forgetrail 0.4.20 → 0.5.0

package/package.json

@@ -1,70 +1,69 @@
-{
-  "name": "forgetrail",
-  "version": "0.4.20",
-  "private": false,
-  "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "bin": {
-    "forgetrail": "./scripts/forgetrail-cli.mjs"
-  },
-  "files": [
-    "scripts/",
-    "content/",
-    "docs/",
-    "prompts/",
-    "WORKFLOW.md",
-    "TRACKING_SCHEMA.md",
-    "workflow_tracking.json",
-    "INITIAL_PROMPT.md",
-    "CONTINUATION_PROMPT.md",
-    "TRY_FORGETRAIL.md",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "workspace:index": "node scripts/workspace-index.mjs",
-    "install:forgetrail": "node scripts/install-forgetrail.mjs",
-    "install:lite": "node scripts/install-forgetrail-lite.mjs",
-    "link:global": "node scripts/link-global.mjs",
-    "mcp": "node scripts/mcp-status.mjs dev",
-    "mcp:build": "node scripts/mcp-status.mjs build",
-    "mcp:status": "node scripts/mcp-status.mjs status",
-    "mcp:ping": "node scripts/mcp-status.mjs ping",
-    "mcp:cursor-config": "node scripts/mcp-status.mjs cursor-config",
-    "mcp:inspector": "node scripts/mcp-status.mjs inspector",
-    "ship": "pnpm --dir site run ship",
-    "site:dev": "pnpm --dir site dev",
-    "site:build": "pnpm --dir site run build",
-    "site:deploy": "pnpm --dir site run ship",
-    "pack:check": "node scripts/publish-gate.mjs",
-    "prepublishOnly": "node scripts/publish-gate.mjs"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "keywords": [
-    "forgetrail",
-    "mcp",
-    "ai-agents",
-    "cursor",
-    "claude",
-    "methodology",
-    "lite"
-  ],
-  "author": {
-    "name": "Catalyst Forge LLC",
-    "url": "https://catalystforge.com"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Catalyst-Forge-LLC/forgetrail.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Catalyst-Forge-LLC/forgetrail/issues"
-  },
-  "homepage": "https://forgetrail.dev",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "forgetrail",
+  "version": "0.5.0",
+  "private": false,
+  "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "forgetrail": "./scripts/forgetrail-cli.mjs"
+  },
+  "files": [
+    "scripts/",
+    "content/",
+    "docs/",
+    "prompts/",
+    "WORKFLOW.md",
+    "TRACKING_SCHEMA.md",
+    "workflow_tracking.json",
+    "INITIAL_PROMPT.md",
+    "CONTINUATION_PROMPT.md",
+    "TRY_FORGETRAIL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "forgetrail",
+    "mcp",
+    "ai-agents",
+    "cursor",
+    "claude",
+    "methodology",
+    "lite"
+  ],
+  "author": {
+    "name": "Catalyst Forge LLC",
+    "url": "https://catalystforge.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Catalyst-Forge-LLC/forgetrail.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Catalyst-Forge-LLC/forgetrail/issues"
+  },
+  "homepage": "https://forgetrail.dev",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "workspace:index": "node scripts/workspace-index.mjs",
+    "install:forgetrail": "node scripts/install-forgetrail.mjs",
+    "install:lite": "node scripts/install-forgetrail-lite.mjs",
+    "link:global": "node scripts/link-global.mjs",
+    "mcp": "node scripts/mcp-status.mjs dev",
+    "mcp:build": "node scripts/mcp-status.mjs build",
+    "mcp:status": "node scripts/mcp-status.mjs status",
+    "mcp:ping": "node scripts/mcp-status.mjs ping",
+    "mcp:cursor-config": "node scripts/mcp-status.mjs cursor-config",
+    "mcp:inspector": "node scripts/mcp-status.mjs inspector",
+    "ship": "pnpm --dir site run ship",
+    "site:dev": "pnpm --dir site dev",
+    "site:build": "pnpm --dir site run build",
+    "site:deploy": "pnpm --dir site run ship",
+    "pack:check": "node scripts/publish-gate.mjs"
+  }
+}

package/scripts/forgetrail-cli.mjs

@@ -36,7 +36,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    Skip workflow_tracking.json starter
+  --skip-tracking    Accepted and ignored. A tracking JSON file is not installed.
   --path, -p <dir>   Install elsewhere (default: current directory)
   --help, -h         Show help
 

package/scripts/install-lib.mjs

@@ -109,6 +109,7 @@ export function copyContentDir(fromDir, toDir, opts) {
   ensureDir(toDir, opts.dryRun);
   for (const name of readdirSync(fromDir)) {
     if (name === "skills") continue;
+    if (name === "LITE_WORKFLOW_TRACKING.json") continue;
     if (MCP_ONLY_CONTENT.has(name)) continue;
     copyPath(join(fromDir, name), join(toDir, name), opts);
   }

package/scripts/install.mjs

@@ -17,7 +17,6 @@ import {
 const ROOT_FILES = [
   "WORKFLOW.md",
   "TRACKING_SCHEMA.md",
-  "workflow_tracking.json",
   "INITIAL_PROMPT.md",
   "CONTINUATION_PROMPT.md",
   "LICENSE",
@@ -70,14 +69,6 @@ export function runInstallForgetrail(rawArgv, { defaultToCwd = false } = {}) {
   copyPath(join(FORGETRAIL_ROOT, "prompts"), join(forgetrailDir, "prompts"), opts);
   copyContentDir(contentSrc, contentDest, opts);
 
-  if (!args.skipTracking) {
-    copyPath(
-      join(FORGETRAIL_ROOT, "workflow_tracking.json"),
-      join(target, ".forgetrail", "workflow_tracking.json"),
-      { ...opts, force: args.force }
-    );
-  }
-
   const hooksSrc = join(FORGETRAIL_ROOT, "content", "hooks");
   const hooksDest = join(target, ".forgetrail", "hooks");
   ensureDir(hooksDest, args.dryRun);
@@ -95,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("  Tracking:     .forgetrail/workflow_tracking.json");
+  console.log("  Project record: appledger/ (not workflow_tracking.json)");
   console.log("  Hooks:        .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
   return { target, mode: "full" };
 }
@@ -127,14 +118,6 @@ export function runInstallLite(rawArgv, { defaultToCwd = false } = {}) {
     );
   }
 
-  if (!args.skipTracking) {
-    copyPath(
-      join(contentDir, "LITE_WORKFLOW_TRACKING.json"),
-      join(forgetrailDir, "workflow_tracking.json"),
-      opts
-    );
-  }
-
   const hooksSrc = join(contentDir, "hooks");
   const hooksDest = join(forgetrailDir, "hooks");
   ensureDir(hooksDest, args.dryRun);
@@ -158,7 +141,7 @@ export function runInstallLite(rawArgv, { defaultToCwd = false } = {}) {
 
   console.log("\nDone.");
   console.log("  Protocol:  .forgetrail/FORGETRAIL_LITE.md");
-  console.log("  Tracking:  .forgetrail/workflow_tracking.json (lite-1 schema)");
+  console.log("  Project record: appledger/ (a tracking JSON file is not installed)");
   console.log("  Hooks:     .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
   if (args.withGenesisStub) {
     console.log("  Genesis:   docs/GENESIS.md (stub — replace with your spec)");
@@ -177,12 +160,12 @@ Usage:
 Options:
   --path, -p <dir>   Target project root (default: current directory for \`forgetrail\` CLI)
   --force, -f        Overwrite existing files
-  --skip-tracking    Do not create .forgetrail/workflow_tracking.json
+  --skip-tracking    Accepted and ignored. A tracking JSON file is not installed.
   --dry-run          Print actions only
 
 Installs:
   <target>/_forgetrail/   WORKFLOW, templates, prompts, content/ (curated)
-  <target>/.forgetrail/   workflow_tracking.json starter (unless skipped)
+  <target>/.forgetrail/   hooks only. Project state belongs in appledger/.
 `.trim();
 
 export const INSTALL_LITE_HELP = `
@@ -195,11 +178,11 @@ Usage:
 Options:
   --path, -p <dir>        Target project root (default: current directory for \`forgetrail\` CLI)
   --force, -f             Overwrite existing files
-  --skip-tracking         Do not create workflow_tracking.json starter
+  --skip-tracking         Accepted and ignored. A tracking JSON file is not installed.
   --with-genesis-stub     Also create docs/GENESIS.md stub (for the Try path)
   --dry-run               Print actions only
 
-Installs into <target>/.forgetrail/ (FORGETRAIL_LITE.md, tracking starter, cursor rules).
+Installs into <target>/.forgetrail/ (FORGETRAIL_LITE.md, cursor rules, hooks). Project state belongs in appledger/.
 With --with-genesis-stub, also writes docs/GENESIS.md from content/GENESIS_STUB.md.
 See TRY_FORGETRAIL.md in the ForgeTrail repo for the no-MCP prove-it recipe.
 `.trim();

package/scripts/publish-gate.mjs

@@ -98,11 +98,13 @@ for (const needed of ["WORKFLOW.md", "README.md", "LICENSE", "content/FORGETRAIL
 console.log("\n✓ forgetrail pack check passed");
 console.log(`  forgetrail@${root.version}`);
 console.log(`  forgetrail-mcp@${mcp.version} (build ok at ${MCP_ENTRY})`);
-console.log("\nPublish (you run these):");
-console.log("  pnpm publish --access public");
-console.log("  pnpm --dir mcp-server publish --access public");
-console.log("\nDry-run first if you want:");
+console.log("\nPublish (you run these, from a clean tree, after pushing if the tarball should match GitHub):");
 console.log("  pnpm publish --dry-run --access public");
+console.log("  pnpm publish --access public");
+console.log("  cd mcp-server");
+console.log("  pnpm publish --access public");
+console.log("  cd ..");
+console.log("Do not use pnpm --dir mcp-server publish. npm 12 treats leftover --dir as an extra package spec.");
 
 const here = fileURLToPath(import.meta.url);
 if (resolve(process.argv[1] ?? "") === resolve(here)) {

package/scripts/tracking-cutover.test.mjs

@@ -0,0 +1,109 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validateTrackingData } from "../content/hooks/validate-tracking-core.mjs";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+test("a pointer is not a second decision log", () => {
+  const result = validateTrackingData({
+    record: "appledger/",
+    status: "pointer",
+    note: "Decisions live in appledger/.",
+  });
+  assert.equal(result.issues.length, 0);
+  assert.match(result.warnings.join("\n"), /pointer to appledger/);
+});
+
+test("a legacy tracking document is a conflict", () => {
+  const result = validateTrackingData({
+    project: { name: "Notes", description: "Find notes" },
+    currentPhase: "4-feature-iteration",
+    phases: { "4-feature-iteration": { status: "in_progress", exitCriteriaRemaining: ["Edge cases"] } },
+    decisions: [{ decision: "Use local files" }],
+    sessions: [],
+  });
+  assert.match(result.issues.join("\n"), /not the system of record/);
+  assert.match(result.issues.join("\n"), /appledger migrate preview/);
+});
+
+test("install does not create workflow_tracking.json", () => {
+  for (const args of [
+    ["install", "--lite", "--dry-run"],
+    ["install", "--dry-run"],
+  ]) {
+    const dir = mkdtempSync(join(tmpdir(), "ft-cutover-"));
+    const result = spawnSync(process.execPath, ["scripts/forgetrail-cli.mjs", ...args, "--path", dir], {
+      cwd: root,
+      encoding: "utf8",
+    });
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+    assert.doesNotMatch(result.stdout, /\\workflow_tracking\.json/);
+    assert.match(result.stdout, /Project record: appledger/);
+  }
+});
+
+test("session start warns on a legacy file and does not quote it as the live phase", () => {
+  const dir = mkdtempSync(join(tmpdir(), "ft-session-"));
+  mkdirSync(join(dir, ".forgetrail"), { recursive: true });
+  writeFileSync(
+    join(dir, ".forgetrail", "workflow_tracking.json"),
+    JSON.stringify({
+      project: { name: "Notes" },
+      currentPhase: "4-feature-iteration",
+      phases: {},
+      decisions: [{ decision: "Keep the old log" }],
+    })
+  );
+  const result = spawnSync(process.execPath, [join(root, "content", "hooks", "session-start.mjs")], {
+    cwd: dir,
+    encoding: "utf8",
+  });
+  assert.equal(result.status, 0, result.stderr);
+  const payload = JSON.parse(result.stdout);
+  assert.match(payload.additional_context, /not the system of record/);
+  assert.doesNotMatch(payload.additional_context, /Current Phase: 4-feature-iteration/);
+});
+
+test("Lite and workflow instructions name the ledger", () => {
+  const lite = readFileSync(join(root, "content", "FORGETRAIL_LITE.md"), "utf8");
+  const legacyAt = lite.indexOf("## 11. Legacy");
+  const resumeAt = lite.indexOf("## 12. `AGENTS.md`");
+  assert.ok(legacyAt > 0 && resumeAt > legacyAt);
+  const instructional = `${lite.slice(0, legacyAt)}\n${lite.slice(resumeAt)}`;
+  assert.match(lite.slice(legacyAt, resumeAt), /"schemaVersion": "lite-1"/);
+  assert.match(instructional, /ForgeTrail Lite v2\.2\.0/);
+  for (const line of instructional.split("\n")) {
+    if (!line.includes("workflow_tracking.json")) continue;
+    assert.match(line, /[Dd]o not|does not|not the live phase|not recreate/, line);
+  }
+  const workflow = readFileSync(join(root, "WORKFLOW.md"), "utf8");
+  assert.match(workflow, /not_applicable/);
+  assert.match(workflow, /data\.companion_outcomes/);
+  assert.doesNotMatch(workflow, /Where this file names that JSON/);
+  for (const line of workflow.split("\n")) {
+    if (!line.includes("workflow_tracking.json")) continue;
+    assert.match(line, /[Dd]o not|does not|not the system of record|not the live phase/, line);
+  }
+});
+
+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, /appledger init/);
+  assert.doesNotMatch(kickoff, /no separate init command/);
+  const plan = readFileSync(join(root, "content", "PLAN_MODE_PATTERNS.md"), "utf8");
+  assert.match(plan, /decision record/);
+  assert.doesNotMatch(plan, /decisions\[\]/);
+  assert.match(plan, /Do not create `\.forgetrail\/workflow_tracking\.json`/);
+  const genesis = readFileSync(join(root, "content", "GENESIS_STUB.md"), "utf8");
+  assert.match(genesis, /appledger init/);
+  assert.doesNotMatch(genesis, /Create `\.forgetrail\/workflow_tracking\.json`/);
+  const intake = readFileSync(join(root, "content", "GREENFIELD_INTAKE.md"), "utf8");
+  assert.doesNotMatch(intake, /tracking file/);
+  assert.doesNotMatch(intake, /decisions\[\]/);
+  assert.match(intake, /archetype/);
+});

package/scripts/workspace-index.mjs

@@ -40,8 +40,9 @@ function scanWorkspace(workspaceRoot) {
 
     const trackingPath = findTracking(fullPath);
     const hooksStatus = hasHooks(fullPath);
+    const ledger = existsSync(join(fullPath, "appledger", "manifest.yaml"));
 
-    if (!trackingPath && hooksStatus === "none") {
+    if (!trackingPath && !ledger && hooksStatus === "none") {
       continue;
     }
 
@@ -77,9 +78,16 @@ function scanWorkspace(workspaceRoot) {
             openCriteriaCount = pObj.exitCriteriaRemaining.length;
           }
         }
+        if (tracking.status === "pointer") {
+          phase = ledger ? "appledger" : "pointer";
+        } else if (tracking.currentPhase || tracking.phases) {
+          phase = ledger ? `legacy+${phase}` : `legacy:${phase}`;
+        }
       } catch {}
     }
 
+    if (ledger && phase === "-") phase = "appledger";
+
     rows.push({
       repo: entry,
       name: projectName,