forgetrail 0.4.20 → 0.5.0

package/content/hooks/session-start.mjs

@@ -3,20 +3,17 @@
 /**
  * ForgeTrail Session Start Context Injector
  * Hook event: sessionStart (Cursor)
- * Injects live ForgeTrail phase status and open exit criteria into session context.
- * Retires static phase-status rules on hosts with hook support.
+ * Points the session at appledger/. A legacy workflow_tracking.json is a conflict, not the live phase.
  */
 
-import { readFileSync, existsSync } from "node:fs";
-import { resolve, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 
-function findTrackingFile(startDir) {
+function walkUp(startDir, found) {
   let curr = resolve(startDir || process.cwd());
   for (let i = 0; i < 6; i++) {
-    const candidate1 = join(curr, ".forgetrail", "workflow_tracking.json");
-    if (existsSync(candidate1)) return candidate1;
-    const candidate2 = join(curr, "workflow_tracking.json");
-    if (existsSync(candidate2)) return candidate2;
+    const hit = found(curr);
+    if (hit) return hit;
     const parent = resolve(curr, "..");
     if (parent === curr) break;
     curr = parent;
@@ -24,70 +21,68 @@ function findTrackingFile(startDir) {
   return null;
 }
 
-function main() {
-  const trackingPath = findTrackingFile(process.cwd());
-
-  if (!trackingPath) {
-    console.log(JSON.stringify({}));
-    return;
-  }
-
-  try {
-    const tracking = JSON.parse(readFileSync(trackingPath, "utf-8"));
-    const projectName = tracking.project?.name || "App";
-    const phase = tracking.currentPhase || "1";
-    const isLite = tracking.schemaVersion === "lite-1";
+function findLedger(startDir) {
+  return walkUp(startDir, (dir) => {
+    const manifest = join(dir, "appledger", "manifest.yaml");
+    if (existsSync(manifest)) return dir;
+    return null;
+  });
+}
 
-    let remaining = [];
-    if (isLite) {
-      const phaseObj = tracking.phases?.[String(phase)];
-      if (phaseObj?.exitCriteria) {
-        remaining = Object.entries(phaseObj.exitCriteria)
-          .filter(([_, met]) => !met)
-          .map(([flag]) => flag);
-      }
-    } else {
-      const phaseObj = tracking.phases?.[phase];
-      if (Array.isArray(phaseObj?.exitCriteriaRemaining)) {
-        remaining = phaseObj.exitCriteriaRemaining;
-      }
-    }
+function findProjectTracking(startDir) {
+  return walkUp(startDir, (dir) => {
+    const candidate = join(dir, ".forgetrail", "workflow_tracking.json");
+    if (existsSync(candidate)) return candidate;
+    const rootStarter = join(dir, "workflow_tracking.json");
+    const methodology = existsSync(join(dir, "WORKFLOW.md")) && existsSync(join(dir, "content"));
+    if (existsSync(rootStarter) && !methodology) return rootStarter;
+    return null;
+  });
+}
 
-    let lastLeftOff = "";
-    if (Array.isArray(tracking.sessions) && tracking.sessions.length > 0) {
-      const lastSession = tracking.sessions[tracking.sessions.length - 1];
-      lastLeftOff = lastSession.leftOff || lastSession.notes || "";
-    }
+function isPointer(data) {
+  return data?.status === "pointer" && typeof data.record === "string" && data.record.replaceAll("\\", "/").includes("appledger");
+}
 
-    const lines = [
-      `=== ForgeTrail Context (${projectName}) ===`,
-      `Current Phase: ${phase} (${isLite ? "Lite schema" : "MCP schema"})`,
-    ];
+function main() {
+  const ledgerRoot = findLedger(process.cwd());
+  const trackingPath = findProjectTracking(process.cwd());
+  const lines = [];
 
-    if (lastLeftOff) {
-      lines.push(`Last Session Left Off: ${lastLeftOff}`);
-    }
+  if (ledgerRoot) {
+    lines.push("=== ForgeTrail Context ===");
+    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 (remaining.length > 0) {
-      lines.push("Open Exit Criteria for Current Phase:");
-      for (const item of remaining.slice(0, 5)) {
-        lines.push(`  - ${item}`);
-      }
-      if (remaining.length > 5) {
-        lines.push(`  ...and ${remaining.length - 5} more`);
+  if (trackingPath) {
+    try {
+      const tracking = JSON.parse(readFileSync(trackingPath, "utf-8"));
+      if (isPointer(tracking)) {
+        if (!ledgerRoot) {
+          lines.push("=== ForgeTrail Context ===");
+          lines.push("workflow_tracking.json is a pointer to appledger/. Do not write decisions, sessions, or phase status there.");
+        }
+      } else {
+        lines.push("=== Legacy tracking conflict ===");
+        lines.push("workflow_tracking.json is not the system of record.");
+        lines.push("Do not add decisions, sessions, or phase status to it.");
+        lines.push("Run `appledger migrate preview`, then apply once, and write only in appledger/.");
       }
+    } catch {
+      lines.push("workflow_tracking.json could not be read. Do not recreate it. Use appledger/.");
     }
+  }
 
-    lines.push("========================================");
-
-    console.log(
-      JSON.stringify({
-        additional_context: lines.join("\n"),
-      })
-    );
-  } catch {
+  if (lines.length === 0) {
     console.log(JSON.stringify({}));
+    return;
   }
+
+  lines.push("========================================");
+  console.log(JSON.stringify({ additional_context: lines.join("\n") }));
 }
 
 main();

package/content/hooks/session-stop.mjs

@@ -3,19 +3,17 @@
 /**
  * ForgeTrail Session Stop Check
  * Hook event: stop (Cursor)
- * Prompts a reminder if a session concluded without updating sessions[] in tracking.
+ * Reminds the agent to update the AppLedger session, not a tracking JSON file.
  */
 
-import { readFileSync, existsSync } from "node:fs";
-import { resolve, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 
-function findTrackingFile(startDir) {
+function walkUp(startDir, found) {
   let curr = resolve(startDir || process.cwd());
   for (let i = 0; i < 6; i++) {
-    const candidate1 = join(curr, ".forgetrail", "workflow_tracking.json");
-    if (existsSync(candidate1)) return candidate1;
-    const candidate2 = join(curr, "workflow_tracking.json");
-    if (existsSync(candidate2)) return candidate2;
+    const hit = found(curr);
+    if (hit) return hit;
     const parent = resolve(curr, "..");
     if (parent === curr) break;
     curr = parent;
@@ -23,32 +21,53 @@ function findTrackingFile(startDir) {
   return null;
 }
 
+function findLedger(startDir) {
+  return walkUp(startDir, (dir) => (existsSync(join(dir, "appledger", "manifest.yaml")) ? dir : null));
+}
+
+function findProjectTracking(startDir) {
+  return walkUp(startDir, (dir) => {
+    const candidate = join(dir, ".forgetrail", "workflow_tracking.json");
+    if (existsSync(candidate)) return candidate;
+    return null;
+  });
+}
+
+function isPointer(data) {
+  return data?.status === "pointer" && typeof data.record === "string" && data.record.replaceAll("\\", "/").includes("appledger");
+}
+
 function main() {
-  const trackingPath = findTrackingFile(process.cwd());
-  if (!trackingPath) {
-    console.log(JSON.stringify({}));
+  const ledgerRoot = findLedger(process.cwd());
+  const trackingPath = findProjectTracking(process.cwd());
+  let legacy = false;
+  if (trackingPath) {
+    try {
+      legacy = !isPointer(JSON.parse(readFileSync(trackingPath, "utf-8")));
+    } catch {
+      legacy = true;
+    }
+  }
+
+  if (legacy) {
+    console.log(
+      JSON.stringify({
+        followup_message:
+          "ForgeTrail reminder: workflow_tracking.json is a legacy file. Do not append sessions to it. Run `appledger migrate preview`, then apply, and record this session in appledger/.",
+      })
+    );
     return;
   }
 
-  try {
-    const tracking = JSON.parse(readFileSync(trackingPath, "utf-8"));
-    const sessions = tracking.sessions;
-
-    const today = new Date().toISOString().slice(0, 10);
-    const hasTodaySession =
-      Array.isArray(sessions) &&
-      sessions.some((s) => s.date === today || (s.timestamp && s.timestamp.startsWith(today)));
-
-    if (!hasTodaySession) {
-      console.log(
-        JSON.stringify({
-          followup_message:
-            "ForgeTrail Reminder: Update .forgetrail/workflow_tracking.json (sessions[], decisions[], gotchas[]) with what was accomplished before ending.",
-        })
-      );
-      return;
-    }
-  } catch {}
+  if (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.",
+      })
+    );
+    return;
+  }
 
   console.log(JSON.stringify({}));
 }

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

@@ -41,6 +41,26 @@ function isLiteSchema(data) {
   return data && data.schemaVersion === "lite-1";
 }
 
+const LEGACY_TRACKING_ISSUE =
+  "Legacy writable tracking is not the system of record. Do not add decisions, sessions, or phase status to this file. Run `appledger migrate preview`, then apply once, and write only in appledger/.";
+
+const POINTER_WARNING =
+  "This file is a pointer to appledger/. Do not add decisions, sessions, or phase status here.";
+
+function isPointer(data) {
+  return data.status === "pointer" && typeof data.record === "string" && data.record.replaceAll("\\", "/").includes("appledger");
+}
+
+function isLegacyTracking(data) {
+  return (
+    "currentPhase" in data ||
+    "phases" in data ||
+    "decisions" in data ||
+    "sessions" in data ||
+    "schemaVersion" in data
+  );
+}
+
 export function validateTrackingData(data) {
   const issues = [];
   const warnings = [];
@@ -50,6 +70,15 @@ export function validateTrackingData(data) {
     return { issues, warnings };
   }
 
+  if (isPointer(data)) {
+    warnings.push(POINTER_WARNING);
+    return { issues, warnings };
+  }
+
+  if (isLegacyTracking(data)) {
+    issues.push(LEGACY_TRACKING_ISSUE);
+  }
+
   const project = data.project;
   if (!project || typeof project !== "object") {
     issues.push("Missing top-level project object.");
@@ -214,7 +243,11 @@ export function formatValidationResult(result) {
   const { issues, warnings } = result;
 
   if (issues.length === 0 && warnings.length === 0) {
-    return "Tracking file looks structurally healthy.";
+    return "No workflow_tracking.json is required. Project state lives in appledger/.";
+  }
+
+  if (issues.length === 0 && warnings.every((item) => item.includes("pointer"))) {
+    return "Pointer accepted. Project state lives in appledger/.\n\n" + warnings.map((item) => `- ${item}`).join("\n");
   }
 
   const parts = [];

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

@@ -143,9 +143,19 @@ async function cmdRun() {
 
 function renderProgress() {
   if (!existsSync(trackingPath)) {
-    return { text: "No .forgetrail/workflow_tracking.json yet — agent bootstrap not finished.", md: null };
+    return {
+      text: "No workflow_tracking.json. Phase state belongs in appledger/profiles/forgetrail.yaml.",
+      md: null,
+    };
   }
   const t = JSON.parse(readFileSync(trackingPath, "utf8"));
+  const record = typeof t.record === "string" ? t.record.replaceAll("\\", "/") : "";
+  if (t.status === "pointer" && record.includes("appledger")) {
+    return {
+      text: "workflow_tracking.json is a pointer to appledger/. Read appledger/profiles/forgetrail.yaml.",
+      md: null,
+    };
+  }
   const phase = t.currentPhase ?? "?";
   const phaseId = String(phase);
   const phaseBlock = t.phases?.[phaseId];
@@ -168,7 +178,7 @@ function renderProgress() {
   const md = [
     "# ForgeTrail progress",
     "",
-    "_Human-readable snapshot. Source of truth: `.forgetrail/workflow_tracking.json`._",
+    "_Human-readable snapshot read from a legacy workflow_tracking.json. After migrate, the source of truth is `appledger/profiles/forgetrail.yaml`._",
     "",
     `**Current phase:** ${label} (\`${phaseId}\`) — **${status}**`,
     "",

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 .forgetrail/workflow_tracking.json 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."
+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."
 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,27 +21,28 @@ 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 `currentPhase` and exit criteria in tracking.
+   Phases 4 and 5 commonly alternate. Update `current_phase_instance` and criteria in `appledger/profiles/forgetrail.yaml`. Do not write `workflow_tracking.json`.
 
 2. **At the start of every session or major turn**:
-   - Read `.forgetrail/workflow_tracking.json` (create `.forgetrail/` if missing).
+   - Read `appledger/profiles/forgetrail.yaml` and the latest session record.
    - Read `CONTEXT_PROMPT.md` and `TODO.md` if they exist.
    - Call `getPhaseGuidance` for the current phase if needed.
-   - Summarize current phase, exit criteria met/remaining, and recent decisions to the user briefly.
+   - 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?"
-   - Wait for explicit user approval before advancing `currentPhase` in tracking.
+   - Wait for explicit user approval before changing `current_phase_instance`.
 
-4. **Maintain the tracking file** (`.forgetrail/workflow_tracking.json`):
-   - Log every major decision with rationale and alternatives_considered.
-   - Move items from `exitCriteriaRemaining` to `exitCriteriaMet`.
-   - Add to `gotchas[]` immediately when something surprising or painful happens.
-   - Append session notes at natural breaks.
-   - Use the schema from `getTrackingSchema`.
+4. **Maintain `appledger/`**:
+   - Log every major decision as a decision record with rationale.
+   - 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`) + `decisions[]`.
+   - 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`.
    - 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.
 
@@ -68,18 +69,17 @@ You are operating under the ForgeTrail methodology. Your primary job is to give
 ## Phase Transition Protocol
 
 When ready to advance:
-- Confirm all exit criteria.
-- Update tracking.
-- Ask user: "Ready to move to Phase X?"
-- Only after confirmation, update `currentPhase` and start the next phase's playbook.
+- 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`.
 
 ## For New Projects (Greenfield)
 
-Prefer calling `getNewProjectKickoff` (or `kickoffGreenfield`) at the very beginning. Write the returned `.forgetrail/workflow_tracking.json`, 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. Do not write `workflow_tracking.json`. Write optional Cursor rules, and follow the post-bootstrap instructions exactly. Then start with Phase 1.
 
 ## For Resuming
 
-Call `getResumeSessionInstructions` (or read tracking + CONTEXT_PROMPT) and continue from the current phase.
+Call `getResumeSessionInstructions` (or read `appledger/profiles/forgetrail.yaml`, the latest session, and CONTEXT_PROMPT) and continue from the current phase.
 
 ## Key Tools to Use Proactively
 
@@ -88,10 +88,10 @@ Call `getResumeSessionInstructions` (or read tracking + CONTEXT_PROMPT) and cont
 - `getTemplate({name: "..."})` — for PHASE_1_BRIEF, CONTEXT_PROMPT, audits, etc. Use mode "shell" for clean structure.
 - `runAudit`, `searchLessons`, `getAntiPatterns`
 - `suggestSubagentDecomposition` (when subagents available)
-- `validateTracking` (to keep the state file healthy)
-- `ingestPlanArtifact` (after native plan mode approval — map plan → PHASE_1_BRIEF + decisions[])
+- `validateTracking` (classify a legacy `workflow_tracking.json`; 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.
 
-Always keep the user in the loop on phase progress and major decisions. The tracking file + CONTEXT_PROMPT are the source of truth across sessions, not chat history.
+Always keep the user in the loop on phase progress and major decisions. `appledger/` plus CONTEXT_PROMPT are the source of truth across sessions, not chat history.
 
 This skill makes you a much more reliable long-term build partner. Use it.

package/content/skills/forgetrail/SKILL_FACTS.md

@@ -6,7 +6,7 @@ version: "0.3.0"
 status: active
 license: Apache-2.0
 kind: cursor-skill
-purpose: "Enforce the ForgeTrail 7-phase lifecycle and maintain .forgetrail/workflow_tracking.json as the system of record"
+purpose: "Enforce the ForgeTrail 7-phase lifecycle and maintain appledger/ as the system of record"
 homepage: https://forgetrail.dev
 repository: https://github.com/Catalyst-Forge-LLC/forgetrail
 provenance:
@@ -54,7 +54,7 @@ credits:
 
 ## Purpose
 
-Enforce the ForgeTrail 7-phase lifecycle and maintain .forgetrail/workflow_tracking.json as the system of record
+Enforce the ForgeTrail 7-phase lifecycle and maintain appledger/ as the system of record
 
 ## Provenance
 

package/docs/CONTEXT_PROMPT.md

@@ -24,7 +24,7 @@ _If the project used ForgeTrail Phase 1 properly, **`docs/PHASE_1_BRIEF.md`** ex
 | §10 Out of scope v1 | **Key Architectural Decisions** or short note under **Recent Changes** |
 | §11 First feature batch | Seed **`TODO.md`** |
 
-**After merge:** Keep **`PHASE_1_BRIEF.md`** in `docs/` as a dated audit trail **or** replace its body with one line: `Merged into CONTEXT_PROMPT.md on [date]. Source preserved in git history.` Do **not** delete corresponding entries in **`.forgetrail/workflow_tracking.json` → `decisions[]`.**
+**After merge:** Keep **`PHASE_1_BRIEF.md`** in `docs/` as a dated audit trail **or** replace its body with one line: `Merged into CONTEXT_PROMPT.md on [date]. Source preserved in git history.` Do **not** delete the corresponding decision records in **`appledger/`**.
 
 ---
 

package/docs/NPM.md

@@ -8,14 +8,14 @@ You run `pnpm publish`. The gate does not log in or publish.
 
 Two public unscoped packages:
 
-| Package | Version | From | What it is |
-| --- | --- | --- | --- |
-| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.3.0 | repo root | CLI + Lite + templates. `npx forgetrail install --lite` |
-| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.2.2 | `mcp-server/` | MCP bin. `npx -y forgetrail-mcp` |
+| Package | This tree | On npm until you publish | From | What it is |
+| --- | --- | --- | --- | --- |
+| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.5.0 | 0.4.20 | repo root | CLI + Lite + templates. `pnpm dlx forgetrail install --lite` |
+| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.4.0 | 0.3.10 | `mcp-server/` | MCP bin. `pnpm dlx forgetrail-mcp` |
 
 These are **installer and MCP channels**, not a library. App repos should not add `forgetrail` to `dependencies`.
 
-`pnpm run pack:check` already passed on this tree (2026-08-20). Root dry-run packed `forgetrail@0.3.0` (98 files, no `site/` or `specs/`).
+`0.5.0` stops installing `workflow_tracking.json`. `0.4.0` tells kickoff to run `appledger init`. The registry copies above do not include that cutover. `pnpm run pack:check` is the gate. It does not publish.
 
 ---
 
@@ -59,11 +59,11 @@ The `Debugger listening` line on MCP `prepack` is Cursor attaching to a one-line
 
 ```bash
 # Prefer pnpm dlx. npm 12 `npx forgetrail --help` on Windows failed to spawn the bin.
-pnpm dlx forgetrail@0.3.0 --help
-pnpm dlx forgetrail@0.3.0 install --lite --dry-run
+pnpm dlx forgetrail@0.5.0 --help
+pnpm dlx forgetrail@0.5.0 install --lite --dry-run
 
 # MCP starts; needs content via FORGETRAIL_ROOT or a sibling forgetrail install
-pnpm dlx forgetrail-mcp@0.2.2
+pnpm dlx forgetrail-mcp@0.4.0
 ```
 
 Optional Cursor MCP (content from a `forgetrail` install, or set the path):

package/docs/PHASE_1_BRIEF.md

@@ -1,10 +1,10 @@
 # [App Name] — Phase 1 architecture brief
 
-_Structured capture of planning and architecture **before** code scaffolding. Goal: Phase 2 (or a new agent/session) can start from this file + `.forgetrail/workflow_tracking.json` without re-reading the whole Phase 1 chat._
+_Structured capture of planning and architecture **before** code scaffolding. Goal: Phase 2 (or a new agent/session) can start from this file plus `appledger/` without re-reading the whole Phase 1 chat._
 
 **Status:** `[draft | locked]`  
 **Last updated:** `[ISO date]`  
-**Phase 1 exit:** Do not mark Phase 1 complete in `.forgetrail/workflow_tracking.json` until this brief is **locked** and major commitments are in `decisions[]`.
+**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`.
 
 ---
 
@@ -13,7 +13,7 @@ _Structured capture of planning and architecture **before** code scaffolding. Go
 **What we are building (2–4 sentences):**
 
 
-**Project archetype:** `[product | internal-tool | one-shot]` _(WORKFLOW.md §1d — non-`product` archetypes prune later-phase exit criteria in the tracking file; log the pruning in `decisions[]`)_
+**Project archetype:** `[product | internal-tool | one-shot]` _(WORKFLOW.md §1d — non-`product` archetypes prune later-phase criteria in `appledger/profiles/forgetrail.yaml`; record the pruning as a decision.)_
 
 **What “done” looks like for v1 (measurable where possible):**
 
@@ -115,7 +115,7 @@ _What could blow schedule or architecture — honest list._
 
 ## 8. Architectural decisions (numbered)
 
-_Each decision should include **WHY** and what was rejected. **Also** add each major commitment to `.forgetrail/workflow_tracking.json` → `decisions[]` (id, timestamp, phase, decision, rationale, alternatives_considered)._
+_Each decision should include **WHY** and what was rejected. **Also** add each major commitment as a decision record in `appledger/` (choice, rationale, alternatives)._
 
 **D1.**
 
@@ -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
-- [ ] `.forgetrail/workflow_tracking.json` updated: `decisions[]` for each major D#; `phases["1-architecture"]` notes summarize sign-off
-- [ ] Phase 2 opener will read **this file** + `.forgetrail/workflow_tracking.json` first
+- [ ] `appledger/` updated: a decision record for each major D#, and the session records the sign-off. Do not write `workflow_tracking.json`.
+- [ ] Phase 2 opener will read **this file**, `appledger/profiles/forgetrail.yaml`, and the latest session record first
 
-> 💡 **Lesson learned:** Treat the brief and `decisions[]` as a pair: JSON is great for machine-structured history; the brief is great for the next human or agent to read 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.
+> 💡 **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.