forgetrail 0.5.5 → 0.5.6

package/CONTINUATION_PROMPT.md

@@ -11,7 +11,7 @@ I'm continuing work on [APP NAME]. You are following ForgeTrail, a structured ph
 
 1. Call ForgeTrail MCP **`getResumeSessionInstructions`** and follow it.
 2. Read **`appledger/profiles/forgetrail.yaml`** and the latest session record. If the phase is **plan**, read **`docs/PHASE_1_BRIEF.md`**. Otherwise read **`CONTEXT_PROMPT.md`** (if a later phase is current but CONTEXT is missing and the brief exists, **merge the brief into CONTEXT** first per the CONTEXT_PROMPT template).
-3. Use **`getPhaseGuidance`** for the current phase. If a legacy `.forgetrail/workflow_tracking.json` exists and is not a pointer, run **`appledger migrate preview`** and then apply.
+3. Use **`getPhaseGuidance`** for the current phase.
 
 ### Local `_forgetrail/` folder
 

package/README.md

@@ -33,7 +33,7 @@ The shortest supported first task is: create `appledger/`, draft `docs/PHASE_1_B
 | Path | Who uses it | What it is |
 | --- | --- | --- |
 | **Lite** | First path | One protocol file. The agent writes `appledger/`. |
-| **CLI** (`forgetrail`) | Node.js 20+ | Installer. Writes Lite and Cursor hooks, or the full template tree. It does not write a tracking JSON file. Skips files that already exist. Does not run the agent. |
+| **CLI** (`forgetrail`) | Node.js 20+ | Installer. Writes Lite and Cursor hooks, or the full template tree. Skips files that already exist. Does not run the agent. |
 | **MCP** (`forgetrail-mcp`) | Cursor or Claude | Phase guidance, templates, and lessons search. The ledger still lives in the app repo. |
 
 ```bash
@@ -45,9 +45,9 @@ MCP: `npx -y forgetrail-mcp` (0.4.2 or later finds the methodology without `FORG
 
 ## What you get
 
-A 7-phase playbook, a ledger in `appledger/`, and templates pre-loaded with first-party production lessons. Each project leaves decisions, lessons, and a session handoff that future work follows. Those lesson notes are not independent adoption evidence. A new install does not create `.forgetrail/workflow_tracking.json`.
+A 7-phase playbook, a ledger in `appledger/`, and templates pre-loaded with first-party production lessons. Each project leaves decisions, lessons, and a session handoff that future work follows. Those lesson notes are not independent adoption evidence.
 
-Optional hooks in [`content/hooks/`](content/hooks/README.md) load the current phase at session start in Cursor or Claude Code, validate tracking edits, and check for a session note at session stop. The agent still does the writing. Flags, MCP, and the phase table live in the [docs](https://forgetrail.dev/docs).
+Optional hooks in [`content/hooks/`](content/hooks/README.md) load the current phase at session start in Cursor or Claude Code, check ledger edits, and check for a session note at session stop. The agent still does the writing. Flags, MCP, and the phase table live in the [docs](https://forgetrail.dev/docs).
 
 <!-- xfacts-label -->
 

package/TRY_FORGETRAIL.md

@@ -29,14 +29,14 @@ Prove ForgeTrail in one sitting: write a **what, not how** spec in any AI chat,
      `pnpm dlx forgetrail install --lite`  
      Stub for Genesis too:  
      `pnpm dlx forgetrail install --lite --with-genesis-stub`  
-     The CLI writes the Lite protocol and Cursor hooks. It does not write a tracking JSON file. Project state belongs in `appledger/`. It skips files that already exist.
+     The CLI writes the Lite protocol and Cursor hooks. Project state belongs in `appledger/`. It skips files that already exist.
 
 5. **Save your spec as `docs/GENESIS.md`**  
    Create `docs/` if needed. That path is the canonical handoff for ForgeTrail (not the repo root).
 
 6. **Open the folder in your coding agent** and paste this kickoff line:
 
-> Follow `.forgetrail/FORGETRAIL_LITE.md` as the project protocol. Treat `docs/GENESIS.md` as the product spec (what, not how). Create `appledger/` (manifest, profile, application record, session record) and draft `docs/PHASE_1_BRIEF.md` from the Genesis file, asking me only about gaps. Do not create `workflow_tracking.json`. Do not scaffold application code until I explicitly approve the Phase 1 brief.
+> Follow `.forgetrail/FORGETRAIL_LITE.md` as the project protocol. Treat `docs/GENESIS.md` as the product spec (what, not how). Create `appledger/` (manifest, profile, application record, session record) and draft `docs/PHASE_1_BRIEF.md` from the Genesis file, asking me only about gaps. Do not scaffold application code until I explicitly approve the Phase 1 brief.
 
 7. **Approve the Phase 1 brief** before any app scaffold. If the agent starts writing application code early, stop it and paste the kickoff line again.
 

package/WORKFLOW.md

@@ -4,7 +4,7 @@
 
 A persistent development system for building software with AI agents. A structured 7-phase workflow for solo developers building non-trivial full-stack apps with coding agents. Derived from 7 sessions and ~78,000 lines of real-world app development.
 
-**System of record:** Phase, decisions, lessons, and sessions live in `appledger/` (`profiles/forgetrail.yaml` and records). If a legacy `.forgetrail/workflow_tracking.json` exists and is not a pointer, run `appledger migrate preview` and then apply. Do not keep a second decision log. `.forgetrail/` is hooks and host integration.
+**System of record:** Phase, decisions, lessons, and sessions live in `appledger/` (`profiles/forgetrail.yaml` and records). `.forgetrail/` is hooks and host integration.
 
 ---
 
@@ -272,7 +272,7 @@ Catalyst Forge siblings (and Cloudflare as a default DNS/hosting suggestion) are
 
 They are **never required**. Decline is success. Do not dump the shelf at kickoff. Suggest when a trigger is true; persist the outcome on the appledger session as `data.companion_outcomes`.
 
-**Subjects:** When an applicable subject exists — an application, a tool server, a skill package, an agent configuration, or a model variant — record a disposition with `appledger subjects`. A family with no subject is `not_applicable`, not a missing label. Do not generate or rewrite a label. A published xFacts label remains an offer when the product goes public or changes hands, and only if the user asks.
+**Subjects:** When an applicable subject exists — an application, a tool server, a skill package, an agent configuration, or a model variant — record a disposition with `appledger subjects`. A family with no subject is `not_applicable`, not a missing label. Do not generate or rewrite a label. A published xFacts label remains an offer when the product goes public or changes hands, and only if the user asks. An [Efficacy](https://efficacy.dev) chain in `.efficacy/` is the same kind of offer when a later agent should record a measured use of that version.
 
 **Agents:** `getCompanionSuggestions` (`phase` or `situation`) plus the optional footer on `getPhaseGuidance`. Mapping: `content/COMPANION_TOOLS.md`. Shelf: [catalystforge.com/tools](https://catalystforge.com/tools/).
 
@@ -289,7 +289,7 @@ They are **never required**. Decline is success. Do not dump the shelf at kickof
 - Pre-launch newcomer check → Cold-eye
 - Quality / presentation of a tool, site, or page → CraftAssay
 - An applicable subject exists → record a disposition (`appledger subjects`). A missing family stays `not_applicable`. Do not generate a label.
-- Product going public or handed off, and the user asks → offer an xFacts label
+- Product going public or handed off, and the user asks → offer an xFacts label, and an [Efficacy](https://efficacy.dev) chain if a later agent should inspect a measured use
 - Unpushed work you cannot lose → IngotVault
 - Spoken idea capture → DictaWhisper
 
@@ -303,8 +303,8 @@ ForgeTrail includes deterministic host hooks (`.forgetrail/hooks/` with `.cursor
 
 - **Shell guards:** Runs pre-commit verification (`pnpm run verify`), prevents package manager divergence (e.g. `npm`/`yarn` when `pnpm-lock.yaml` is present), gates `git push` on explicit user approval, and flags destructive operations (`git reset --hard`, `rm -rf`).
 - **Edit guards:** Requires user confirmation before mutating environment secrets (`.env*`) or canonical/completed specs (`specs/completed/**`).
-- **Session start injection:** Points the session at `appledger/` (profile phase and the latest session). It reports a legacy `.forgetrail/workflow_tracking.json` as a conflict, not the live phase.
-- **Tracking validation:** A pointer to `appledger/` is accepted. A legacy writable `workflow_tracking.json` is a conflict and is not the system of record.
+- **Session start injection:** Points the session at `appledger/` (profile phase and the latest session).
+- **Ledger check:** After an edit under `appledger/`, runs `appledger check` when the command is on PATH.
 
 Where the host supports hooks, tool-level denial and injection take the load off agent context budgets.
 
@@ -567,7 +567,7 @@ Where the host supports hooks, tool-level denial and injection take the load off
 - No silent failures in core workflows
 - Docs alignment audit passed (MCP `runAudit({ type: "docs-alignment" })` or `_forgetrail/prompts/docs-alignment-audit.md`)
 
-**Optional companions:** Cold-eye for newcomer readiness; CraftAssay for a quality score of the presented work; FilePress + Cloudflare Pages for a Markdown or docs site; IngotVault before a rewrite. If an applicable subject exists, record a disposition; a missing family is `not_applicable`. Offer an xFacts label only when the product goes public or changes hands and the user asks. Do not generate a label. See §1f.
+**Optional companions:** Cold-eye for newcomer readiness; CraftAssay for a quality score of the presented work; FilePress + Cloudflare Pages for a Markdown or docs site; IngotVault before a rewrite. If an applicable subject exists, record a disposition; a missing family is `not_applicable`. Offer an xFacts label only when the product goes public or changes hands and the user asks. Do not generate a label. An Efficacy chain in `.efficacy/` is optional in that same moment. See §1f.
 
 ---
 

package/content/AGENT_INTEGRATION_cursor.md

@@ -42,7 +42,6 @@ Use `run_in_background` for long subagents when appropriate.
 
 After subagent or feature work:
 - Update `appledger/` (criteria, decision records, lessons, the session).
-- Run **`validateTracking`** only when a legacy tracking file is present. A missing file is expected.
 - Update `CONTEXT_PROMPT.md` when architecture or patterns change.
 
 ## Skills alternative

package/content/AGENT_INTEGRATION_generic.md

@@ -1,6 +1,6 @@
 # ForgeTrail Integration Guide (generic agents)
 
-Use this when no agent-specific guide is available. ForgeTrail is **agent-agnostic** — the lifecycle, tracking file, and MCP tools work with any capable coding agent.
+Use this when no agent-specific guide is available. ForgeTrail is **agent-agnostic** — the lifecycle, the ledger, and MCP tools work with any capable coding agent.
 
 ## Core integration model
 

package/content/COMPANION_TOOLS.md

@@ -17,7 +17,7 @@ Public shelf (current versions and install): [catalystforge.com/tools](https://c
 3. FilePress publishes **Markdown**. It does not replace an interactive SvelteKit app.
 4. LocalSlip and LocalHelm are for **two or more** local apps, not a first single project. If they accept LocalSlip, use the recipes below. Do not write `ensure-lease.mjs`.
 5. Practice skills: install the one that matches the current job, not the set.
-6. Offer an xFacts label when a product ships (public URL or handoff). Generate one only if the user accepts. Record the subject disposition in `appledger/` either way.
+6. Offer an xFacts label when a product ships (public URL or handoff). Generate one only if the user accepts. Record the subject disposition in `appledger/` either way. Offer an [Efficacy](https://efficacy.dev) chain in `.efficacy/` when a later agent should record a measured use of that version. The chain is optional, and a passing verify does not make the claim true.
 
 ---
 
@@ -77,7 +77,7 @@ Do not migrate a working host the user already chose.
 | `hard-to-undo` | Delete data, lock persistence, rewrite git, lock a stack | [TemperPass](https://temperpass.dev) |
 | `never-do` | Destructive action, force-push, or history rewrite | [TemperPass](https://temperpass.dev), [IngotVault](https://ingotvault.dev) |
 | `unclear-cause` | Failure is real; cause is not earned | [Gap Last](https://gaplast.dev) |
-| `ship-label` | Product is going public or being handed off | [xFacts](https://xfacts.dev) (AppFacts and neighbors) |
+| `ship-label` | Product is going public or being handed off | [xFacts](https://xfacts.dev) (AppFacts and neighbors), [Efficacy](https://efficacy.dev) |
 | `git-backup` | New project, or unpushed work you cannot lose; before rebase/rewrite | [IngotVault](https://ingotvault.dev) |
 | `voice-journal` | Builder captures ideas by voice, or wants a local journal | [DictaWhisper](https://dictawhisper.com) |
 

package/content/FORGETRAIL_LITE.md

@@ -8,7 +8,7 @@
 
 A single self-contained file for starting a new project in **any** agent: Cursor, Claude Code, Claude Cowork, OpenAI Codex, Cline, Aider, Continue, Windsurf, etc. **No MCP server, no vendored methodology tree, no external fetches.** Drop this file into the repo (or paste it into chat), and the agent has enough structure to run a real project end to end.
 
-**System of record:** Phase, decisions, lessons, and sessions live in `appledger/` (`profiles/forgetrail.yaml` and records). §11 is the legacy shape for `appledger migrate` only. If a legacy `.forgetrail/workflow_tracking.json` exists and is not a pointer, run `appledger migrate preview` and then apply. Do not keep a second decision log. `.forgetrail/` is the protocol, rules, and hooks.
+**System of record:** Phase, decisions, lessons, and sessions live in `appledger/` (`profiles/forgetrail.yaml` and records). `.forgetrail/` is the protocol, rules, and hooks.
 
 > **Maintainers:** Optional onboarding blocks in **§4.3**, **§4.4**, and **§7.1** are intentionally duplicated in root **`README.md`** and **`WORKFLOW.md`**. When you edit one, sync the others (see **`update-log.md`** — FORGETRAIL_LITE release checklist, item 3).
 
@@ -49,7 +49,7 @@ Any of the three works. A + C together is best. For a written pre-Phase-1 spec,
 
 ForgeTrail agent artifacts (protocol, tracking, platform rules) live in **`.forgetrail/`** at the repo root — **whether you bootstrap via ForgeTrail Lite file copy or MCP greenfield.**
 
-**Upstream ForgeTrail is open source** (Apache 2.0). In your app repo, **`.forgetrail/`** holds the protocol, rules, and hooks. Project state lives in **`appledger/`**. **MCP greenfield** does not need a tracking JSON file. **Lite file bootstrap** may copy `FORGETRAIL_LITE.md` here; you may **commit** `.forgetrail/` under the same license or **gitignore** it to keep the public repo focused on app code and to avoid duplicating a large protocol when MCP already serves updates. Never commit **secrets** (`.env`, API keys) inside the ledger or rules.
+**Upstream ForgeTrail is open source** (Apache 2.0). In your app repo, **`.forgetrail/`** holds the protocol, rules, and hooks. Project state lives in **`appledger/`**. **Lite file bootstrap** may copy `FORGETRAIL_LITE.md` here; you may **commit** `.forgetrail/` under the same license or **gitignore** it to keep the public repo focused on app code and to avoid duplicating a large protocol when MCP already serves updates. Never commit **secrets** (`.env`, API keys) inside the ledger or rules.
 
 ```
 .forgetrail/
@@ -101,7 +101,7 @@ When a boot surfaces a gap in **ForgeTrail Lite itself** (not a one-off app bug)
 
 **Optional companions:** when a job matches (Markdown site, two or more local apps, local Ollama, copy review), you may offer a sibling from the Catalyst Forge shelf. Never required. Do not list them in the first message to the human. MCP: `getCompanionSuggestions`. Full mapping lives with ForgeTrail, not in this file.
 
-**Subjects:** When the project has an application, a tool server, a skill package, an agent configuration, or a model variant, record a disposition with `appledger subjects`. A family with no subject is `not_applicable`, not a missing label. Do not generate or publish a label unless the user asks. Offering an xFacts label when the product goes public or changes hands stays optional.
+**Subjects:** When the project has an application, a tool server, a skill package, an agent configuration, or a model variant, record a disposition with `appledger subjects`. A family with no subject is `not_applicable`, not a missing label. Do not generate or publish a label unless the user asks. Offering an xFacts label when the product goes public or changes hands stays optional. An [Efficacy](https://efficacy.dev) chain in `.efficacy/` is the same kind of offer when a later agent should record a measured use of that version. The chain is not the project record.
 
 **Named ports (if they accept):** [LocalSlip](https://localslip.dev). FilePress: lease name = site `package.json` `name`. `localslip claim NAME --port N && filepress dev`. Do not pass `--port`. Vite: `localslip get` in `vite.config`, `strictPort`. Claim once. Do not write `ensure-lease.mjs`. Do not add the `localslip` package just to read a port.
 
@@ -161,7 +161,7 @@ Every project flows through these phases. The agent **pauses at every phase tran
 
 When archetype ≠ `product`, **prune** the non-applicable criteria in the profile once (and record that pruning as a decision) instead of annotating them "N/A" forever. If the project outgrows its archetype (a one-shot grows accounts), flag it and propose re-promoting to `product`.
 
-**Wrap (when the project ends):** Finishing a project includes **harvesting** it. When the app ships, is delivered, or is intentionally shelved: sweep lesson and decision records for lessons that generalize beyond this app (framework traps, CLI changes, integration surprises), record them in `FORGETRAIL_LITE_UPDATES.md` (§1.6) or propagate to the upstream ForgeTrail repo if you have one, set `project_status` to `wrapped`, and add a final session record with the end state (deploy URL, handoff notes). Small projects often surface the freshest tooling lessons — do not let them die in the repo. Optional: Cold-eye for a newcomer-readiness pass. A public xFacts label is still optional and only when the user asks. The subject disposition from the **Subjects** note above is already recorded.
+**Wrap (when the project ends):** Finishing a project includes **harvesting** it. When the app ships, is delivered, or is intentionally shelved: sweep lesson and decision records for lessons that generalize beyond this app (framework traps, CLI changes, integration surprises), record them in `FORGETRAIL_LITE_UPDATES.md` (§1.6) or propagate to the upstream ForgeTrail repo if you have one, set `project_status` to `wrapped`, and add a final session record with the end state (deploy URL, handoff notes). Small projects often surface the freshest tooling lessons — do not let them die in the repo. Optional: Cold-eye for a newcomer-readiness pass. A public xFacts label is still optional and only when the user asks. An Efficacy chain is the same kind of offer. The subject disposition from the **Subjects** note above is already recorded.
 
 ### 3.1 Feature specs (Phase 4+)
 
@@ -469,7 +469,7 @@ Output requirements
 |-----------|----------------|
 | **`status.bat`** / **`status.sh`** / **`pnpm run forgetrail:status`** | Anyone — prints phase name, open exit criteria, last session; refreshes **`docs/FORGETRAIL_PROGRESS.md`** |
 | **`docs/FORGETRAIL_PROGRESS.md`** | Plain-language snapshot (template: upstream **`FORGETRAIL_PROGRESS.md`**) |
-| **`.cursor/rules/forgetrail-phase-status.mdc`** | Cursor agent footers from tracking JSON |
+| **`.cursor/rules/forgetrail-phase-status.mdc`** | Cursor agent footers from `appledger/profiles/forgetrail.yaml` |
 | **Ask the agent** | *"What's our ForgeTrail phase and what's next?"* — it should read tracking first |
 
 **Agent:** After locking a phase or completing exit criteria, update tracking **and** either refresh **`docs/FORGETRAIL_PROGRESS.md`** or remind the user to run **status.bat**. On phase transitions, pause for explicit approval (§8 rule 1) — **status** output should not replace that conversation.

package/content/NEW_PROJECT_BOOTSTRAP.md

@@ -62,7 +62,7 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 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).
 5. Call **`getGreenfieldIntakePrompt`** — product/delivery questions: exports (PDF / DOCX / PPTX, etc.), tenancy (e.g. consultants × clients), hybrid vs full spec, compliance tier (even if “none yet”), hero flow, and registrar/DNS/git/hosting if still open. Capture answers in **`PHASE_1_BRIEF.md`** and as decision records. If using native plan mode, include these questions in the plan context (`getPlanModePatterns`). When a companion trigger is true later, call **`getCompanionSuggestions`**. Do not name companions in the first user-facing message.
-6. Call **`getTrackingSchema`** — you will maintain **`appledger/`**. Do not maintain a tracking JSON file. Optionally call **`getAgentIntegrationGuide`** for your host (`grok`, `cursor`, `claude`, `generic`) and **`getForgeTrailSkill`** if the agent supports persistent skills.
+6. Call **`getTrackingSchema`** — you will maintain **`appledger/`**. Optionally call **`getAgentIntegrationGuide`** for your host (`grok`, `cursor`, `claude`, `generic`) and **`getForgeTrailSkill`** if the agent supports persistent skills.
 7. Call **`getPhaseGuidance`** with phase `1` (architecture). Summarize understanding and propose structure, data model, integrations, and v1 scope **before** writing app code.
 8. During Phase 1, create **`docs/PHASE_1_BRIEF.md`** from **`getTemplate({ name: "PHASE_1_BRIEF" })`**, fill every section, and **lock** it; mirror major decisions as **appledger decision records**.
 9. After architecture is confirmed and the brief is locked, call **`getPhaseGuidance`** with phase `2` (scaffolding). Read the brief and **`appledger/profiles/forgetrail.yaml`**, **merge the brief into `CONTEXT_PROMPT.md`**, then execute a **single-pass app skeleton** and the rest of the Phase 2 doc set (`README`, `TODO`, `.forgetrail/IDEAS.md`).
@@ -76,7 +76,7 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 | **Pre-Phase-1 build spec (external LLM chat)** | **`getGenesisSpecPrompt`** → user saves **`docs/GENESIS.md`**; or human recipe **`TRY_FORGETRAIL.md`** (no MCP) |
 | **Feature delivery SPEC template (Phase 4+)** | **`getTemplate({ name: "SPEC_FEATURE_TEMPLATE" })`** → write `specs/[feature].md`; lifecycle in WORKFLOW Phase 4 |
 | **Approved Genesis / plan → brief + decisions** | **`ingestPlanArtifact`** — after plan approval or when `docs/GENESIS.md` exists |
-| **One-call greenfield setup** (bootstrap + tracking JSON + post-bootstrap guidance + optional Cursor rules) | **`getNewProjectKickoff`** — prefer over calling the granular tools separately |
+| **One-call greenfield setup** (bootstrap + ledger + post-bootstrap guidance + optional Cursor rules) | **`getNewProjectKickoff`** — prefer over calling the granular tools separately |
 | **Which docs in which phase** | **`getProgressiveDocSchedule`** (WORKFLOW §1a) |
 | Phase playbooks, entry/exit criteria, patterns | `getPhaseGuidance` (phases 1–7 or keywords like `scaffolding`, `hardening`) |
 | Milestone checklists | `getChecklist` (`before-session-1`, `session-1`, `session-2`, `full`, …) |
@@ -89,7 +89,7 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 | **Native plan mode as Phase 1** | **`getPlanModePatterns`** — use before scaffolding when the host supports plan-before-code |
 | **Agent-specific integration** (Grok, Cursor, Claude) | **`getAgentIntegrationGuide`** — primitive mappings and session openers |
 | **Installable forgetrail skill** (Grok etc.) | **`getForgeTrailSkill`** — copy to host skill directory |
-| **Legacy tracking classification** | **`validateTracking`** — reports a writable `workflow_tracking.json` as a conflict. A missing file is expected |
+| **Ledger check** | **`validateTracking`** — a missing file is expected |
 | **Optional companion tools** (FilePress, LocalSlip, skills, xFacts, …) | **`getCompanionSuggestions`** — `phase` or `situation`; never required; not in the first user-facing message (WORKFLOW §1f) |
 | **Parallel subagent recommendations** | **`suggestSubagentDecomposition`** — before spawning audits/research (WORKFLOW §1c) |
 | **Ledger initialization** for a greenfield repo | `getInitialWorkflowTracking` — does **not** return JSON. Create **`appledger/`** |
@@ -140,7 +140,7 @@ 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). If a legacy `.forgetrail/workflow_tracking.json` exists and is not a pointer, **`validateTracking`** reports the conflict.
+- After substantive work, update **`appledger/`** (criteria, decision records, lessons, the session).
 - 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.
 - **Git commits:** `git commit -F <file>` or plain `-m` at natural stopping points with concise summaries. Run verification checks prior to commit.

package/content/ONE_CLICK_DEV_SETUP.md

@@ -137,6 +137,6 @@ if errorlevel 1 pause
 See **FORGETRAIL_LITE.md** §4.2.2 and **`SCAFFOLD_INSTALL.json`** (`versionPolicy`). Install scripts read `POCKETBASE_VERSION` from `.env`:
 
 - unset or `latest` → resolve from GitHub **releases/latest** at setup time
-- `0.26.2` (example) → pin that release; record in `decisions[]` when the user confirms a good boot
+- `0.26.2` (example) → pin that release; record it as an appledger decision record when the user confirms a good boot
 
 Never ship a stale semver only in methodology docs without an env override path.

package/content/SESSION_RESUME_MCP.md

@@ -10,7 +10,6 @@ The user is **continuing** a project that uses ForgeTrail via the **MCP server**
 2. If the current phase is **`plan`**, read **`docs/PHASE_1_BRIEF.md`** and continue planning toward a locked brief. Otherwise read **`CONTEXT_PROMPT.md`**. If a later phase is current but CONTEXT is missing and **`PHASE_1_BRIEF.md`** exists, **merge the brief into CONTEXT** first (see CONTEXT_PROMPT template).
 3. Call **`getPhaseGuidance`** for that phase (`plan` through `harden`, or `1`–`7`). When a companion trigger is true, call **`getCompanionSuggestions`** for that phase or situation. Do not install unless the user asked.
 4. If you need checklist context, call **`getChecklist`** (e.g. `every-session` or `full`).
-5. If a **`workflow_tracking.json`** file exists and is not a pointer, do not update it. Run **`appledger migrate preview`**, then apply. Call **`validateTracking`** only to classify that file.
 
 Do **not** require `_forgetrail/WORKFLOW.md` or `_forgetrail/TRACKING_SCHEMA.md` on disk — use the MCP tools above.
 

package/content/SYSTEM_HEALTH_CHECKS.md

@@ -69,7 +69,7 @@ OLLAMA_MODEL=ibm/granite4.1:8b
 # SKIP_OLLAMA_INSTALL=1  # skip entire setup
 ```
 
-Pin **`OLLAMA_MODEL`** after a successful **test-ollama** run; log in **`decisions[]`**.
+Pin **`OLLAMA_MODEL`** after a successful **test-ollama** run, and record that pin as an appledger decision record.
 
 ---
 

package/content/companion-tools.json

@@ -204,6 +204,11 @@
           "name": "xFacts",
           "homepage": "https://xfacts.dev",
           "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."
+        },
+        {
+          "name": "Efficacy",
+          "homepage": "https://efficacy.dev",
+          "offer": "When a later agent should inspect a measured use of this exact version, offer an Efficacy chain in .efficacy/. The chain is optional. Verify shows the record is intact and bound to its evidence. It does not show the claim is true."
         }
       ]
     },

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

@@ -19,7 +19,7 @@ The human pasted the kickoff line from [TRY_FORGETRAIL.md](../../TRY_FORGETRAIL.
 3. Recorded one decision and one lesson.
 4. Stopped after the human approved the brief. No application scaffold yet.
 
-The CLI, if used instead of a hand copy, writes the Lite file, hook scripts, and an optional Genesis stub. It does not write a tracking JSON file and it does not fill in the phase, decisions, or session. Those writes depend on the agent following the protocol.
+The CLI, if used instead of a hand copy, writes the Lite file, hook scripts, and an optional Genesis stub. It does not fill in the phase, decisions, or session. Those writes depend on the agent following the protocol.
 
 ### What was left unfinished
 
@@ -67,8 +67,6 @@ That is the trail: a phase, a decision, a lesson, and a next step. The next chat
 
 MCP tools can hand the agent the same protocol and a lessons search. They do not replace the files in the app repo.
 
-An existing writable `.forgetrail/workflow_tracking.json` is legacy. `appledger migrate preview` writes nothing. `apply` imports decisions, sessions, resolved gotchas as lessons, unresolved gotchas as open questions, and `IDEAS.md` / `BUGS.md` from the repository root and from `.forgetrail/`, then replaces the file with a pointer. The `appledger` package is not a published npm release. Use the [repository](https://github.com/Catalyst-Forge-LLC/appledger).
-
 ## Catalog excerpt
 
 Keep project decisions, development state, and lessons in the repository so the next session can continue. After one sitting you should see `appledger/` with a phase, a decision, and a session next step. Full walk-through: this file, and the [continuity](https://forgetrail.dev/docs/continuity) page. The live site still shows the previous pages until it is redeployed.

package/content/hooks/README.md

@@ -6,10 +6,11 @@ Enforces ForgeTrail rules and guards at the host tool level, rather than relying
 
 - `guard-shell.mjs`: runs pre-commit verification (`pnpm run verify`), prevents npm/yarn when `pnpm-lock.yaml` is present, allows `ingotvault` (asks before `--force-with-lease`), asks before any `git push`, and prompts on destructive git or filesystem operations.
 - `guard-edit.mjs`: guards `.env*` secrets files and `specs/completed/**` or `specs/canonical/**` records against accidental mutation.
-- `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.
+- `session-start.mjs`: on session start, points the session at `appledger/`. When `appledger` is on PATH it appends `appledger orient --budget 300`.
+- `appledger-bin.mjs`: finds the `appledger` command. A missing command is not a failure.
+- `validate-tracking.mjs`: after an edit under `appledger/`, runs `appledger check` when the command is on PATH and reports warnings.
 - `validate-tracking-core.mjs`: standalone zero-dependency tracking validator.
-- `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.
+- `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.
 - `cursor-hooks.json`: standard Cursor hooks configuration.
 - `claude-settings-hooks.json`: standard Claude Code configuration fragment.
 

package/content/hooks/appledger-bin.mjs

@@ -0,0 +1,33 @@
+/**
+ * Find and run the appledger CLI from PATH.
+ * A missing command is absent, not a failure. Hooks keep their previous text in that case.
+ */
+
+import { spawnSync } from "node:child_process";
+
+export function findAppledger() {
+  const finder = process.platform === "win32" ? "where.exe" : "which";
+  const found = spawnSync(finder, ["appledger"], { encoding: "utf8", windowsHide: true });
+  if (found.status !== 0) return null;
+  const line = found.stdout
+    .split(/\r?\n/)
+    .map((item) => item.trim())
+    .find(Boolean);
+  return line || null;
+}
+
+export function runAppledger(args, cwd) {
+  const bin = findAppledger();
+  if (!bin) return { absent: true, status: null, text: "" };
+  const script = /\.(cmd|bat)$/i.test(bin);
+  const result = spawnSync(bin, args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 20_000,
+    windowsHide: true,
+    shell: script,
+  });
+  if (result.error?.code === "ENOENT") return { absent: true, status: null, text: "" };
+  const text = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+  return { absent: false, status: result.status, text };
+}

package/content/hooks/session-start.mjs

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { runAppledger } from "./appledger-bin.mjs";
 
 function walkUp(startDir, found) {
   let curr = resolve(startDir || process.cwd());
@@ -54,6 +55,11 @@ 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.");
+    const orient = runAppledger(["orient", "--budget", "300"], ledgerRoot);
+    if (!orient.absent && orient.text) {
+      lines.push("");
+      lines.push(orient.text);
+    }
   }
 
   if (trackingPath) {

package/content/hooks/validate-tracking.mjs

@@ -7,7 +7,17 @@
  */
 
 import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
 import { validateTrackingData, formatValidationResult } from "./validate-tracking-core.mjs";
+import { runAppledger } from "./appledger-bin.mjs";
+
+function ledgerRoot(filePath) {
+  if (!filePath) return null;
+  const abs = resolve(filePath).replaceAll("\\", "/");
+  const at = abs.toLowerCase().lastIndexOf("/appledger/");
+  if (at === -1) return null;
+  return abs.slice(0, at);
+}
 
 function readStdin() {
   try {
@@ -27,6 +37,22 @@ function main() {
     payload.tool_input?.path ||
     "";
 
+  const ledger = ledgerRoot(filePath);
+  if (ledger) {
+    const check = runAppledger(["check", "--root", ledger], ledger);
+    const noisy = !check.absent && (check.status !== 0 || /warning|error/i.test(check.text));
+    if (noisy && check.text) {
+      console.log(
+        JSON.stringify({
+          additional_context: `=== ForgeTrail ledger check ===\n${check.text}\n================================`,
+        })
+      );
+      return;
+    }
+    console.log(JSON.stringify({}));
+    return;
+  }
+
   if (!filePath.endsWith("workflow_tracking.json")) {
     console.log(JSON.stringify({}));
     return;

package/content/skills/forgetrail/SKILL.md

@@ -28,7 +28,6 @@ You are operating under the ForgeTrail methodology. Your primary job is to give
    - Read `CONTEXT_PROMPT.md` and `TODO.md` if they exist.
    - Call `getPhaseGuidance` for the current phase if needed.
    - Summarize current phase, pending criteria, and recent decisions to the user briefly.
-   - If `workflow_tracking.json` exists and is not a pointer, do not edit it. Run `appledger migrate preview`, then apply.
 
 3. **Pause at phase transitions**:
    - When you believe exit criteria for the current phase are met, explicitly tell the user: "I think we have completed Phase X because [reasons]. The remaining exit criteria are [list]. Ready to move to Phase Y?"
@@ -87,7 +86,7 @@ Call `getResumeSessionInstructions` (or read `appledger/profiles/forgetrail.yaml
 - `getTemplate({name: "..."})` — for PHASE_1_BRIEF, CONTEXT_PROMPT, audits, etc. Use mode "shell" for clean structure.
 - `runAudit`, `searchLessons`, `getAntiPatterns`
 - `suggestSubagentDecomposition` (when subagents available)
-- `validateTracking` (classify a legacy `workflow_tracking.json`; a missing file is expected)
+- `validateTracking` (a missing file is expected)
 - `ingestPlanArtifact` (after native plan mode approval — map plan → PHASE_1_BRIEF + decision records)
 - `todo_write` — mirror open exit criteria and next actions.
 

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.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` |
+| [`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` |
 
 These are **installer and MCP channels**, not a library. App repos should not add `forgetrail` to `dependencies`.
 
-`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.
+`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.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgetrail",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "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/prompts/propagate-to-forgetrail.md

@@ -2,15 +2,15 @@
 
 Run this prompt after implementing a new feature, pattern, plan, or significant enhancement in your app. It generalizes **both** durable **feature shapes** (what to document in **`TECHNICAL_REFERENCE.md`**, **`TEST_PLAN.md`**, brand/design templates) **and** reusable **lessons** (callouts in templates), then updates ForgeTrail so future projects start with that guidance.
 
-**Any ForgeTrail project is a valid source** — not just the flagship app that seeded these templates. A weekend one-shot with two gotchas in its tracking file propagates the same way a mature SaaS does; small projects often exercise the newest tool versions and surface the freshest scaffolding lessons. If your project has only a handful of docs (Lite bootstrap, `one-shot` archetype), skip the doc-inventory ceremony and use **Harvest mode** below.
+**Any ForgeTrail project is a valid source** — not just the flagship app that seeded these templates. A weekend one-shot with two lessons in its ledger propagates the same way a mature SaaS does; small projects often exercise the newest tool versions and surface the freshest scaffolding lessons. If your project has only a handful of docs (Lite bootstrap, `one-shot` archetype), skip the doc-inventory ceremony and use **Harvest mode** below.
 
 ### Harvest mode (small projects and project wrap)
 
-Use this when the source project is **small** (no product journal, minimal doc set) or you are running the **wrap protocol** (WORKFLOW.md §1e) at project end. The primary discovery source is the **tracking file**, not the doc tree:
+Use this when the source project is **small** (no product journal, minimal doc set) or you are running the **wrap protocol** (WORKFLOW.md §1e) at project end. The primary discovery source is the **ledger**, not the doc tree:
 
-1. **Read `.forgetrail/workflow_tracking.json`** — every `gotchas[]` entry and every `decisions[]` entry — plus `CONTEXT_PROMPT.md`'s gotcha/pattern sections and any `FORGETRAIL_LITE_UPDATES.md`.
+1. **Read appledger decision records and lesson records**, plus `CONTEXT_PROMPT.md`'s gotcha/pattern sections and any `FORGETRAIL_LITE_UPDATES.md`.
 2. **Classify each entry:** *generalizable* (framework traps, CLI behavior changes, scaffolding surprises, integration lessons — anything a different project on the same stack could hit) vs *app-specific* (content decisions, domain rules). Only the first group propagates.
-3. **For each generalizable entry**, run the normal Step 2 dedupe (grep ForgeTrail for existing coverage) and Step 3 mapping (which template gets it). Tracking-file gotchas usually land as **pattern memory** (`CONTEXT_PROMPT.md` callouts, `FORGETRAIL_LITE.md` scaffolding notes); occasionally a decision reveals a **feature shape** worth a stub.
+3. **For each generalizable entry**, run the normal Step 2 dedupe (grep ForgeTrail for existing coverage) and Step 3 mapping (which template gets it). Ledger lessons usually land as **pattern memory** (`CONTEXT_PROMPT.md` callouts, `FORGETRAIL_LITE.md` scaffolding notes); occasionally a decision reveals a **feature shape** worth a stub.
 4. **Zero-yield is fine.** If nothing generalizes, say so and skip the update-log entry — do not pad.
 
 Harvest mode replaces the Discovery scan and Journal-driven sections for these projects; everything from Step 2 onward applies unchanged.
@@ -44,7 +44,7 @@ When you run a **periodic** propagation (catch-up after a sprint, or anytime **A
 
 ## Context
 
-**Your app** is the live project. Its docs are the source of truth — **whichever of these exist**. A full Phase-7 product will have most of them; a Lite or `one-shot` project may have only `CONTEXT_PROMPT.md`, `README.md`, `TODO.md`, and the tracking file (use **Harvest mode** above in that case). Treat this list as a menu, not a requirement:
+**Your app** is the live project. Its docs are the source of truth — **whichever of these exist**. A full Phase-7 product will have most of them; a Lite or `one-shot` project may have only `CONTEXT_PROMPT.md`, `README.md`, `TODO.md`, and `appledger/` (use **Harvest mode** above in that case). Treat this list as a menu, not a requirement:
 
 - `CONTEXT_PROMPT.md`
 - `docs/PHASE_1_BRIEF.md` (if you improved the Phase 1 handoff template)
@@ -91,7 +91,7 @@ Run after meaningful implementation work **and** after substantive **documentati
 | **Isolated service health checks / local Ollama** (test PB without app; install Ollama + VRAM model + completion test; avoid thinking models by default) | **`SYSTEM_HEALTH_CHECKS.md`**, **`FORGETRAIL_LITE.md`** §4.7–§4.8; **`scripts/test-pocketbase.mjs`**, **`scripts/setup-ollama.mjs`**, **`scripts/test-ollama.mjs`**, **`SCAFFOLD_INSTALL.json`** `systemHealthChecks` |
 | **URL / listing import pipeline** (fetch + HTML parse, refresh-from-source, optional LLM-assisted recover when selectors drift) | `docs/TECHNICAL_REFERENCE.md` (*URL import* — paywalls, **markup drift / optional recover**); `docs/CONTEXT_PROMPT.md`; `docs/TEST_PLAN.md` §2a; **`content/FORGETRAIL_LITE.md` §7.2**; partial spec stub under **`specs/partial/`** when shipped behavior needs follow-up. |
 | **A week+ of shipping without running this prompt** | Use **Journal-driven propagation**: sweep **`docs/PRODUCT_JOURNAL.md`** (e.g. last 10–14 days) so **Added** / **Improved** items get **`TECHNICAL_REFERENCE` / `TEST_PLAN`** stubs, not only **CONTEXT_PROMPT** lessons. |
-| **Project wrap — the source project is finished, delivered, or shelved** | Run **Harvest mode** (top of this prompt) as part of the wrap protocol (**WORKFLOW.md §1e**): sweep the tracking file's `gotchas[]` + `decisions[]` before the project goes quiet. Small projects count. |
+| **Project wrap — the source project is finished, delivered, or shelved** | Run **Harvest mode** (top of this prompt) as part of the wrap protocol (**WORKFLOW.md §1e**): sweep appledger lesson records and decision records before the project goes quiet. Small projects count. |
 | **CI/CD, Node/`engines`, or package-manager pins changed** | Keep workflow, container, and `package.json` in sync — lessons for **DEPLOYMENT.md**, **TECHNICAL_REFERENCE.md**, **CONTEXT_PROMPT.md**. |
 | **Deploy scripts, systemd units, or process stop/restart behavior** | `TimeoutStopSec`, blue-green `systemctl stop`, and graceful-shutdown tradeoffs affect **wall-clock deploy time** as well as request safety — **DEPLOYMENT.md** (and **CONTEXT_PROMPT** if it changes operator expectations). |
 | **New scripts, hooks, or dev-tooling** | Journal/lint/build wrappers → **CONTEXT_PROMPT** (tooling) or **TECHNICAL_REFERENCE** (pipelines). |
@@ -109,7 +109,7 @@ Do **not** rely only on the immediate trigger. Skim **multiple signal sources**
 
 | Source | What to extract |
 |--------|-----------------|
-| **`.forgetrail/workflow_tracking.json`** (`gotchas[]`, `decisions[]`) | Framework traps, CLI/scaffolding surprises, and integration lessons logged during the build — the primary source for small projects (see **Harvest mode**), and an easy-to-miss one for large projects where docs lag the tracking file. |
+| **`appledger/` decision and lesson records** | Framework traps, CLI/scaffolding surprises, and integration lessons logged during the build — the primary source for small projects (see **Harvest mode**), and an easy-to-miss one for large projects where docs lag the ledger. |
 | **`git log` / recent commits** | Subjects and paths; cluster related work; compare to the last `update-log.md` propagation date. |
 | **`docs/PRODUCT_JOURNAL.md`** (or git-derived changelog) | Day-level themes across UX, infra, and docs. Map **`Added`** / major **`Improved`** items to Step 3: new **feature-area** stubs in **`TECHNICAL_REFERENCE.md`**, **`TEST_PLAN.md`** checks, **`BRAND_AND_PRODUCT.md`** / **`DESIGN_SYSTEM.md`** when IA or positioning changes—not only **`CONTEXT_PROMPT.md`** bullets. |
 | **Recently touched `specs/`** | Durable architecture and copy decisions, including WIP specs. |

package/prompts/second-family-critique.md

@@ -40,4 +40,4 @@ When the second model returns its review:
 
 1. **Verify observations against codebase reality:** Not all critiques apply if the opposing model lacked local file context.
 2. **Update the spec:** Add newly discovered edge cases to the Edge Cases section; tighten acceptance criteria.
-3. **Log architectural pivots:** If a critique exposes an unviable path, log the alternative in `decisions[]` in `workflow_tracking.json`.
+3. **Log architectural pivots:** If a critique exposes an unviable path, record the alternative as an appledger decision record.

package/scripts/forgetrail-cli.mjs

@@ -37,7 +37,7 @@ Install options:
   --with-genesis-stub  With --lite: also create docs/GENESIS.md stub
   --force, -f        Overwrite existing files
   --dry-run          Preview without writing
-  --skip-tracking    Accepted and ignored. A tracking JSON file is not installed.
+  --skip-tracking    Accepted and ignored.
   --path, -p <dir>   Install elsewhere (default: current directory)
   --help, -h         Show help
   --version, -v      Print the forgetrail version

package/scripts/install.mjs

@@ -38,6 +38,7 @@ const HOOK_FILES = [
   "guard-shell.mjs",
   "guard-edit.mjs",
   "session-start.mjs",
+  "appledger-bin.mjs",
   "validate-tracking.mjs",
   "validate-tracking-core.mjs",
   "session-stop.mjs",
@@ -142,7 +143,7 @@ export function runInstallLite(rawArgv, { defaultToCwd = false } = {}) {
 
   console.log("\nDone.");
   console.log("  Protocol:  .forgetrail/FORGETRAIL_LITE.md");
-  console.log("  Project record: appledger/ (a tracking JSON file is not installed)");
+  console.log("  Project record: appledger/");
   console.log("  Hooks:     .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
   if (args.withGenesisStub) {
     console.log("  Genesis:   docs/GENESIS.md (stub — replace with your spec)");
@@ -168,7 +169,7 @@ Usage:
 Options:
   --path, -p <dir>   Target project root (default: current directory for \`forgetrail\` CLI)
   --force, -f        Overwrite existing files
-  --skip-tracking    Accepted and ignored. A tracking JSON file is not installed.
+  --skip-tracking    Accepted and ignored.
   --dry-run          Print actions only
 
 Installs:
@@ -186,7 +187,7 @@ Usage:
 Options:
   --path, -p <dir>        Target project root (default: current directory for \`forgetrail\` CLI)
   --force, -f             Overwrite existing files
-  --skip-tracking         Accepted and ignored. A tracking JSON file is not installed.
+  --skip-tracking         Accepted and ignored.
   --with-genesis-stub     Also create docs/GENESIS.md stub (for the Try path)
   --dry-run               Print actions only
 

package/scripts/tracking-cutover.test.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, readFileSync, writeFileSync, mkdirSync, utimesSync } from "node:fs";
+import { mkdtempSync, readFileSync, writeFileSync, mkdirSync, utimesSync, chmodSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -94,6 +94,70 @@ test("session start warns on a legacy file and does not quote it as the live pha
   assert.doesNotMatch(payload.additional_context, /Current Phase: 4-feature-iteration/);
 });
 
+function stubAppledger(dir, line) {
+  const stub = join(dir, "bin");
+  mkdirSync(stub, { recursive: true });
+  if (process.platform === "win32") {
+    writeFileSync(join(stub, "appledger.cmd"), `@echo off\r\necho ${line}\r\n`);
+  } else {
+    const file = join(stub, "appledger");
+    writeFileSync(file, `#!/bin/sh\necho ${line}\n`);
+    chmodSync(file, 0o755);
+  }
+  const system = process.env.SystemRoot ? `${process.env.SystemRoot}\\System32` : "/usr/bin";
+  const sep = process.platform === "win32" ? ";" : ":";
+  return { PATH: [stub, system, process.env.PATH].filter(Boolean).join(sep) };
+}
+
+function runHook(script, dir, { input, env } = {}) {
+  return spawnSync(process.execPath, [join(root, "content", "hooks", script)], {
+    cwd: dir,
+    input,
+    encoding: "utf8",
+    env: env ? { ...process.env, ...env } : process.env,
+  });
+}
+
+test("session start includes orient when appledger is on PATH", () => {
+  const dir = mkdtempSync(join(tmpdir(), "ft-orient-"));
+  mkdirSync(join(dir, "appledger"), { recursive: true });
+  writeFileSync(join(dir, "appledger", "manifest.yaml"), "format: appledger\n");
+  const result = runHook("session-start.mjs", dir, { env: stubAppledger(dir, "STUB-ORIENT") });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(JSON.parse(result.stdout).additional_context, /STUB-ORIENT/);
+});
+
+test("session start keeps the ledger text when appledger is absent", () => {
+  const dir = mkdtempSync(join(tmpdir(), "ft-noap-"));
+  mkdirSync(join(dir, "appledger"), { recursive: true });
+  writeFileSync(join(dir, "appledger", "manifest.yaml"), "format: appledger\n");
+  const system = process.env.SystemRoot ? `${process.env.SystemRoot}\\System32` : "/usr/bin";
+  const result = runHook("session-start.mjs", dir, { env: { PATH: system } });
+  assert.equal(result.status, 0, result.stderr);
+  const text = JSON.parse(result.stdout).additional_context;
+  assert.match(text, /Project record: appledger/);
+  assert.doesNotMatch(text, /STUB-ORIENT/);
+});
+
+test("an edit under appledger/ runs check and reports a warning", () => {
+  const dir = mkdtempSync(join(tmpdir(), "ft-check-"));
+  mkdirSync(join(dir, "appledger"), { recursive: true });
+  const manifest = join(dir, "appledger", "manifest.yaml");
+  writeFileSync(manifest, "format: appledger\n");
+  const warned = runHook("validate-tracking.mjs", dir, {
+    input: JSON.stringify({ path: manifest }),
+    env: stubAppledger(dir, "warning missing_source example"),
+  });
+  assert.equal(warned.status, 0, warned.stderr);
+  assert.match(JSON.parse(warned.stdout).additional_context, /warning missing_source example/);
+  const clean = runHook("validate-tracking.mjs", dir, {
+    input: JSON.stringify({ path: manifest }),
+    env: stubAppledger(join(dir, "clean"), "ok ledger"),
+  });
+  assert.equal(clean.status, 0, clean.stderr);
+  assert.deepEqual(JSON.parse(clean.stdout), {});
+});
+
 test("Lite and workflow instructions name the ledger", () => {
   const lite = readFileSync(join(root, "content", "FORGETRAIL_LITE.md"), "utf8");
   const legacyAt = lite.indexOf("## 11. Legacy");
@@ -180,6 +244,7 @@ test("session stop reminds only after work newer than the session record", () =>
 
 test("kickoff names appledger init and does not require the tracking file", () => {
   const kickoff = readFileSync(join(root, "mcp-server", "src", "index.ts"), "utf8");
+  assert.match(kickoff, /z\.union\(\[z\.string\(\), z\.number\(\)\]\)/);
   assert.match(kickoff, /appledger init/);
   assert.doesNotMatch(kickoff, /no separate init command/);
   const plan = readFileSync(join(root, "content", "PLAN_MODE_PATTERNS.md"), "utf8");