[1.0 T10] Read existing project data without migration #186

Problem and outcome

Read supported customer project data without another mandatory migration. A customer updates the plugin, reopens the project, and continues working. Compatibility belongs in readers from T2 onward; this task verifies the complete runtime, skills, and site contract.

Interaction contract

Keep FluencyLoop. Proposed positioning: Stay fluent as people and agents evolve the product.

Use retained product reasoning automatically. Explain consequential choices at the right depth. Recommend a path. Continue within agreed intent. Ask when human judgment is needed. Update the shared model at natural boundaries.

The flagship goal/principles/precedents/tradeoffs reasoning is integrated into the existing design explanation at proportional depth. It is not a mandatory recital, proposal form, or new approval exchange. People must remain able to understand and challenge the design.

Scope

• Read existing 0.3 JSONL and supported earlier Markdown where they are, using compatibility adapters. No mandatory copying, moving, rewriting, or bulk-appending of customer knowledge. An additive history reconstruction is still a migration.
• Resolve legacy identities at read time without backfilling IDs, goals, lifecycle, or approval metadata. Derive deterministic references from existing logical identities where possible; expose ambiguity otherwise. New work may reference legacy decisions and append replacement links when a real choice changes.
• Keep old and new records usable together. Existing feature explanations remain readable in Changes without a new proposal or goal association. Missing historical information stays explicitly unknown.
• Make startup, project opening, context/check reads, and site browsing read-only with respect to project knowledge, including tracked and untracked artifacts. Runtime process state and normal new-work writes are separate concerns.
• Remove the current skills' mandatory repository-wide semantic-assessment prerequisite from normal workflows. Pending legacy-assessment markers must not trigger a history sweep or prevent starting a task.
• Keep historical enrichment a separate, explicitly requested action on selected material. Do not infer enrichment authorization from a plugin update or missing new fields; preserve originals and provenance.
• Separate product version from data-format version. A 1.0 product release does not itself require a schema bump. Document supported inputs and return honest diagnostics for malformed/unsupported data without automatic conversion or repair.
• Cover Bash, PowerShell, both agent entry paths, and the local site. Document forward recovery for runtime failures without promising client pinning/downgrade capabilities.

Acceptance criteria

• A populated existing project works and remains browsable immediately after a plugin update without a conversion command, history sweep, strategy workshop, or retrospective approvals.
• Update/start/context/check/site-read sequences leave the complete project-knowledge file set and bytes unchanged, including no newly generated enrichment records or untracked knowledge artifacts. Repeated reads remain unchanged.
• Both existing 0.3 records and supported earlier Markdown are read without rerunning an importer solely for the new runtime or site.
• Mixed old/new records resolve correctly. A new decision can reference an old logical identity without rewriting or assigning IDs across history first.
• Absent brief, goal, lifecycle, original proposal, and approval metadata remain usable unknowns; no intent or approval is fabricated.
• A pending legacy semantic-assessment marker cannot force repository-wide reconstruction or block ordinary authorized work in either agent workflow.
• Only an explicit enrichment request permits changes to the selected historical knowledge; normal new work may write its own records at natural boundaries without converting the old store.
• Product-version changes alone do not advance the stored-data format; malformed/unsupported input receives a non-mutating diagnostic.

Validation

Add Bats/Pester fixtures and shared reader cases for populated 0.3 stores, supported older Markdown, mixed-format histories, pending semantic-assessment markers, absent briefs, and partial/unknown metadata. Snapshot the entire knowledge tree, including file paths and bytes, before and after repeated update/start/context/check/site-read sequences. Assert zero writes, not merely preservation of original files; protect against additive bulk reconstruction too.

Separately exercise normal new work referencing old decisions and an explicitly requested, narrowly scoped enrichment. Verify originals/provenance survive and no unrelated history changes. Check both distributed skill entry paths for removal of the mandatory assessment gate, run the core without Node, and verify Bash/PowerShell/site resolution parity. This planning issue specifies future validation; no migration or customer-data changes are authorized by editing it.

Starting points

scripts/{bash,powershell}/common.*, check.*, import-legacy.*, migrate.*, startup hooks, both plan/feature skill distributions, site/server.js record readers and identity resolver; tests/import-legacy.bats, tests/site.bats, tests/node-optional.bats, and PowerShell mirrors. Replace import-on-read and skill assessment prerequisites where present rather than scheduling another compulsory migration.

Constraints

• Target dev; main distributes releases. No runtime implementation occurs in the planning PR.
• T1 is an observed pilot using existing artifacts before new infrastructure. Use its evidence to retain, narrow, or defer later scope.
• Recommend and continue within authorized intent; ask with a recommendation only for consequential unresolved judgment. Batch independent questions, reuse settled answers, and wait for dependent work. Silence is not approval.
• Absent briefs, historical link gaps, stale prose, and unreviewed metadata alone are advisory. Do not require onboarding, cleanup, or retrospective approvals to work.
• Unknown familiarity is not fluency and does not automatically require a blocking probe/check. Support requested guided learning without quizzes; keep calibration/preferences private. T5 explicitly updates inherited pause rules.
• Capture rationale once, link mechanical views, record outcome deviations at natural closure, distill once at wrap-up, and reuse unchanged context.
• Preserve append-only history/provenance; Bash and PowerShell implement the same contract. Core remains Node-optional; no new database, hosted service, or vector search.

Dependencies and size

• Task: T10
• Relative size: M (not a calendar estimate)
• Depends on: T3: [1.0 T3] Assemble bounded design context in Bash and PowerShell #179, T4: [1.0 T4] Link existing design rationale and capture outcome deviations once #180, T6: [1.0 T6] Reconcile implementation and update review/backfill workflows #182
• Milestone: https://github.com/baokhang83/fluencyloop/milestone/3
• Plan: draft source
• Planning PR: docs: propose FluencyLoop 1.0 shared product direction and design #189