forgetrail 0.5.7 → 0.5.9

package/TRACKING_SCHEMA.md

@@ -5,167 +5,9 @@ Phase, decisions, sessions, and gotchas live in **`appledger/`**.
 - **`appledger/profiles/forgetrail.yaml`** holds the current phase instance and criteria. Phase ids are `plan`, `build`, `stabilize`, `iterate`, `refine`, `align`, and `harden`.
 - Decision records, session records, and lesson or question records live under **`appledger/records/`**.
 - Do **not** create or update **`.forgetrail/workflow_tracking.json`**. `.forgetrail/` is hooks and host integration.
-- If that JSON file already exists and its `status` is not `pointer`, run **`appledger migrate preview`**, then apply once. Do not keep a second decision log.
+- If that JSON file already exists and its `status` is not `pointer`, preserve it; current migration is retired. Historical recovery is documented at https://appledger.dev/docs/migration-retirement. Do not keep a second decision log.
 - A file with `"status": "pointer"` and `"record": "appledger/"` is a leftover pointer. Do not add decisions, sessions, or phase status to it.
 
 `getInitialWorkflowTracking` does not return a starter JSON file. `validateTracking` classifies an existing file. It does not accept a legacy document as healthy writable state.
 
-The rest of this file describes the **legacy** Lite and full JSON shapes so an existing file can be recognized and migrated. It is not a template to copy into a new project.
-
-## Legacy phase id vocabulary (Lite vs full)
-
-Both legacy schemas describe the same seven lifecycle phases. **`scripts/forgetrail-dev-launcher.mjs`** can still read either shape. New work uses the profile ids in the table's display-name column.
-
-
-| # | Lite `currentPhase` | MCP `currentPhase` | Display name |
-|---|---------------------|--------------------|--------------|
-| 1 | `1` | `1-architecture` | Plan |
-| 2 | `2` | `2-scaffolding` | Build |
-| 3 | `3` | `3-stabilization` | Stabilize |
-| 4 | `4` | `4-feature-iteration` | Iterate |
-| 5 | `5` | `5-refactoring` | Refine |
-| 6 | `6` | `6-strategic-review` | Align |
-| 7 | `7` | `7-hardening` | Harden |
-
-**Lite (`schemaVersion: "lite-1"`):** numeric `currentPhase`; each phase has **`exitCriteria`** as `{ "flagName": true/false }`. The old copy block is **`FORGETRAIL_LITE.md`** §11. Do not write it into a project.
-
-**Full / MCP:** string `currentPhase`; each phase has **`exitCriteriaMet`** and **`exitCriteriaRemaining`** string arrays. The old sample remains at repo-root **`workflow_tracking.json`** for migration only. `getInitialWorkflowTracking` does not return it.
-
-## Top-Level Fields
-
-### `project`
-
-Static metadata. Set once at project creation (except `status`, which flips at wrap).
-
-```json
-{
-  "name": "My App",
-  "created": "2026-03-12",
-  "description": "One-sentence description",
-  "archetype": "product",
-  "status": "active"
-}
-```
-
-- **`archetype`** — `product` (default) | `internal-tool` | `one-shot`. Set during Phase 1 per **WORKFLOW.md §1d**. When the archetype is not `product`, **prune** non-applicable exit criteria from the phase arrays at bootstrap (e.g. drop payments/business-plan criteria for an internal tool; collapse phases 5–7 into a single polish-and-ship gate for a one-shot). Log the pruning in `decisions[]` so the removal reads as intentional. Do **not** leave inapplicable criteria in place and mark them "N/A" one by one — prune once instead.
-- **`status`** — `active` (default) | `wrapped`. Set to `wrapped` when the project is finished or shelved, after running the **wrap protocol** (WORKFLOW.md §1e): sweep `gotchas[]` + `decisions[]` for generalizable lessons, run the propagation prompt (Harvest mode), add a final `sessions[]` entry with end state and handoff pointers.
-
-### `currentPhase`
-
-String. One of: `1-architecture`, `2-scaffolding`, `3-stabilization`, `4-feature-iteration`, `5-refactoring`, `6-strategic-review`, `7-hardening`.
-
-Note: Phases 4 and 5 can alternate. A project might go 4 -> 5 -> 4 -> 6 -> 4 -> 7. The tracking file reflects reality, not a strict linear path.
-
-### `phases`
-
-Each phase has:
-
-- `status`: `not_started` | `in_progress` | `completed` | `revisiting` (for phases you return to)
-- `startedAt` / `completedAt`: ISO timestamps
-- `exitCriteriaMet`: Array of strings (criteria that have been satisfied)
-- `exitCriteriaRemaining`: Array of strings (criteria not yet met)
-- `notes`: Array of `{ timestamp, text }` objects for anything worth recording during this phase
-
-When Claude believes exit criteria are met, it moves items from `exitCriteriaRemaining` to `exitCriteriaMet` and proposes the phase transition.
-
-### `decisions`
-
-Architectural and design decisions with rationale. **Start logging in Phase 1** alongside **`docs/PHASE_1_BRIEF.md`** so Phase 2 can begin without the Phase 1 chat. After Phase 2, this array stays aligned with **Key Architectural Decisions** in `CONTEXT_PROMPT.md` (which should be populated by merging the brief).
-
-```json
-{
-  "id": "d1",
-  "timestamp": "2026-03-12T10:30:00",
-  "phase": "1-architecture",
-  "session": 1,
-  "decision": "Use PocketBase instead of filesystem storage",
-  "rationale": "Need multi-user support and real-time sync. Filesystem won't scale.",
-  "alternatives_considered": ["SQLite", "Supabase", "No database"],
-  "status": "active"
-}
-```
-
-`status` can be `active`, `superseded` (replaced by a later decision), or `revisit` (flagged for reconsideration). If superseded, add `superseded_by` field with the ID of the replacement decision.
-
-### `gotchas`
-
-Issues, surprises, or traps encountered during development. These persist across sessions so the same mistake isn't repeated.
-
-```json
-{
-  "timestamp": "2026-03-12T14:00:00",
-  "phase": "3-stabilization",
-  "session": 1,
-  "issue": "SvelteKit .env doesn't populate process.env",
-  "resolution": "Use $env/dynamic/private instead",
-  "category": "environment"
-}
-```
-
-Categories: `environment`, `integration`, `data-model`, `ui`, `performance`, `ai-output`, `security`, `tooling`, `other`.
-
-### `sessions`
-
-Log of each session with what was accomplished and where it left off.
-
-```json
-{
-  "session": 1,
-  "date": "2026-03-12",
-  "phasesWorked": ["1-architecture", "2-scaffolding"],
-  "accomplished": ["Confirmed tech stack", "Built full skeleton", "Imported 44 existing jobs"],
-  "leftOff": "App runs but env vars need fixing. Phase 3 next.",
-  "contextLimitHit": false,
-  "approximateLines": 3500
-}
-```
-
-## Update Rules for Claude
-
-1. **After completing a task:** Update the relevant phase's `notes` and move any satisfied exit criteria.
-2. **After making a decision:** Add to `decisions` array with full rationale.
-3. **After hitting a gotcha:** Add to `gotchas` array immediately so it's captured.
-4. **At session end:** Add a session entry to `sessions` array.
-5. **At phase transition:** Update `currentPhase`, set `completedAt` on the old phase, `startedAt` on the new one.
-6. **When revisiting a phase:** Set status to `revisiting`, don't overwrite the original `completedAt`.
-
-## Custom Extensions
-
-Projects may add custom fields to phases as needed. For example, `4-feature-iteration` has an `iterations` array for tracking feature-by-feature progress:
-
-```json
-{
-  "feature": "DOCX tailoring",
-  "status": "complete",
-  "turnsSpent": 8,
-  "approach": "Programmatic placeholder replacement",
-  "notes": "LLM find/replace failed due to Word XML run splitting. Pivoted in turn 6."
-}
-```
-
-Add whatever fields make sense for your project. The schema is a starting point, not a cage.
-
-### `agentContext` (optional, top-level)
-
-Record which agent stack drives the project and what native primitives are available:
-
-```json
-{
-  "primaryAgent": "cursor-agent",
-  "supportsSubagents": true,
-  "supportsPlanMode": true,
-  "lastSessionId": "optional-host-session-id"
-}
-```
-
-### `subagentRuns` (optional, per phase)
-
-Optional array under a phase object to log parallel subagent work (especially Phase 4, 5, 7):
-
-```json
-{
-  "id": "sa-7-security",
-  "description": "Black-hat audit via read-only subagent",
-  "outcome": "12 findings; 2 critical — synthesized into BLACK_HAT_REPORT.md"
-}
-```
+The legacy shapes and starter are retained in ForgeTrail Git history at commit `3863f68e01d6f57823ffbc2a94b626defeef9bfe`. Current hooks and MCP only reject a writable legacy file or identify an inert pointer; they do not validate or translate the retired format.

package/content/FORGETRAIL_LITE.md

@@ -31,7 +31,7 @@ If your host supports hooks (Cursor `hooks.json`, Claude Code `settings.json`),
 
 ## 1. How to use this file
 
-**Humans (first time):** Prefer the repo-root recipe **[TRY_FORGETRAIL.md](../TRY_FORGETRAIL.md)**: Genesis spec in any chat app, then this Lite file, then one kickoff line to your coding agent. No MCP required.
+**Humans (first time):** Prefer the upstream ForgeTrail recipe **[TRY_FORGETRAIL.md](https://github.com/Catalyst-Forge-LLC/forgetrail/blob/main/TRY_FORGETRAIL.md)**: Genesis spec in any chat app, then this Lite file, then one kickoff line to your coding agent. The recipe lives in the upstream repository; Lite installation does not place it in your app root. No MCP required.
 
 **Option A — drop-in file (preferred).** Save this doc in **`.forgetrail/FORGETRAIL_LITE.md`** (see §1.5). You may commit `.forgetrail/` (same Apache 2.0 license) or gitignore it for a cleaner public app history — see §1.5. Most agents will read it when cited (e.g. *"follow `.forgetrail/FORGETRAIL_LITE.md`"*). Then save the **AGENTS.md snippet** from §12 as **`.forgetrail/AGENTS.md`**. Symlink or copy `.forgetrail/cursor/rules/*.mdc` into `.cursor/rules/` so Cursor loads them (§1.5). If you already have a product idea, pair this file with **`docs/GENESIS.md`** (see TRY_FORGETRAIL.md and `content/GENESIS_SPEC_PROMPT.md`).
 
@@ -945,55 +945,9 @@ Keep it **short** — this is a map, not a monograph. If it grows past ~200 line
 
 ---
 
-## 11. Legacy `.forgetrail/workflow_tracking.json` (do not copy)
+## 11. AppLedger record
 
-Do **not** write this into a project. It is the old Lite shape. `appledger migrate` reads it when a project already has the file. New projects start at `appledger/`.
-
-**Lite vs MCP tracking:** Lite uses **`schemaVersion: "lite-1"`**, numeric **`currentPhase`** (`1`–`7`), and per-phase **`exitCriteria`** objects (boolean flags). The full MCP starter uses string phase keys (`1-architecture`, …) and **`exitCriteriaMet`** / **`exitCriteriaRemaining`** arrays — see **`TRACKING_SCHEMA.md`** (phase ID map + both shapes). **`scripts/forgetrail-dev-launcher.mjs`** `status` understands both.
-
-```json
-{
-  "schemaVersion": "lite-1",
-  "project": {
-    "name": "<project name>",
-    "created": "<YYYY-MM-DD>",
-    "description": "<one-line description>",
-    "sourceControl": "git",
-    "archetype": "product",
-    "status": "active"
-  },
-  "currentPhase": 1,
-  "phases": {
-    "1": { "name": "Plan", "status": "in_progress", "exitCriteria": { "phase1BriefLocked": false, "stackLocked": false, "heroFlowAgreed": false, "v1ScopeAgreed": false } },
-    "2": { "name": "Build", "status": "pending", "exitCriteria": { "runnableSpine": false, "heroFlowEndToEnd": false, "contextPromptWritten": false } },
-    "3": { "name": "Stabilize", "status": "pending", "exitCriteria": {} },
-    "4": { "name": "Iterate", "status": "pending", "exitCriteria": {} },
-    "5": { "name": "Refine", "status": "pending", "exitCriteria": {} },
-    "6": { "name": "Align", "status": "pending", "exitCriteria": {} },
-    "7": { "name": "Harden", "status": "pending", "exitCriteria": {} }
-  },
-  "decisions": [],
-  "gotchas": [],
-  "sessions": [],
-  "openQuestions": []
-}
-```
-
-**Entry shapes** (append-only; include **`phase`** when the decision belongs to a specific lifecycle phase):
-
-```json
-// decisions[] — date, phase, decision, why, alternatives (alternatives may be [])
-{ "date": "2026-04-22", "phase": 1, "decision": "Stack: SvelteKit + PocketBase", "why": "single-binary DB, fast spine", "alternatives": ["Next+Postgres"] }
-
-// gotchas[]
-{ "date": "2026-04-22", "phase": 2, "gotcha": "sv create hung: Directory not empty. Continue?", "fix": "Lite root is never empty by step 10; use manual scaffold (§4.2 step 10 A.1) or sv create into a new empty subfolder (app/); kill stuck process" }
-{ "date": "2026-04-22", "phase": 2, "gotcha": "sv create hangs on Tailwind plugin prompt", "fix": "pass --no-add-ons or explicit --tailwindcss=plugins:none" }
-{ "date": "2026-04-22", "phase": 2, "gotcha": "port 8090 already in use by background process", "fix": "configured PUBLIC_POCKETBASE_URL with port 8096 in .env" }
-{ "date": "2026-04-23", "phase": 2, "gotcha": "tar -xf on Windows: (a) 'Cannot connect to Z: resolve failed' — bsdtar parses drive letters as remote host; (b) 'This does not look like a tar archive' — GNU tar from Git Bash shadowed bsdtar on PATH", "fix": "On win32 branch: PowerShell Expand-Archive (or C:\\Windows\\System32\\tar.exe by absolute path) with cwd + basename, not full X:\\... path; see §13 Engineering" }
-
-// sessions[]
-{ "date": "2026-04-22", "phase": 2, "summary": "wired auth + hero route end-to-end", "nextSession": "seed data + first export" }
-```
+Project phase, decisions, lessons, and sessions live in `appledger/`. Read its manifest, the ForgeTrail profile, and the latest session. Do not create a legacy `workflow_tracking.json`. The old tracking shapes are retained in Git history, not shipped as starter templates. Historical recovery is documented at https://appledger.dev/docs/migration-retirement.
 
 ---
 

package/content/cursor-rules/forgetrail-phase-status.mdc

@@ -5,7 +5,7 @@ alwaysApply: true
 
 # ForgeTrail phase awareness
 
-This repo uses **ForgeTrail**. **Source of truth:** `appledger/profiles/forgetrail.yaml` and the latest session record. If a legacy `.forgetrail/workflow_tracking.json` exists and is not a pointer, it is a legacy conflict: run `appledger migrate preview`, then apply.
+This repo uses **ForgeTrail**. **Source of truth:** `appledger/profiles/forgetrail.yaml` and the latest session record. If a legacy `.forgetrail/workflow_tracking.json` exists and is not a pointer, it is a legacy conflict: preserve the file and follow the historical recovery procedure at https://appledger.dev/docs/migration-retirement. Current migration is retired.
 
 ## When to surface status
 

package/content/forgetrail-workspace-README.md

@@ -11,7 +11,7 @@ Used for **both** ForgeTrail Lite file bootstrap and **MCP greenfield** kickoff.
 | `hooks/` | Host safety hooks. They do not store project phase or decisions |
 | `FORGETRAIL_LITE.md` | Full Lite kickoff protocol (Lite file bootstrap only) |
 | `FORGETRAIL_LITE_UPDATES.md` | Optional local feedback log (§1.6) — merge accepted items upstream |
-| `AGENTS.md` | Agent instructions — cite or symlink for your IDE |
+| `AGENTS.md` | Created by the agent in the first kickoff session from Lite §12; absent immediately after installation. Cite or symlink it for your IDE after creation |
 | `CLAUDE.md` | Claude Code instructions |
 | `IDEAS.md` | Backlog parking lot |
 | `cursor/rules/*.mdc` | Cursor rule snippets (updates-log, …) |
@@ -34,8 +34,8 @@ mkdir .cursor\rules 2>nul
 mklink .cursor\rules\forgetrail-updates-log.mdc ..\.forgetrail\cursor\rules\forgetrail-updates-log.mdc
 ```
 
-Optional: symlink `.forgetrail/AGENTS.md` → `AGENTS.md` at repo root if a tool requires root placement (also gitignore root copies if you symlink).
+After the first kickoff creates `.forgetrail/AGENTS.md` from Lite §12, optionally symlink it → `AGENTS.md` at repo root if a tool requires root placement (also gitignore root copies if you symlink).
 
 ## Recovering after clone
 
-If `.forgetrail/` was gitignored, it is not in git. Copy from upstream Catalyst Forge (`content/`) or restore from backup; MCP-only projects can recreate tracking via **`getInitialWorkflowTracking`**.
+If `.forgetrail/` was gitignored, it is not in git. Reinstall ForgeTrail, copy its host artifacts from upstream Catalyst Forge (`content/`), or restore them from backup. Restore any project-specific agent instructions from backup or recreate them during kickoff. The existing **`appledger/`** remains the authoritative project record; restoring host artifacts does not replace it. For a new empty project, use **`appledger init`**. MCP **`getInitialWorkflowTracking`** returns ledger guidance, not a tracking file or a replacement ledger.

package/content/hooks/session-start.mjs

@@ -74,7 +74,7 @@ function main() {
         lines.push("=== Legacy tracking conflict ===");
         lines.push("workflow_tracking.json is not the system of record.");
         lines.push("Do not add decisions, sessions, or phase status to it.");
-        lines.push("Run `appledger migrate preview`, then apply once, and write only in appledger/.");
+        lines.push("Legacy migration is retired. Preserve the legacy file; use an isolated copy and the historical AppLedger revision for recovery. See https://appledger.dev/docs/migration-retirement.");
       }
     } catch {
       lines.push("workflow_tracking.json could not be read. Do not recreate it. Use appledger/.");

package/content/hooks/session-stop.mjs

@@ -125,7 +125,7 @@ function main() {
     console.log(
       JSON.stringify({
         followup_message:
-          "ForgeTrail reminder: workflow_tracking.json is a legacy file. Do not append sessions to it. Run `appledger migrate preview`, then apply, and record this session in appledger/.",
+          "ForgeTrail reminder: workflow_tracking.json is a legacy file. Do not append sessions to it. Legacy migration is retired. Preserve the legacy file; recover from the historical AppLedger revision in an isolated copy. Record current sessions in appledger/.",
       })
     );
     return;

package/content/hooks/validate-tracking-core.mjs

@@ -1,262 +1,20 @@
-/**
- * Structural validation for .forgetrail/workflow_tracking.json (MCP full + Lite shapes).
- * Standalone zero-dependency module for ForgeTrail hooks and MCP.
- */
-
-const VALID_MCP_PHASES = [
-  "1-architecture",
-  "2-scaffolding",
-  "3-stabilization",
-  "4-feature-iteration",
-  "5-refactoring",
-  "6-strategic-review",
-  "7-hardening",
-];
-
-const VALID_LITE_PHASES = ["1", "2", "3", "4", "5", "6", "7"];
-
-const VALID_GOTCHA_CATEGORIES = new Set([
-  "environment",
-  "integration",
-  "data-model",
-  "ui",
-  "performance",
-  "ai-output",
-  "security",
-  "tooling",
-  "other",
-]);
-
-const VALID_DECISION_STATUS = new Set(["active", "superseded", "revisit"]);
-
-const VALID_PHASE_STATUS = new Set([
-  "not_started",
-  "pending",
-  "in_progress",
-  "completed",
-  "revisiting",
-]);
-
-function isLiteSchema(data) {
-  return data && data.schemaVersion === "lite-1";
-}
-
-const LEGACY_TRACKING_ISSUE =
-  "Legacy writable tracking is not the system of record. Do not add decisions, sessions, or phase status to this file. Run `appledger migrate preview`, then apply once, and write only in appledger/.";
-
-const POINTER_WARNING =
-  "This file is a pointer to appledger/. Do not add decisions, sessions, or phase status here.";
-
-function isPointer(data) {
-  return data.status === "pointer" && typeof data.record === "string" && data.record.replaceAll("\\", "/").includes("appledger");
-}
-
-function isLegacyTracking(data) {
-  return (
-    "currentPhase" in data ||
-    "phases" in data ||
-    "decisions" in data ||
-    "sessions" in data ||
-    "schemaVersion" in data
-  );
-}
-
+/** Diagnose retired tracking files. Current project records live in appledger/. */
 export function validateTrackingData(data) {
-  const issues = [];
-  const warnings = [];
-
-  if (!data || typeof data !== "object") {
-    issues.push("Tracking data is empty or not an object.");
-    return { issues, warnings };
-  }
-
-  if (isPointer(data)) {
-    warnings.push(POINTER_WARNING);
-    return { issues, warnings };
-  }
-
-  if (isLegacyTracking(data)) {
-    issues.push(LEGACY_TRACKING_ISSUE);
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return { issues: ['Tracking data is empty or not an object.'], warnings: [] };
   }
-
-  const project = data.project;
-  if (!project || typeof project !== "object") {
-    issues.push("Missing top-level project object.");
-  } else if (!project.name || typeof project.name !== "string" || !project.name.trim()) {
-    issues.push("project.name is missing or empty.");
-  }
-
-  if (!data.currentPhase) {
-    issues.push("Missing currentPhase.");
-  }
-
-  const lite = isLiteSchema(data);
-  const currentPhase = data.currentPhase;
-
-  if (currentPhase) {
-    if (lite) {
-      const phaseStr = String(currentPhase);
-      if (!VALID_LITE_PHASES.includes(phaseStr)) {
-        issues.push(
-          `Lite schema currentPhase "${phaseStr}" is not a valid phase number (1–7).`
-        );
-      }
-    } else if (
-      typeof currentPhase === "string" &&
-      !VALID_MCP_PHASES.includes(currentPhase)
-    ) {
-      issues.push(
-        `currentPhase "${currentPhase}" is not a recognized MCP phase id (e.g. "1-architecture").`
-      );
-    }
+  if (data.status === 'pointer' && typeof data.record === 'string' && data.record.replaceAll('\\', '/').includes('appledger')) {
+    return { issues: [], warnings: ["This file is a pointer to appledger/. Do not add decisions, sessions, or phase status here."] };
   }
-
-  const phases = data.phases;
-  if (!phases || typeof phases !== "object") {
-    issues.push("Missing phases object.");
-    return { issues, warnings };
-  }
-
-  const phaseKeys = Object.keys(phases);
-  if (phaseKeys.length === 0) {
-    issues.push("No phases defined in tracking.");
-  }
-
-  if (!lite && currentPhase && typeof currentPhase === "string" && !phaseKeys.includes(currentPhase)) {
-    issues.push(`currentPhase "${currentPhase}" is not a key in phases.`);
-  }
-
-  for (const [key, rawPhase] of Object.entries(phases)) {
-    if (!rawPhase || typeof rawPhase !== "object") {
-      issues.push(`phases["${key}"] is not an object.`);
-      continue;
-    }
-    const phase = rawPhase;
-
-    if (phase.status && !VALID_PHASE_STATUS.has(String(phase.status))) {
-      warnings.push(
-        `phases["${key}"].status "${phase.status}" is not a standard value (not_started | in_progress | completed | revisiting).`
-      );
-    }
-
-    if (lite) {
-      if (phase.exitCriteria !== undefined && (typeof phase.exitCriteria !== "object" || phase.exitCriteria === null)) {
-        issues.push(`phases["${key}"].exitCriteria should be an object of boolean flags (Lite schema).`);
-      }
-    } else {
-      if (phase.exitCriteriaMet !== undefined && !Array.isArray(phase.exitCriteriaMet)) {
-        issues.push(`phases["${key}"].exitCriteriaMet should be an array.`);
-      }
-      if (phase.exitCriteriaRemaining !== undefined && !Array.isArray(phase.exitCriteriaRemaining)) {
-        issues.push(`phases["${key}"].exitCriteriaRemaining should be an array.`);
-      }
-      const met = phase.exitCriteriaMet ?? [];
-      const remaining = phase.exitCriteriaRemaining ?? [];
-      if (Array.isArray(met) && Array.isArray(remaining)) {
-        const overlap = met.filter((item) => remaining.includes(item));
-        if (overlap.length > 0) {
-          warnings.push(
-            `phases["${key}"] has exit criteria in both Met and Remaining: ${overlap.slice(0, 3).join("; ")}${overlap.length > 3 ? "…" : ""}`
-          );
-        }
-      }
-    }
-
-    const subagentRuns = phase.subagentRuns;
-    if (subagentRuns !== undefined && !Array.isArray(subagentRuns)) {
-      issues.push(`phases["${key}"].subagentRuns should be an array when present.`);
-    }
-  }
-
-  const decisions = data.decisions;
-  if (decisions !== undefined) {
-    if (!Array.isArray(decisions)) {
-      issues.push("decisions should be an array.");
-    } else {
-      const seenIds = new Set();
-      for (let i = 0; i < decisions.length; i++) {
-        const d = decisions[i];
-        if (!d || typeof d !== "object") {
-          issues.push(`decisions[${i}] is not an object.`);
-          continue;
-        }
-        if (!d.decision || typeof d.decision !== "string") {
-          issues.push(`decisions[${i}] missing decision text.`);
-        }
-        if (!d.rationale || typeof d.rationale !== "string") {
-          warnings.push(`decisions[${i}] missing rationale (recommended for Phase 1 handoff).`);
-        }
-        if (d.id && typeof d.id === "string") {
-          if (seenIds.has(d.id)) {
-            issues.push(`Duplicate decisions id "${d.id}".`);
-          }
-          seenIds.add(d.id);
-        }
-        if (d.status && !VALID_DECISION_STATUS.has(String(d.status))) {
-          warnings.push(`decisions[${i}].status "${d.status}" is not standard (active | superseded | revisit).`);
-        }
-        if (
-          d.alternatives_considered !== undefined &&
-          !Array.isArray(d.alternatives_considered)
-        ) {
-          warnings.push(`decisions[${i}].alternatives_considered should be an array when present.`);
-        }
-      }
-    }
-  }
-
-  const gotchas = data.gotchas;
-  if (gotchas !== undefined) {
-    if (!Array.isArray(gotchas)) {
-      issues.push("gotchas should be an array.");
-    } else {
-      for (let i = 0; i < gotchas.length; i++) {
-        const g = gotchas[i];
-        if (!g || typeof g !== "object") {
-          issues.push(`gotchas[${i}] is not an object.`);
-          continue;
-        }
-        if (!g.issue || typeof g.issue !== "string") {
-          warnings.push(`gotchas[${i}] missing issue description.`);
-        }
-        if (!g.resolution || typeof g.resolution !== "string") {
-          warnings.push(`gotchas[${i}] missing resolution.`);
-        }
-        if (g.category && !VALID_GOTCHA_CATEGORIES.has(String(g.category))) {
-          warnings.push(
-            `gotchas[${i}].category "${g.category}" is not a standard category (environment, integration, …).`
-          );
-        }
-      }
-    }
-  }
-
-  const sessions = data.sessions;
-  if (sessions !== undefined && !Array.isArray(sessions)) {
-    issues.push("sessions should be an array when present.");
-  }
-
-  return { issues, warnings };
+  return { issues: ["Legacy writable tracking is not the system of record. Legacy migration is retired. Preserve the file; historical recovery uses an isolated copy and AppLedger commit fb7939c0f4d811930adb9cfd4bfd0c6766638a44. Write current decisions, sessions, and phase only in appledger/."], warnings: [] };
 }
 
 export function formatValidationResult(result) {
-  const { issues, warnings } = result;
-
-  if (issues.length === 0 && warnings.length === 0) {
-    return "No workflow_tracking.json is required. Project state lives in appledger/.";
-  }
-
-  if (issues.length === 0 && warnings.every((item) => item.includes("pointer"))) {
-    return "Pointer accepted. Project state lives in appledger/.\n\n" + warnings.map((item) => `- ${item}`).join("\n");
+  if (result.issues.length === 0 && result.warnings.length === 0) {
+    return 'No workflow_tracking.json is required. Project state lives in appledger/.';
   }
-
-  const parts = [];
-  if (issues.length > 0) {
-    parts.push("Issues (fix these):\n" + issues.map((i) => `- ${i}`).join("\n"));
-  }
-  if (warnings.length > 0) {
-    parts.push("Warnings:\n" + warnings.map((w) => `- ${w}`).join("\n"));
+  if (result.issues.length === 0) {
+    return 'Pointer accepted. Project state lives in appledger/.\n\n' + result.warnings.map(item => '- ' + item).join('\n');
   }
-
-  return parts.join("\n\n");
+  return 'Issues (fix these):\n' + result.issues.map(item => '- ' + item).join('\n');
 }

package/content/scripts/forgetrail-dev-launcher.mjs

@@ -5,7 +5,7 @@
  *
  * Commands: setup | run | status
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
@@ -13,52 +13,8 @@ import { spawn } from "node:child_process";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const repoRoot = join(__dirname, "..");
 const trackingPath = join(repoRoot, ".forgetrail", "workflow_tracking.json");
-const progressPath = join(repoRoot, "docs", "FORGETRAIL_PROGRESS.md");
 const isWin = process.platform === "win32";
 
-const PHASE_LABELS = {
-  // Display names — see TRACKING_SCHEMA.md "Phase ID vocabulary (Lite vs MCP)"
-  "1": "Plan",
-  "2": "Build",
-  "3": "Stabilize",
-  "4": "Iterate",
-  "5": "Refine",
-  "6": "Align",
-  "7": "Harden",
-  "1-architecture": "Plan",
-  "2-scaffolding": "Build",
-  "3-stabilization": "Stabilize",
-  "4-feature-iteration": "Iterate",
-  "5-refactoring": "Refine",
-  "6-strategic-review": "Align",
-  "7-hardening": "Harden",
-};
-
-/** Lite schema: exitCriteria { key: boolean }. MCP schema: exitCriteriaMet / exitCriteriaRemaining arrays. */
-function getExitCriteriaStatus(phaseBlock) {
-  if (!phaseBlock) return { met: [], remaining: [] };
-
-  if (Array.isArray(phaseBlock.exitCriteriaMet) || Array.isArray(phaseBlock.exitCriteriaRemaining)) {
-    return {
-      met: Array.isArray(phaseBlock.exitCriteriaMet) ? phaseBlock.exitCriteriaMet : [],
-      remaining: Array.isArray(phaseBlock.exitCriteriaRemaining) ? phaseBlock.exitCriteriaRemaining : [],
-    };
-  }
-
-  const criteria = phaseBlock.exitCriteria;
-  if (criteria && typeof criteria === "object" && !Array.isArray(criteria)) {
-    const met = [];
-    const remaining = [];
-    for (const [key, value] of Object.entries(criteria)) {
-      if (value) met.push(key);
-      else remaining.push(key);
-    }
-    return { met, remaining };
-  }
-
-  return { met: [], remaining: [] };
-}
-
 function run(cmd, args, opts = {}) {
   return new Promise((resolve, reject) => {
     const p = spawn(cmd, args, { stdio: "inherit", cwd: repoRoot, shell: isWin, ...opts });
@@ -142,70 +98,16 @@ async function cmdRun() {
 }
 
 function renderProgress() {
-  if (!existsSync(trackingPath)) {
-    return {
-      text: "Phase state: appledger/profiles/forgetrail.yaml.",
-      md: null,
-    };
-  }
-  const t = JSON.parse(readFileSync(trackingPath, "utf8"));
-  const record = typeof t.record === "string" ? t.record.replaceAll("\\", "/") : "";
-  if (t.status === "pointer" && record.includes("appledger")) {
-    return {
-      text: "workflow_tracking.json is a pointer to appledger/. Read appledger/profiles/forgetrail.yaml.",
-      md: null,
-    };
-  }
-  const phase = t.currentPhase ?? "?";
-  const phaseId = String(phase);
-  const phaseBlock = t.phases?.[phaseId];
-  const label = PHASE_LABELS[phaseId] || phaseBlock?.name || `Phase ${phase}`;
-  const status = phaseBlock?.status || "unknown";
-  const { met, remaining } = getExitCriteriaStatus(phaseBlock);
-  const lines = [
-    `ForgeTrail phase: ${label} (${phaseId}) — ${status}`,
-    "",
-    met.length ? "Done (this phase):" : "",
-    ...met.map((k) => `  ✓ ${k}`),
-    met.length ? "" : "",
-    remaining.length ? "Still open:" : "Exit criteria for this phase look complete (confirm before advancing):",
-    ...remaining.map((k) => `  - ${k}`),
-  ];
-  if (t.sessions?.length) {
-    const last = t.sessions[t.sessions.length - 1];
-    lines.push("", `Last session: ${last.date} — ${last.summary || "(no summary)"}`);
-  }
-  const md = [
-    "# ForgeTrail progress",
-    "",
-    "_Human-readable snapshot read from a legacy workflow_tracking.json. After migrate, the source of truth is `appledger/profiles/forgetrail.yaml`._",
-    "",
-    `**Current phase:** ${label} (\`${phaseId}\`) — **${status}**`,
-    "",
-    "## What's done (this phase)",
-    "",
-    ...(met.length ? met.map((k) => `- [x] ${k}`) : ["- _(none marked met yet)_"]),
-    "",
-    "## Still to do (this phase)",
-    "",
-    ...(remaining.length ? remaining.map((k) => `- [ ] ${k}`) : ["- _(none listed — verify before advancing)_"]),
-    "",
-    "## Refresh",
-    "",
-    "Double-click **status.bat** (Windows) or run **./status.sh** / **pnpm run forgetrail:status** anytime.",
-    "",
-  ].join("\n");
-  return { text: lines.join("\n"), md };
+  if (!existsSync(trackingPath)) return 'Phase state: appledger/profiles/forgetrail.yaml.';
+  try {
+    const tracking = JSON.parse(readFileSync(trackingPath, 'utf8'));
+    if (tracking.status === 'pointer') return 'Project state: appledger/profiles/forgetrail.yaml.';
+  } catch {}
+  return 'Legacy tracking conflict. Preserve the file. Current migration is retired; use historical recovery in an isolated copy. Project state belongs in appledger/.';
 }
 
 function cmdStatus() {
-  const { text, md } = renderProgress();
-  console.log(text);
-  if (md) {
-    mkdirSync(join(repoRoot, "docs"), { recursive: true });
-    writeFileSync(progressPath, md, "utf8");
-    console.log(`\nWrote ${progressPath}`);
-  }
+  console.log(renderProgress());
 }
 
 const cmd = process.argv[2];

package/docs/NPM.md

@@ -10,12 +10,26 @@ Two public unscoped packages:
 
 | Package | This tree | On npm until you publish | From | What it is |
 | --- | --- | --- | --- | --- |
-| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.5.5 | 0.5.5 | repo root | CLI + Lite + templates. `pnpm dlx forgetrail install --lite` |
-| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.4.3 | 0.4.3 | `mcp-server/` | MCP bin. Depends on `forgetrail` for content. `pnpm dlx forgetrail-mcp` |
+| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.5.8 | 0.5.7 | repo root | CLI + Lite + templates. `pnpm dlx forgetrail install --lite` |
+| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.4.4 | 0.4.3 | `mcp-server/` | MCP bin. Depends on `forgetrail` for content. `pnpm dlx forgetrail-mcp` |
 
 These are **installer and MCP channels**, not a library. App repos should not add `forgetrail` to `dependencies`.
 
-`forgetrail@0.5.5` and `forgetrail-mcp@0.4.3` are on npm and match these `package.json` versions as of 2026-09-29. A later content change needs a version bump before it publishes. `getCompanionSuggestions` reads its text from the installed `forgetrail`. `pnpm run pack:check` is the gate. It does not publish.
+The registry versions above were checked on 2026-09-30. The new tree versions are prepared and unpublished. `getCompanionSuggestions` reads its text from the installed `forgetrail`. `pnpm run pack:check` is the gate. It does not publish.
+
+## September ecosystem release
+
+The CLI release removes writable legacy tracking templates and structural compatibility readers, preserves ledger pointer/conflict diagnosis, and clarifies when an agent creates AGENTS.md. AppLedger remains the application record; its completed one-time migration is retired separately.
+
+Publish CLI `0.5.8` first. Before publishing MCP `0.4.4`, update its dependency and lockfile to require the new content:
+
+```powershell
+Set-Location Z:\workspace\forgetrail\mcp-server
+pnpm add "forgetrail@^0.5.8"
+pnpm build
+```
+
+Review and commit those files, then test the packaged MCP against that dependency. This update is pending until CLI `0.5.8` exists in the registry; the currently installed/locked dependency is still `0.5.2`. Do not publish the MCP preparation unchanged. Preserve independent package versions.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgetrail",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "private": false,
   "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
   "license": "Apache-2.0",
@@ -15,7 +15,6 @@
     "prompts/",
     "WORKFLOW.md",
     "TRACKING_SCHEMA.md",
-    "workflow_tracking.json",
     "INITIAL_PROMPT.md",
     "CONTINUATION_PROMPT.md",
     "TRY_FORGETRAIL.md",

package/scripts/tracking-cutover.test.mjs

@@ -28,7 +28,7 @@ test("a legacy tracking document is a conflict", () => {
     sessions: [],
   });
   assert.match(result.issues.join("\n"), /not the system of record/);
-  assert.match(result.issues.join("\n"), /appledger migrate preview/);
+  assert.match(result.issues.join("\n"), /Legacy migration is retired/);
 });
 
 test("install does not create workflow_tracking.json", () => {
@@ -160,11 +160,11 @@ test("an edit under appledger/ runs check and reports a warning", () => {
 
 test("Lite and workflow instructions name the ledger", () => {
   const lite = readFileSync(join(root, "content", "FORGETRAIL_LITE.md"), "utf8");
-  const legacyAt = lite.indexOf("## 11. Legacy");
+  const legacyAt = lite.indexOf("## 11. AppLedger record");
   const resumeAt = lite.indexOf("## 12. `AGENTS.md`");
   assert.ok(legacyAt > 0 && resumeAt > legacyAt);
   const instructional = `${lite.slice(0, legacyAt)}\n${lite.slice(resumeAt)}`;
-  assert.match(lite.slice(legacyAt, resumeAt), /"schemaVersion": "lite-1"/);
+  assert.doesNotMatch(lite, /"schemaVersion": "lite-1"/);
   assert.match(instructional, /ForgeTrail Lite v2\.2\.2/);
   for (const line of instructional.split("\n")) {
     if (!line.includes("workflow_tracking.json")) continue;

package/scripts/workspace-index.mjs

@@ -55,33 +55,10 @@ function scanWorkspace(workspaceRoot) {
     if (trackingPath) {
       try {
         const tracking = JSON.parse(readFileSync(trackingPath, "utf-8"));
-        projectName = tracking.project?.name || entry;
-        phase = String(tracking.currentPhase || "-");
-        archetype = tracking.project?.archetype || "product";
-
-        if (Array.isArray(tracking.sessions) && tracking.sessions.length > 0) {
-          const s = tracking.sessions[tracking.sessions.length - 1];
-          const date = s.date || s.timestamp?.slice(0, 10) || "";
-          const note = s.leftOff ? ` (${s.leftOff.slice(0, 30)}...)` : "";
-          lastSession = date ? `${date}${note}` : "-";
-        }
-
-        const isLite = tracking.schemaVersion === "lite-1";
-        if (isLite) {
-          const pObj = tracking.phases?.[phase];
-          if (pObj?.exitCriteria) {
-            openCriteriaCount = Object.values(pObj.exitCriteria).filter((v) => !v).length;
-          }
-        } else {
-          const pObj = tracking.phases?.[phase];
-          if (Array.isArray(pObj?.exitCriteriaRemaining)) {
-            openCriteriaCount = pObj.exitCriteriaRemaining.length;
-          }
-        }
         if (tracking.status === "pointer") {
           phase = ledger ? "appledger" : "pointer";
         } else if (tracking.currentPhase || tracking.phases) {
-          phase = ledger ? `legacy+${phase}` : `legacy:${phase}`;
+          phase = "legacy conflict";
         }
       } catch {}
     }

package/workflow_tracking.json

@@ -1,125 +0,0 @@
-{
-  "project": {
-    "name": "",
-    "created": "",
-    "description": "",
-    "archetype": "product",
-    "status": "active"
-  },
-  "currentPhase": "1-architecture",
-  "phases": {
-    "1-architecture": {
-      "status": "not_started",
-      "startedAt": null,
-      "completedAt": null,
-      "exitCriteriaMet": [],
-      "exitCriteriaRemaining": [
-        "Tech choices confirmed",
-        "Folder structure confirmed",
-        "Data model shape confirmed",
-        "First feature batch defined",
-        "Claude's understanding verified by user",
-        "PHASE_1_BRIEF.md created, complete, and locked (docs/)",
-        "Major decisions recorded in workflow_tracking.json decisions[]"
-      ],
-      "notes": []
-    },
-    "2-scaffolding": {
-      "status": "not_started",
-      "startedAt": null,
-      "completedAt": null,
-      "exitCriteriaMet": [],
-      "exitCriteriaRemaining": [
-        "App runs with pnpm dev",
-        "Real data visible on screen",
-        "Core CRUD works",
-        "Hero flow functions end to end",
-        "CONTEXT_PROMPT.md created and populated by merging PHASE_1_BRIEF.md (then template lessons as needed)",
-        "README.md created (from ForgeTrail template)",
-        "TODO.md created (from ForgeTrail template, seeded from PHASE_1_BRIEF §11)",
-        "IDEAS.md created (from ForgeTrail template)",
-        "Runnable verify script in package.json (types + build or lint) passing cleanly",
-        "Phase 2 doc scope only per WORKFLOW §1a (no premature extra templates)"
-      ],
-      "notes": []
-    },
-    "3-stabilization": {
-      "status": "not_started",
-      "startedAt": null,
-      "completedAt": null,
-      "exitCriteriaMet": [],
-      "exitCriteriaRemaining": [
-        "Environment variables resolve correctly",
-        "APIs return real data",
-        "Core workflow completes without infrastructure errors",
-        "Error messages are human-readable (not just status codes)"
-      ],
-      "notes": []
-    },
-    "4-feature-iteration": {
-      "status": "not_started",
-      "startedAt": null,
-      "completedAt": null,
-      "exitCriteriaMet": [],
-      "exitCriteriaRemaining": ["Core value proposition delivered", "Hero flow works with real data including edge cases", "Features tested beyond happy path"],
-      "notes": [],
-      "iterations": []
-    },
-    "5-refactoring": {
-      "status": "not_started",
-      "startedAt": null,
-      "completedAt": null,
-      "exitCriteriaMet": [],
-      "exitCriteriaRemaining": [
-        "No file exceeds ~500 lines without justification",
-        "Shared utilities extracted",
-        "No duplicated patterns",
-        "Build passes after each refactor"
-      ],
-      "notes": []
-    },
-    "6-strategic-review": {
-      "status": "not_started",
-      "startedAt": null,
-      "completedAt": null,
-      "exitCriteriaMet": [],
-      "exitCriteriaRemaining": [
-        "BRAND_AND_PRODUCT.md created (from ForgeTrail template)",
-        "TODO reorganized by brand value pillars",
-        "Features mapped to brand pillars",
-        "Gap between brand promise and product identified",
-        "IDEAS.md processed into TODO",
-        "Build order decided"
-      ],
-      "notes": []
-    },
-    "7-hardening": {
-      "status": "not_started",
-      "startedAt": null,
-      "completedAt": null,
-      "exitCriteriaMet": [],
-      "exitCriteriaRemaining": [
-        "CODE_QUALITY.md produced (from ForgeTrail template) and critical findings fixed",
-        "BLACK_HAT_REPORT.md produced (via ForgeTrail security audit) and critical/high findings fixed",
-        "All findings triaged into TODO.md with P0/P1/P2 priority",
-        "All LLM outputs checked against field size limits",
-        "No silent failures in core workflows (grep for empty catch blocks)",
-        "All API routes return errors in consistent format",
-        "All user input validated (centralized Zod schemas recommended)",
-        "No unvalidated as-any casts on critical paths",
-        "DEPLOYMENT.md created (from ForgeTrail template)",
-        "BUSINESS_PLAN.md created if pursuing paid users (from ForgeTrail template)",
-        "TEST_PLAN.md complete or extended (from ForgeTrail template)",
-        "TECHNICAL_REFERENCE.md complete and current",
-        "Auth flow works end to end (if applicable)",
-        "Payment flow works end to end (if applicable)",
-        "Docs alignment audit passed (via ForgeTrail docs-alignment audit)",
-        "All documentation consolidated and cross-referenced"
-      ],
-      "notes": []
-    }
-  },
-  "decisions": [],
-  "gotchas": [],
-  "sessions": []
-}