forgetrail 0.5.3 → 0.5.5

package/content/NEW_PROJECT_BOOTSTRAP.md

@@ -1,6 +1,6 @@
 # ForgeTrail — New project bootstrap (MCP-first)
 
-Use this when **ForgeTrail is available via the MCP server** (recommended). The customer repo should **not** contain a copied `_forgetrail/` methodology tree — templates, audits, phase playbooks, and lessons are retrieved through MCP tools from the open-source ForgeTrail install. Project state lives in **`appledger/`**. Do **not** create **`.forgetrail/workflow_tracking.json`**. `.forgetrail/` is hooks and host rules.
+Use this when **ForgeTrail is available via the MCP server** (recommended). The customer repo should **not** contain a copied `_forgetrail/` methodology tree — templates, audits, phase playbooks, and lessons are retrieved through MCP tools from the open-source ForgeTrail install. Project state lives in **`appledger/`**. `.forgetrail/` is hooks and host rules.
 
 ---
 
@@ -8,7 +8,7 @@ Use this when **ForgeTrail is available via the MCP server** (recommended). The
 
 1. Follow the **7-phase lifecycle** (Plan → Build → Stabilize → Iterate → Refine → Align → Harden).
 2. **Pause at phase transitions** for explicit user approval before advancing.
-3. **Persist ForgeTrail state in `appledger/`** — manifest, `profiles/forgetrail.yaml`, and records. Do **not** write **`.forgetrail/workflow_tracking.json`**. Add **`.forgetrail/AGENTS.md`**, **`.forgetrail/CLAUDE.md`**, and **`.forgetrail/cursor/rules/`** (symlink `.mdc` files into **`.cursor/rules/`**) for host rules. Product docs (**`docs/`**, **`CONTEXT_PROMPT.md`**, **`README.md`**, **`TODO.md`**) stay at repo root. **Optionally gitignore `.forgetrail/`** if you want a cleaner public history or use MCP-only without a vendored Lite file (see **`FORGETRAIL_LITE.md` §1.5**). Commit **`appledger/`**. For **Cursor**, add **`.cursor/rules/forgetrail-phase-status.mdc`** from **`getNewProjectKickoff`** (bundled) or **`getForgeTrailCursorPhaseRule`** — it reads **`appledger/profiles/forgetrail.yaml`**. Also add **`forgetrail-lessons-gate.mdc`** and **`forgetrail-lessons-mcp.mdc`** from the same bundle or **`getForgeTrailCursorLessonsRules`** so agents call **`getAntiPatterns`** + **`searchLessons`** before substantial feature work.
+3. **Persist ForgeTrail state in `appledger/`** — manifest, `profiles/forgetrail.yaml`, and records. Add **`.forgetrail/AGENTS.md`**, **`.forgetrail/CLAUDE.md`**, and **`.forgetrail/cursor/rules/`** (symlink `.mdc` files into **`.cursor/rules/`**) for host rules. Product docs (**`docs/`**, **`CONTEXT_PROMPT.md`**, **`README.md`**, **`TODO.md`**) stay at repo root. **Optionally gitignore `.forgetrail/`** if you want a cleaner public history or use MCP-only without a vendored Lite file (see **`FORGETRAIL_LITE.md` §1.5**). Commit **`appledger/`**. For **Cursor**, add **`.cursor/rules/forgetrail-phase-status.mdc`** from **`getNewProjectKickoff`** (bundled) or **`getForgeTrailCursorPhaseRule`** — it reads **`appledger/profiles/forgetrail.yaml`**. Also add **`forgetrail-lessons-gate.mdc`** and **`forgetrail-lessons-mcp.mdc`** from the same bundle or **`getForgeTrailCursorLessonsRules`** so agents call **`getAntiPatterns`** + **`searchLessons`** before substantial feature work.
 4. **Pull methodology on demand** via ForgeTrail MCP tools (below). Do not ask the user to paste entire ForgeTrail files.
 5. **User-facing replies:** After bootstrap files exist, **`getPostBootstrapUserMessage`** defines the **first** reply—plain language only: what you did, what happens next, and a **concrete “reply with”** (problem, audience, hero workflow, constraints, v1 scope). **No** MCP/tool names, methodology jargon, ForgeTrail footers, file inventories, or “reference only” tracking dumps unless the user asks for internals.
 6. **Lists and choices:** When offering several next steps or options, follow **`USER_REPLY_FORMAT.md`** (ForgeTrail): **numbers** for ordered pipelines, **bullets** for parallel items, **letters** for pick-one / “which first—A/B/C?”—never hide multiple paths in one long sentence.
@@ -21,7 +21,7 @@ On a **new project folder**, commands like `git status`, `git log`, or `git rev-
 
 **You** initialize git after bootstrap files exist (unless the user chose **no-git mode** — see **`FORGETRAIL_LITE.md` §4.1**):
 
-1. Write kickoff artifacts first: **`appledger/`**, guardrails, optional Cursor rules. Do not write **`workflow_tracking.json`**.
+1. Write kickoff artifacts first: **`appledger/`**, guardrails, optional Cursor rules.
 2. Check with `git rev-parse --is-inside-work-tree`. If it returns false or errors, run **`git init -b main`** at the repo root (or `git init` + `git branch -m main` on older Git). **Never** re-init an existing repo.
 3. Write a **minimal** `.gitignore` now — at least `node_modules/`, `.env`, `.DS_Store`. Add `.forgetrail/` **only** if you chose the gitignore branch in **`FORGETRAIL_LITE.md` §1.5** (default MCP greenfield: **commit `.forgetrail/`**).
 4. Make a **first commit** when steps 1–3 are done so the user has a clean baseline (plain `-m` or `-F`). Skip if the repo already had history; skip entirely in no-git mode.
@@ -34,7 +34,7 @@ Do **not** treat an early missing-repo git error as blocking. Prefer **`git rev-
 
 - **Phase 1:** Create and lock **`docs/PHASE_1_BRIEF.md`** (`getTemplate({ name: "PHASE_1_BRIEF" })`). Log major commitments as **decision records in `appledger/`**. If the host supports **native plan mode**, use **`getPlanModePatterns`** and WORKFLOW §1c — plan first, export to the brief on approval (no app code during planning).
 - **App/code:** Phase 2 still means the **full runnable spine** in one pass: init, deps, data path, routes, components, hero flow **end-to-end**. Do **not** defer that spine.
-- **Project archetype (Phase 1):** classify the project as **`product`** (default), **`internal-tool`**, or **`one-shot`** (gift / event / demo) — often inferable from the problem statement; confirm rather than interrogate. Record it in **`PHASE_1_BRIEF.md`**, as a decision record, and as **`archetype`** on **`appledger/profiles/forgetrail.yaml`**. Prune non-applicable criteria on that profile (internal tools: Phase 6 optional, no payments/business-plan rows; one-shots: phases 5–7 collapse into one polish-and-ship gate). Log the pruning as a decision. Do not write `workflow_tracking.json`. See **WORKFLOW §1d** and **`GREENFIELD_INTAKE.md`** §0.
+- **Project archetype (Phase 1):** classify the project as **`product`** (default), **`internal-tool`**, or **`one-shot`** (gift / event / demo) — often inferable from the problem statement; confirm rather than interrogate. Record it in **`PHASE_1_BRIEF.md`**, as a decision record, and as **`archetype`** on **`appledger/profiles/forgetrail.yaml`**. Prune non-applicable criteria on that profile (internal tools: Phase 6 optional, no payments/business-plan rows; one-shots: phases 5–7 collapse into one polish-and-ship gate). Log the pruning as a decision. See **WORKFLOW §1d** and **`GREENFIELD_INTAKE.md`** §0.
 - **Web-app sub-question (Phase 1, when app type = web app):** before locking PocketBase + auth, ask *"Does any state need to outlive the browser — accounts, cross-device sync, shared data — or is every user's state private and fine in `localStorage`?"* If local-only → **drop PocketBase and auth**, `adapter-static` becomes viable, no deploy-time secrets; persist via `localStorage` / `IndexedDB`. If persistent → the full Default-A stack applies. Record the choice as a decision record and in **`PHASE_1_BRIEF.md` §4 (`State persistence:` row)**. See **`FORGETRAIL_LITE.md` §7** (A-local vs A-persistent) and **`GREENFIELD_INTAKE.md`** §7.
 - **Initial data (optional):** The user may create **JSON files** for seed, fixtures, or imports by using **any** LLM chat (including **local Ollama**) with the copy-paste prompt in **`FORGETRAIL_LITE.md` §4.3** (structured JSON only; save to `data/` or `fixtures/`). The agent **validates** shape before import; the user can repeat for multiple datasets. Not a replacement for the Phase 1 brief — only for bulk structured content.
 - **Web search (optional):** If v1 needs **live internet search**, the user can sign up for **[Tavily](https://tavily.com/)** and/or the **[Brave Search API](https://api-dashboard.search.brave.com/)** (free or entry-level credits per vendor terms), add keys to **`.env`**, and the agent wires **server-side** clients. See **`FORGETRAIL_LITE.md` §4.4** and **`GREENFIELD_INTAKE.md`** §6.
@@ -57,7 +57,7 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
    - If **`docs/GENESIS.md`** already exists (Try path / human brought a what-not-how spec), call **`ingestPlanArtifact`** with that file’s contents as `planContent`, review the draft brief, then continue intake for gaps only (`getGreenfieldIntakePrompt`). Do **not** re-run a full blank Genesis prompt unless the user asks.
    - If the user only has an **idea** (no file yet), especially one that wraps an existing app’s data/file format, offer **`getGenesisSpecPrompt`**: they paste it into an **external** LLM chat, save the result as **`docs/GENESIS.md`**, then you ingest as above. Humans without MCP can follow repo-root **`TRY_FORGETRAIL.md`** instead.
    - Skip this step if the user wants straight Lite/MCP intake questions with no Genesis file.
-1. Call **`getNewProjectKickoff`** (`includeCursorRule: false` if not using **Cursor**). It bundles this document, **`appledger/`** initialization, post-bootstrap user-message guidance, and optionally the Cursor rules (phase status + lessons gate + lessons MCP detail)—**or** call **`getNewProjectBootstrap`**, **`getInitialWorkflowTracking`**, **`getPostBootstrapUserMessage`**, **`getForgeTrailCursorPhaseRule`**, and **`getForgeTrailCursorLessonsRules`** separately if you need only one piece. **`getInitialWorkflowTracking` does not return a JSON file.** Write **`appledger/`**. Do not write **`workflow_tracking.json`**. The **next message to the user** follows **`getPostBootstrapUserMessage`** (product-facing, no methodology leak).
+1. Call **`getNewProjectKickoff`** (`includeCursorRule: false` if not using **Cursor**). It bundles this document, **`appledger/`** initialization, post-bootstrap user-message guidance, and optionally the Cursor rules (phase status + lessons gate + lessons MCP detail)—**or** call **`getNewProjectBootstrap`**, **`getInitialWorkflowTracking`**, **`getPostBootstrapUserMessage`**, **`getForgeTrailCursorPhaseRule`**, and **`getForgeTrailCursorLessonsRules`** separately if you need only one piece. **`getInitialWorkflowTracking` does not return a JSON file.** Write **`appledger/`**. The **next message to the user** follows **`getPostBootstrapUserMessage`** (product-facing, no methodology leak).
 2. **Initialize git if needed** (see **Greenfield git** above): after bootstrap files exist, `git init -b main` when `git rev-parse --is-inside-work-tree` fails; minimal `.gitignore`; optional first commit. Do not ask the user to run `git init`.
 3. Call **`getProgressiveDocSchedule`** and keep it in mind for every phase transition.
 4. Call **`getChecklist`** with section `before-session-1` — complete those items with the user (problem statement, stack, assets, hero flow).
@@ -106,7 +106,7 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 
 **Immediately (greenfield):**
 
-- **`appledger/`** — if the `appledger` command is installed, run **`appledger init`** and pass **`--name`** when the name is known. Init writes the manifest, profile, application record, and session record, and does not overwrite them. If the command is not installed, write those four files by hand. Do **not** write **`workflow_tracking.json`**. Commit **`appledger/`**.
+- **`appledger/`** — if the `appledger` command is installed, run **`appledger init`** and pass **`--name`** when the name is known. Init writes the manifest, profile, application record, and session record, and does not overwrite them. If the command is not installed, write those four files by hand. Commit **`appledger/`**.
 - **`docs/GENESIS.md`** (optional but preferred on the Try path) — what-not-how product spec from **`getGenesisSpecPrompt`** / **`TRY_FORGETRAIL.md`**. If present at kickoff, ingest with **`ingestPlanArtifact`** before locking the brief.
 - **Git repo** — if `git rev-parse --is-inside-work-tree` fails, **`git init -b main`** after bootstrap files exist (see **Greenfield git**). A failed early `git status` on an empty folder is **not** an error. Add minimal **`.gitignore`** and an optional first commit before Phase 1 intake.
 - **Cursor users:** `.cursor/rules/forgetrail-phase-status.mdc` — from **`getForgeTrailCursorPhaseRule`**. **`forgetrail-lessons-gate.mdc`** + **`forgetrail-lessons-mcp.mdc`** — from **`getForgeTrailCursorLessonsRules`** or **`getNewProjectKickoff`** (lessons workflow before substantial changes).
@@ -140,9 +140,9 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 
 - At **each session start**, read **`appledger/profiles/forgetrail.yaml`**, the latest session record, and `CONTEXT_PROMPT.md` (if present). Use **`getPhaseGuidance`** for the current phase.
 - When exit criteria for a phase appear satisfied, **state that explicitly** and **wait for user confirmation** before treating the next phase as active; change `current_phase_instance` only after approval.
-- After substantive work, update **`appledger/`** (criteria, decision records, lessons, the session). Do not write **`workflow_tracking.json`**. If that file exists and is not a pointer, **`validateTracking`** reports the conflict.
+- After substantive work, update **`appledger/`** (criteria, decision records, lessons, the session). If a legacy `.forgetrail/workflow_tracking.json` exists and is not a pointer, **`validateTracking`** reports the conflict.
 - If a problem does not converge after **~5 turns**, propose a **different approach**, not more patches.
-- **When the project ends** (shipped, delivered, shelved), run the **wrap protocol** (WORKFLOW §1e): sweep lesson and decision records for generalizable lessons, run the propagation prompt in **Harvest mode**, set **`project_status`** to **`wrapped`** on the profile, and add a final session record with end state and handoff pointers. Do not write `workflow_tracking.json`.
+- **When the project ends** (shipped, delivered, shelved), run the **wrap protocol** (WORKFLOW §1e): sweep lesson and decision records for generalizable lessons, run the propagation prompt in **Harvest mode**, set **`project_status`** to **`wrapped`** on the profile, and add a final session record with end state and handoff pointers.
 - **Git commits:** `git commit -F <file>` or plain `-m` at natural stopping points with concise summaries. Run verification checks prior to commit.
 
 ---
@@ -157,7 +157,7 @@ ForgeTrail’s reference implementation used **SvelteKit (Svelte 5), TypeScript,
 
 If the user has [gstack](https://github.com/garrytan/gstack) installed (Claude Code slash-command skills), ForgeTrail and gstack are **complementary** — ForgeTrail provides the lifecycle methodology, project memory, and business/brand layer; gstack provides sprint execution, browser-based QA, and deploy automation. Use both:
 
-**ForgeTrail owns the lifecycle.** Phase transitions, exit criteria, `appledger/`, progressive docs, lessons, and audits all come from ForgeTrail MCP. Do not write `workflow_tracking.json`.
+**ForgeTrail owns the lifecycle.** Phase transitions, exit criteria, `appledger/`, progressive docs, lessons, and audits all come from ForgeTrail MCP.
 
 **gstack owns the sprint inner loop.** Within a ForgeTrail phase, use gstack skills for the build → review → test → ship cycle:
 
@@ -171,7 +171,7 @@ If the user has [gstack](https://github.com/garrytan/gstack) installed (Claude C
 | **Phase 6** (Align) | `/design-consultation` for design system, `/plan-ceo-review` for scope check | Create **`BRAND_AND_PRODUCT.md`** and restructure **`TODO.md`** via ForgeTrail templates — gstack doesn't have brand/strategy tooling. |
 | **Phase 7** (Harden) | `/cso` for security audit, `/qa` for full regression, `/ship` + `/land-and-deploy` + `/canary` for production | ForgeTrail's `runAudit("black-hat")` and gstack's `/cso` are complementary — run both. ForgeTrail produces **`BLACK_HAT_REPORT.md`** and **`CODE_QUALITY.md`** as persistent docs; gstack's `/cso` catches runtime exploits. Use `/land-and-deploy` → `/canary` for the actual deploy pipeline, then fill ForgeTrail's **`DEPLOYMENT.md`** to document the process. |
 
-**Key rule:** After every gstack sprint that completes meaningful work, **update `appledger/`** (criteria when evidence exists, decision records, lessons or questions, the session). Do not write `workflow_tracking.json`. gstack persists some sprint artifacts (design docs from `/office-hours` in `~/.gstack/projects/`, retro snapshots in `.context/retros/`, review overrides, skill analytics), but it has **no lifecycle state, no decision rationale log, and no architecture context document**. ForgeTrail's `appledger/` plus `CONTEXT_PROMPT.md` are the system of record for the phase, the decisions, the lessons, and the architecture — none of which gstack tracks.
+**Key rule:** After every gstack sprint that completes meaningful work, **update `appledger/`** (criteria when evidence exists, decision records, lessons or questions, the session). gstack persists some sprint artifacts (design docs from `/office-hours` in `~/.gstack/projects/`, retro snapshots in `.context/retros/`, review overrides, skill analytics), but it has **no lifecycle state, no decision rationale log, and no architecture context document**. ForgeTrail's `appledger/` plus `CONTEXT_PROMPT.md` are the system of record for the phase, the decisions, the lessons, and the architecture — none of which gstack tracks.
 
 ---
 

package/content/PLAN_MODE_PATTERNS.md

@@ -14,7 +14,7 @@ When your host agent supports a first-class plan mode (Grok Build `/plan` + ente
 3. On user approval (the agent's `exit_plan_mode` or equivalent):
    - Immediately call `getTemplate({ name: "PHASE_1_BRIEF", mode: "full" })`.
    - Map/synthesize the approved plan content into the brief template (especially sections on architecture, data model, state persistence, content generation, and v1 scope).
-   - Write each major decision as a decision record in `appledger/`. Do not write `.forgetrail/workflow_tracking.json`.
+   - Write each major decision as a decision record in `appledger/`.
    - Optionally call `ingestPlanArtifact` with the full approved plan text to produce a `PHASE_1_BRIEF.md` draft and decision records (review and lock before Phase 2).
 
 4. The approved `docs/PHASE_1_BRIEF.md` and those decision records become the handoff so Phase 2 can begin "cold" without replaying the entire planning conversation.
@@ -35,7 +35,7 @@ When your host agent supports a first-class plan mode (Grok Build `/plan` + ente
 ## Artifacts That Must Result from Phase 1 (Plan or Not)
 
 - `docs/PHASE_1_BRIEF.md` (locked)
-- `appledger/` with the `plan` phase in progress and those decision records. Do not create `.forgetrail/workflow_tracking.json`.
+- `appledger/` with the `plan` phase in progress and those decision records.
 - (Later) `CONTEXT_PROMPT.md` will merge the brief in Phase 2
 
 Never proceed to scaffolding until the user confirms the plan/brief is locked.

package/content/POCKETBASE_SCHEMA_SCRIPT.md

@@ -18,7 +18,7 @@ Manual admin-UI collection setup (click-through wizards) does not scale across m
 4. **Schema (agent or one terminal):** `pnpm run pocketbase:schema` after PocketBase is up — idempotent; replaces manual Admin UI collection wizards.
 5. **PocketBase broken?** double-click **`test-pocketbase.bat`** / **`pnpm run test:pocketbase`** — isolated health check (**`SYSTEM_HEALTH_CHECKS.md`**).
 6. **Check progress:** double-click **`status.bat`** / **`status.sh`** or open **`docs/FORGETRAIL_PROGRESS.md`**.
-7. Walk the hero flow; tick Phase 2 exit items in `.forgetrail/workflow_tracking.json` when dev runs, data appears, CRUD works, and the full journey passes.
+7. Walk the hero flow; mark Phase 2 criteria met in `appledger/profiles/forgetrail.yaml`, with evidence, when dev runs, data appears, CRUD works, and the full journey passes.
 
 ---
 

package/content/POST_BOOTSTRAP_USER_MESSAGE.md

@@ -1,6 +1,6 @@
 # Post-bootstrap: first reply to the user
 
-**When:** Right after `appledger/` exists (and, for Cursor, the phase rule file if you use it). Do not mention `workflow_tracking.json` to the user.
+**When:** Right after `appledger/` exists (and, for Cursor, the phase rule file if you use it).
 
 **Purpose:** Confirm what happened in **plain language** and give **one clear ask**—what the human should do or answer next. This is not an implementation report.
 
@@ -12,7 +12,7 @@ Assume the reader is a **product owner**, not a methodology engineer. They shoul
 
 - MCP or ForgeTrail server/tool names (`getChecklist`, `getGreenfieldIntakePrompt`, “bundle”, “methodology stays on the MCP side”, etc.)
 - Paths like `.cursor/rules/…` unless they need to edit something themselves
-- Field-by-field descriptions of `workflow_tracking.json` or other “for your reference only” inventories
+- Field-by-field descriptions of `appledger/` files or other “for your reference only” inventories
 - ForgeTrail **footers** (phase · exit criteria · “Next: …”)—those are for **agent** orientation in later turns, not for this first message
 
 Agents keep planning steps **internal** until they turn user answers into `docs/PHASE_1_BRIEF.md`.

package/content/SESSION_RESUME_MCP.md

@@ -19,7 +19,7 @@ Do **not** require `_forgetrail/WORKFLOW.md` or `_forgetrail/TRACKING_SCHEMA.md`
 ## Rules for this session
 
 - When exit criteria for the current phase appear met, say so explicitly and **wait for user confirmation** before changing `current_phase_instance`.
-- After work, update the **session record** and any new **decision records** in **`appledger/`**. Do not write **`workflow_tracking.json`**.
+- After work, update the **session record** and any new **decision records** in **`appledger/`**.
 - Keep **`CONTEXT_PROMPT.md`** the source of truth for architecture; edit it when decisions change.
 - If stuck after **~5 turns** on one issue, propose a **fundamentally different approach**.
 - If the repo has **gstack** installed, use its skills for sprint execution (build/review/qa/ship) within ForgeTrail phases — see **WORKFLOW.md §1b** or call **`getPhaseGuidance`** for phase-specific gstack integration. After each gstack sprint, update the **appledger** session.

package/content/companion-tools.json

@@ -4,7 +4,7 @@
     "Companions are optional. Decline is success. Never block a phase on an install.",
     "Suggest at the moment of need. Do not dump the shelf at kickoff or in the first user-facing message.",
     "Do not install, enroll, or publish unless the user asked.",
-    "After a companion run that matters, persist the outcome on the appledger session as data.companion_outcomes and in the matching progressive doc. Do not write workflow_tracking.json.",
+    "After a companion run that matters, persist the outcome on the appledger session as data.companion_outcomes and in the matching progressive doc.",
     "Do not mention the mapping file, spec paths, or MCP tool names in human-facing offers.",
     "When wiring LocalSlip, follow that tool's how. Do not write ensure-lease.mjs. Do not add the localslip package just to read a port."
   ],
@@ -190,7 +190,7 @@
         {
           "name": "Gap Last",
           "homepage": "https://gaplast.dev",
-          "offer": "Gap Last separates observations, constraints, and remaining questions, then proposes hypotheses. A hypothesis is not the established cause. Log leftovers in gotchas[]."
+          "offer": "Gap Last separates observations, constraints, and remaining questions, then proposes hypotheses. A hypothesis is not the established cause. Record leftovers as open question records in appledger/."
         }
       ]
     },
@@ -203,7 +203,7 @@
         {
           "name": "xFacts",
           "homepage": "https://xfacts.dev",
-          "offer": "xFacts labels (AppFacts and neighbors) are the house standard for shipped products. Write a label when the product is public or handed off. A validator checks shape, not truth."
+          "offer": "When the product is public or handed off, offer an xFacts label (AppFacts and neighbors). Record the subject disposition either way, and bind an existing label with appledger bind. A validator checks shape, not truth."
         }
       ]
     },

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. Do **not** read or write `.forgetrail/workflow_tracking.json`. If that file 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: run `appledger migrate preview`, then apply.
 
 ## When to surface status
 
@@ -19,7 +19,7 @@ Include a short **ForgeTrail** footer in replies when it helps orientation—esp
 
 Skip the footer for trivial one-line answers (typos, single-token replies) unless the user asked for status.
 
-**Product-facing / non-technical users:** Do **not** show ForgeTrail footers, phase IDs, MCP/tool names, or internal checklists unless they ask how the workflow is wired up. Plain language only. For phase progress without an agent, point them to **`docs/FORGETRAIL_PROGRESS.md`**. The durable phase is `appledger/profiles/forgetrail.yaml`, not `.forgetrail/workflow_tracking.json`.
+**Product-facing / non-technical users:** Do **not** show ForgeTrail footers, phase IDs, MCP/tool names, or internal checklists unless they ask how the workflow is wired up. Plain language only. For phase progress without an agent, point them to **`docs/FORGETRAIL_PROGRESS.md`**. The durable phase is `appledger/profiles/forgetrail.yaml`.
 
 **Right after bootstrap:** **Omit** the footer entirely—user should get a simple “what’s done + what I need from you next,” not methodology. If you already followed **`getPostBootstrapUserMessage`** in the same turn, do not duplicate status blocks.
 
@@ -57,4 +57,4 @@ Do **not** bury three or more paths in a single long sentence—**list them**, t
 
 ## Phase transitions
 
-Do **not** advance `current_phase_instance` or mark a phase completed without **explicit user confirmation**. If criteria look satisfied, say so and ask before updating the profile. Do not write `workflow_tracking.json`.
+Do **not** advance `current_phase_instance` or mark a phase completed without **explicit user confirmation**. If criteria look satisfied, say so and ask before updating the profile.

package/content/cursor-rules/forgetrail-updates-log.mdc

@@ -16,7 +16,7 @@ After substantive work, if you find something that **should be fixed or clarifie
 - Errors in the Lite defaults for **pnpm + TypeScript + monorepos** or **Cursor/agent** workflows.
 - Doc structure suggestions (which § to patch).
 
-**Do not** log routine bug fixes or product-only notes; use `.forgetrail/workflow_tracking.json → gotchas[]` for session-local incidents. **Do** log items a **future agent bootstrapping any ForgeTrail Lite project** would benefit from if the upstream file were updated.
+**Do not** log routine bug fixes or product-only notes; record a session-local incident as a lesson or open question record in `appledger/`. **Do** log items a **future agent bootstrapping any ForgeTrail Lite project** would benefit from if the upstream file were updated.
 
 ## How to write an entry
 

package/content/examples/two-session-continuity.md

@@ -2,7 +2,7 @@
 
 This is a labeled example. The project is fictional. It shows how ForgeTrail Lite state survives a closed chat, and how the next session is supposed to consume it.
 
-Nothing here is a benchmark, an adoption claim, or a client record. The record shape matches `appledger/` records, not the legacy `workflow_tracking.json` starter.
+Nothing here is a benchmark, an adoption claim, or a client record. The record shape matches `appledger/` records.
 
 ## The job
 
@@ -14,7 +14,7 @@ The human created an empty folder, wrote `docs/GENESIS.md`, and added Lite by co
 
 The human pasted the kickoff line from [TRY_FORGETRAIL.md](../../TRY_FORGETRAIL.md). The **agent** (not the CLI) then:
 
-1. Created `appledger/` with a manifest, a ForgeTrail profile, an application record, and a session record. It did not create `.forgetrail/workflow_tracking.json`.
+1. Created `appledger/` with a manifest, a ForgeTrail profile, an application record, and a session record.
 2. Drafted `docs/PHASE_1_BRIEF.md`.
 3. Recorded one decision and one lesson.
 4. Stopped after the human approved the brief. No application scaffold yet.

package/content/hooks/README.md

@@ -9,7 +9,7 @@ Enforces ForgeTrail rules and guards at the host tool level, rather than relying
 - `session-start.mjs`: on session start, points the session at `appledger/`. A writable `workflow_tracking.json` is reported as a legacy conflict, not the live phase.
 - `validate-tracking.mjs`: after editing `workflow_tracking.json`, runs structural validation. A pointer is accepted. A legacy writable document is a conflict.
 - `validate-tracking-core.mjs`: standalone zero-dependency tracking validator.
-- `session-stop.mjs`: on session stop, reminds the agent to update the appledger session record. It does not ask for a new JSON session entry.
+- `session-stop.mjs`: when a turn ends, reminds the agent to update the appledger session record if project files changed after that record was last written. It stays quiet on follow-up turns, on read-only turns, and when only `appledger/`, `.forgetrail/`, `.cursor/`, or `.claude/` changed. It names `workflow_tracking.json` only when a legacy copy is present.
 - `cursor-hooks.json`: standard Cursor hooks configuration.
 - `claude-settings-hooks.json`: standard Claude Code configuration fragment.
 

package/content/hooks/guard-shell.mjs

@@ -3,7 +3,7 @@
 /**
  * ForgeTrail Shell Guard
  * Hook event: beforeShellExecution (Cursor) / PreToolUse (Claude Code)
- * Enforces Lite §0, git commit attribution rules, pnpm consistency, and git push guards.
+ * Enforces Lite §0, verify-before-commit, pnpm consistency, and git push guards.
  */
 
 import { readFileSync, existsSync } from "node:fs";

package/content/hooks/session-start.mjs

@@ -54,7 +54,6 @@ function main() {
     lines.push("Project record: appledger/");
     lines.push("Read appledger/profiles/forgetrail.yaml for the current phase.");
     lines.push("Read the latest session record for left_off and next_steps.");
-    lines.push("Do not update workflow_tracking.json.");
   }
 
   if (trackingPath) {

package/content/hooks/session-stop.mjs

@@ -3,10 +3,11 @@
 /**
  * ForgeTrail Session Stop Check
  * Hook event: stop (Cursor)
- * Reminds the agent to update the AppLedger session, not a tracking JSON file.
+ * Reminds the agent to update the AppLedger session record when work happened after it was last written.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 function walkUp(startDir, found) {
@@ -37,7 +38,78 @@ function isPointer(data) {
   return data?.status === "pointer" && typeof data.record === "string" && data.record.replaceAll("\\", "/").includes("appledger");
 }
 
+function readHookInput() {
+  try {
+    const raw = readFileSync(0, "utf-8");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function latestSessionMs(root) {
+  const dir = join(root, "appledger", "records", "session");
+  if (!existsSync(dir)) return 0;
+  let latest = 0;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".md")) continue;
+    latest = Math.max(latest, statSync(join(dir, name)).mtimeMs);
+  }
+  return latest;
+}
+
+function git(root, args) {
+  return execFileSync("git", args, { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+}
+
+const NOT_PROJECT_WORK = ["appledger/", ".forgetrail/", ".cursor/", ".claude/"];
+
+function outsideLedger(path) {
+  const p = path.replaceAll("\\", "/");
+  return p !== "" && !NOT_PROJECT_WORK.some((prefix) => p.startsWith(prefix));
+}
+
+/** True when project files changed after the newest session record, or when that cannot be told. Ledger and host-config paths do not count. */
+function workSinceSession(root) {
+  const sessionMs = latestSessionMs(root);
+  if (sessionMs === 0) return true;
+  try {
+    const since = `@${Math.floor(sessionMs / 1000)}`;
+    const hasCommits = (() => {
+      try {
+        git(root, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+        return true;
+      } catch {
+        return false;
+      }
+    })();
+    if (hasCommits) {
+      const committed = git(root, ["log", `--since=${since}`, "--name-only", "--format="]).split("\n").filter(outsideLedger);
+      if (committed.length > 0) return true;
+    }
+    const pending = git(root, ["status", "--porcelain", "--untracked-files=all"])
+      .split("\n")
+      .map((line) => line.slice(3).split(" -> ").pop()?.replace(/^"|"$/g, "") ?? "")
+      .filter(outsideLedger);
+    return pending.some((path) => {
+      try {
+        return statSync(join(root, path)).mtimeMs > sessionMs;
+      } catch {
+        return true;
+      }
+    });
+  } catch {
+    return true;
+  }
+}
+
 function main() {
+  const input = readHookInput();
+  if ((input.loop_count ?? 0) > 0 || (input.status && input.status !== "completed")) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
   const ledgerRoot = findLedger(process.cwd());
   const trackingPath = findProjectTracking(process.cwd());
   let legacy = false;
@@ -59,11 +131,11 @@ function main() {
     return;
   }
 
-  if (ledgerRoot) {
+  if (ledgerRoot && workSinceSession(ledgerRoot)) {
     console.log(
       JSON.stringify({
         followup_message:
-          "ForgeTrail reminder: update the appledger session record (what was accomplished, left_off, next_steps) before ending. Do not write workflow_tracking.json.",
+          "ForgeTrail reminder: files changed after the latest appledger session record. Update that record (what was accomplished, left_off, next_steps) before ending.",
       })
     );
     return;

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

@@ -144,7 +144,7 @@ async function cmdRun() {
 function renderProgress() {
   if (!existsSync(trackingPath)) {
     return {
-      text: "No workflow_tracking.json. Phase state belongs in appledger/profiles/forgetrail.yaml.",
+      text: "Phase state: appledger/profiles/forgetrail.yaml.",
       md: null,
     };
   }

package/content/skills/forgetrail/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forgetrail
-description: "Enforce the ForgeTrail 7-phase lifecycle (Plan → Build → Stabilize → Iterate → Refine → Align → Harden), maintain appledger/ as the system of record, pause at explicit phase transitions for user approval, prefer native plan modes when available, and use subagents for parallel audits/research where the host agent supports it. Do not write workflow_tracking.json. Activate for any non-trivial full-stack app development. Follow progressive documentation rules and propagate lessons back."
+description: "Enforce the ForgeTrail 7-phase lifecycle (Plan → Build → Stabilize → Iterate → Refine → Align → Harden), maintain appledger/ as the system of record, pause at explicit phase transitions for user approval, prefer native plan modes when available, and use subagents for parallel audits/research where the host agent supports it. Activate for any non-trivial full-stack app development. Follow progressive documentation rules and propagate lessons back."
 user-invocable: true
 argument-hint: "kickoff new project | resume session | Phase 4 feature work | run black-hat audit | stabilize current issues"
 allowed-tools: "read_file, search_replace, run_terminal_command, todo_write, spawn_subagent, getPhaseGuidance, getCompanionSuggestions, runAudit, searchLessons, validateTracking, suggestSubagentDecomposition, getTemplate, getNewProjectKickoff, getResumeSessionInstructions"
@@ -21,7 +21,7 @@ You are operating under the ForgeTrail methodology. Your primary job is to give
    - 6. Align (map to brand/strategy)
    - 7. Harden (security, perf, docs, production readiness)
 
-   Phases 4 and 5 commonly alternate. Update `current_phase_instance` and criteria in `appledger/profiles/forgetrail.yaml`. Do not write `workflow_tracking.json`.
+   Phases 4 and 5 commonly alternate. Update `current_phase_instance` and criteria in `appledger/profiles/forgetrail.yaml`.
 
 2. **At the start of every session or major turn**:
    - Read `appledger/profiles/forgetrail.yaml` and the latest session record.
@@ -39,10 +39,9 @@ You are operating under the ForgeTrail methodology. Your primary job is to give
    - Mark a criterion `met` only when an evidence ref exists.
    - Add a lesson or question record when something surprising or painful happens.
    - Update the session record at natural breaks.
-   - Do not create or update `workflow_tracking.json`.
 
 5. **Use native agent capabilities**:
-   - If the agent supports a native plan mode (e.g. Grok `/plan`), use it for Phase 1. On approval, export the plan into `docs/PHASE_1_BRIEF.md` (via `getTemplate`) and decision records in `appledger/`. Do not write `workflow_tracking.json`.
+   - If the agent supports a native plan mode (e.g. Grok `/plan`), use it for Phase 1. On approval, export the plan into `docs/PHASE_1_BRIEF.md` (via `getTemplate`) and decision records in `appledger/`.
    - When the host supports `spawn_subagent`, use `suggestSubagentDecomposition` (or reason directly) to run audits, research, and reviews in parallel with appropriate `capability_mode`, `isolation`, and personas. Synthesize results in the parent thread and update tracking/docs.
    - Prefer `read-only` or `execute` modes for subagents doing analysis.
 
@@ -71,11 +70,11 @@ You are operating under the ForgeTrail methodology. Your primary job is to give
 When ready to advance:
 - Confirm the phase criteria that have evidence.
 - Ask the user: "Ready to move to Phase X?"
-- Only after confirmation, update the phase status in `appledger/profiles/forgetrail.yaml` and the session record. Do not write `workflow_tracking.json`.
+- Only after confirmation, update the phase status in `appledger/profiles/forgetrail.yaml` and the session record.
 
 ## For New Projects (Greenfield)
 
-Prefer calling `getNewProjectKickoff` (or `kickoffGreenfield`) at the very beginning. When `appledger` is installed, run `appledger init` as that bundle describes. Do not write `workflow_tracking.json`. Write optional Cursor rules, and follow the post-bootstrap instructions exactly. Then start with Phase 1.
+Prefer calling `getNewProjectKickoff` (or `kickoffGreenfield`) at the very beginning. When `appledger` is installed, run `appledger init` as that bundle describes. Write optional Cursor rules, and follow the post-bootstrap instructions exactly. Then start with Phase 1.
 
 ## For Resuming
 

package/content/skills/forgetrail/SKILL_FACTS.md

@@ -33,7 +33,7 @@ egress:
   telemetry: none
   destinations: []
 generated:
-  date: 2026-08-20
+  date: 2026-09-26
   generator: hand-authored
 credits:
   generated_with: https://skillfacts.dev

package/docs/NPM.md

@@ -10,12 +10,12 @@ 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.2 | 0.5.2 | repo root | CLI + Lite + templates. `pnpm dlx forgetrail install --lite` |
-| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.4.2 | 0.4.1 | `mcp-server/` | MCP bin. Depends on `forgetrail` for content. `pnpm dlx forgetrail-mcp` |
+| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.5.3 | 0.5.3 | repo root | CLI + Lite + templates. `pnpm dlx forgetrail install --lite` |
+| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.4.3 | 0.4.2 | `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.2` is on npm. This tree has Lite v2.2.1 and a new installer `Next:` step that are not in `0.5.2`, so `forgetrail` needs a version bump before its next publish. `forgetrail-mcp@0.4.2` is this tree and is not published yet. It adds `forgetrail` as a dependency and returns an explicit error when content is missing. `0.4.1` remains the registry copy until you publish from `mcp-server/`. `pnpm run pack:check` is the gate. It does not publish.
+`forgetrail@0.5.3` and `forgetrail-mcp@0.4.2` are on npm. This tree adds `forgetrail --version`, forgetrail.dev `llms.txt`, and companion text that names `appledger/`, so `forgetrail` needs a version bump before its next publish. `forgetrail-mcp@0.4.3` changes the startup banner and the `ingestPlanArtifact` description, and is not published yet. `getCompanionSuggestions` reads its text from the installed `forgetrail`, so the new companion text reaches MCP users only after `forgetrail` is published. `pnpm run pack:check` is the gate. It does not publish.
 
 ---
 
@@ -63,7 +63,7 @@ pnpm dlx forgetrail@<version> --help
 pnpm dlx forgetrail@<version> install --lite --dry-run
 
 # MCP starts and reads content from its forgetrail dependency. ping should not say "content missing".
-pnpm dlx forgetrail-mcp@0.4.2
+pnpm dlx forgetrail-mcp@0.4.3
 ```
 
 Optional Cursor MCP (content from a `forgetrail` install, or set the path):

package/docs/PHASE_1_BRIEF.md

@@ -4,7 +4,7 @@ _Structured capture of planning and architecture **before** code scaffolding. Go
 
 **Status:** `[draft | locked]`  
 **Last updated:** `[ISO date]`  
-**Phase 1 exit:** Do not mark the `plan` phase complete in `appledger/profiles/forgetrail.yaml` until this brief is **locked** and major commitments are decision records. Do not write `workflow_tracking.json`.
+**Phase 1 exit:** Do not mark the `plan` phase complete in `appledger/profiles/forgetrail.yaml` until this brief is **locked** and major commitments are decision records.
 
 ---
 
@@ -158,7 +158,7 @@ _Ordered list of what to build after the spine runs — aligns with initial `TOD
 
 - [ ] User has confirmed stack, folder shape, data sketch, hero flow, and v1 boundaries
 - [ ] This brief is **locked** (no `[draft]` ambiguity) or remaining items are only in §9 Open questions
-- [ ] `appledger/` updated: a decision record for each major D#, and the session records the sign-off. Do not write `workflow_tracking.json`.
+- [ ] `appledger/` updated: a decision record for each major D#, and the session records the sign-off.
 - [ ] Phase 2 opener will read **this file**, `appledger/profiles/forgetrail.yaml`, and the latest session record first
 
 > 💡 **Lesson learned:** Treat the brief and the decision records as a pair. The brief is what the next human or agent reads in one pass. Duplicated rationale is OK — drift between them is not. After Phase 2 starts, **merge** this content into `CONTEXT_PROMPT.md` per the mapping in that template’s “Handoff from Phase 1” section.

package/docs/SPEC_FEATURE_TEMPLATE.md

@@ -132,7 +132,7 @@ _Testable binary pass/fail checks. Avoid vague qualifiers ("performant", "clean"
 
 ## 10. Decisions (optional)
 
-_Lock choices here (and mirror major ones into `.forgetrail/workflow_tracking.json` → `decisions[]` when they are architectural)._
+_Lock choices here (and record major ones as decision records in `appledger/` when they are architectural)._
 
 **D1.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgetrail",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "private": false,
   "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
   "license": "Apache-2.0",

package/scripts/forgetrail-cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { readFileSync } from "node:fs";
 import { cwd } from "node:process";
 import {
   INSTALL_FULL_HELP,
@@ -39,6 +40,7 @@ Install options:
   --skip-tracking    Accepted and ignored. A tracking JSON file is not installed.
   --path, -p <dir>   Install elsewhere (default: current directory)
   --help, -h         Show help
+  --version, -v      Print the forgetrail version
 
 First-time prove-it (no MCP): see TRY_FORGETRAIL.md in the ForgeTrail repo.
 Run \`forgetrail mcp --help\` for all MCP subcommands.
@@ -54,6 +56,12 @@ function main() {
 
   const cmd = argv[0];
 
+  if (cmd === "--version" || cmd === "-v") {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
   if (cmd === "mcp") {
     runMcpCommand(argv.slice(1));
     return;

package/scripts/install.mjs

@@ -86,7 +86,7 @@ export function runInstallForgetrail(rawArgv, { defaultToCwd = false } = {}) {
   console.log("\nDone.");
   console.log("  Methodology:  _forgetrail/WORKFLOW.md");
   console.log("  First chat:   _forgetrail/INITIAL_PROMPT.md");
-  console.log("  Project record: appledger/ (not workflow_tracking.json)");
+  console.log("  Project record: appledger/");
   console.log("  Hooks:        .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
   printLedgerNext();
   return { target, mode: "full" };