@specforge/canary-cli 0.1.9 → 0.1.11

package/dist/tools/core/git-injection.d.ts

@@ -0,0 +1,50 @@
+/** Runs a `git` sub-command; returns trimmed stdout, or `null` on any failure. */
+export type GitRunner = (args: string[]) => string | null;
+/** Default runner: spawn `git`, return trimmed stdout, `null` on any failure. */
+export declare const defaultGitRunner: GitRunner;
+export interface WorktreeGitEvidence {
+    /**
+     * `true` when the worktree has no uncommitted changes — OR when the caller is
+     * not inside a git repo (a non-git caller is never "dirty", so SWS still runs).
+     */
+    gitClean: boolean;
+    /** Worktree root (`git rev-parse --show-toplevel`); `null` when not in a worktree. */
+    worktreePath: string | null;
+    /** Current branch (`git rev-parse --abbrev-ref HEAD`); `null` when not in a worktree. */
+    branch: string | null;
+}
+/**
+ * SWS git evidence — the clean-status precondition input + the worktree
+ * provenance (M23.2). Emits `null` provenance (and `gitClean: true`) when the
+ * agent is not inside a git worktree, so SWS still records the WorkSession.
+ */
+export declare function readWorktreeGitEvidence(run?: GitRunner): WorktreeGitEvidence;
+/** One injected file-change action (a subset of the AWS `record_file_change` payload). */
+export interface LocalFileChangeAction {
+    action: 'record_file_change';
+    workSessionId: string;
+    ticketId: string;
+    expectedPath: string;
+    expectedAction: 'create' | 'modify' | 'delete';
+    actualAction: 'created' | 'modified' | 'deleted';
+    status: 'matched';
+}
+interface DeriveCtx {
+    workSessionId: string;
+    ticketId: string;
+}
+/**
+ * Parse `git status --porcelain` into the `record_file_change` set the MCP-local
+ * injects in `validateFiles: 'local'` mode — one action per created/modified/
+ * deleted path (the agent reports the `referenced` files itself). A rename (`R`)
+ * surfaces as a create of the new path.
+ */
+export declare function deriveLocalFileChanges(statusPorcelain: string | null, ctx: DeriveCtx): LocalFileChangeAction[];
+/**
+ * Read the worktree's changed-file set (`git status --porcelain`) and map it to
+ * the `record_file_change` actions the MCP-local injects (AWS `validateFiles:
+ * 'local'`). Empty when not inside a git worktree.
+ */
+export declare function readLocalFileChanges(ctx: DeriveCtx, run?: GitRunner): LocalFileChangeAction[];
+export {};
+//# sourceMappingURL=git-injection.d.ts.map

package/dist/tools/core/git-injection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-injection.d.ts","sourceRoot":"","sources":["../../../src/tools/core/git-injection.ts"],"names":[],"mappings":"AA2BA,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,GAAG,IAAI,CAAC;AAE1D,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,EAAE,SAU9B,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yFAAyF;IACzF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,SAA4B,GAAG,mBAAmB,CAc9F;AAED,0FAA0F;AAC1F,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC/C,YAAY,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IACjD,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,UAAU,SAAS;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,GAAG,EAAE,SAAS,GACb,qBAAqB,EAAE,CA4BzB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,GAAE,SAA4B,GAAG,qBAAqB,EAAE,CAE/G"}

package/dist/tools/core/git-injection.js

@@ -0,0 +1,74 @@
+import { execFileSync } from "node:child_process";
+const defaultGitRunner = (args) => {
+  try {
+    const out = execFileSync("git", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.trim();
+  } catch {
+    return null;
+  }
+};
+function readWorktreeGitEvidence(run = defaultGitRunner) {
+  const worktreePath = run(["rev-parse", "--show-toplevel"]);
+  if (worktreePath === null || worktreePath === "") {
+    return { gitClean: true, worktreePath: null, branch: null };
+  }
+  const branch = run(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const status = run(["status", "--porcelain"]);
+  return {
+    // A failed `git status` (null) must not block SWS → treat as clean.
+    gitClean: status === null ? true : status.trim() === "",
+    worktreePath,
+    branch: branch === null || branch === "" ? null : branch
+  };
+}
+function deriveLocalFileChanges(statusPorcelain, ctx) {
+  if (!statusPorcelain) return [];
+  const actions = [];
+  for (const raw of statusPorcelain.split("\n")) {
+    const line = raw.replace(/\r$/, "");
+    if (line.trim() === "") continue;
+    const xy = line.slice(0, 2);
+    let path = line.slice(3).trim();
+    const arrow = path.indexOf(" -> ");
+    if (arrow >= 0) path = path.slice(arrow + 4).trim();
+    if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
+    if (path === "") continue;
+    const kind = classifyPorcelain(xy);
+    if (!kind) continue;
+    actions.push({
+      action: "record_file_change",
+      workSessionId: ctx.workSessionId,
+      ticketId: ctx.ticketId,
+      expectedPath: path,
+      expectedAction: kind.expected,
+      actualAction: kind.actual,
+      status: "matched"
+    });
+  }
+  return actions;
+}
+function readLocalFileChanges(ctx, run = defaultGitRunner) {
+  return deriveLocalFileChanges(run(["status", "--porcelain"]), ctx);
+}
+function classifyPorcelain(xy) {
+  const s = xy.trim();
+  if (s === "") return null;
+  if (s === "??" || s.includes("A") || s.includes("R") || s.includes("C")) {
+    return { expected: "create", actual: "created" };
+  }
+  if (s.includes("D")) return { expected: "delete", actual: "deleted" };
+  if (s.includes("M") || s.includes("T") || s.includes("U")) {
+    return { expected: "modify", actual: "modified" };
+  }
+  return null;
+}
+export {
+  defaultGitRunner,
+  deriveLocalFileChanges,
+  readLocalFileChanges,
+  readWorktreeGitEvidence
+};
+//# sourceMappingURL=git-injection.js.map

package/dist/tools/core/git-injection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/tools/core/git-injection.ts"],"sourcesContent":["/**\n * MCP-local git-evidence injection (M23.2).\n *\n * The work lifecycle's SWS/AWS verbs need worktree git evidence that only the\n * MCP-LOCAL (this CLI, running on the agent's machine — the deployed Lambda has\n * NO worktree) can observe. Per `docs/architecture/work-lifecycle-flow.md` §0 +\n * [[project_coherence_score]]:\n *\n *  - **SWS** (`start_work_session`): runs `git status` for the clean-workspace\n *    precondition (`gitClean`) and reports the worktree provenance —\n *    `worktreePath` via `git rev-parse --show-toplevel` + `branch` via\n *    `git rev-parse --abbrev-ref HEAD` — so SWS persists\n *    `WorkSession.worktreePath`/`branch` (M16.2). When the agent is NOT inside a\n *    git worktree (\"caso esteja em uma\") the provenance is `null` (SWS still\n *    records the WorkSession) and `gitClean` defaults to `true` (a non-git caller\n *    is never \"dirty\" — it must not be blocked by the precondition).\n *  - **AWS** (`action_work_session`, `validateFiles: 'local'`): runs\n *    `git status --porcelain` and injects one `record_file_change` action per\n *    created/modified/deleted file (the agent only reports the `referenced`\n *    files git cannot see).\n *\n * The git commands run through an injectable `GitRunner` (defaults to a real,\n * non-throwing `git` spawn) so the layer is unit-testable without a live repo and\n * never throws inside a tool handler.\n */\nimport { execFileSync } from 'node:child_process';\n\n/** Runs a `git` sub-command; returns trimmed stdout, or `null` on any failure. */\nexport type GitRunner = (args: string[]) => string | null;\n\n/** Default runner: spawn `git`, return trimmed stdout, `null` on any failure. */\nexport const defaultGitRunner: GitRunner = (args) => {\n  try {\n    const out = execFileSync('git', args, {\n      encoding: 'utf8',\n      stdio: ['ignore', 'pipe', 'ignore'],\n    });\n    return out.trim();\n  } catch {\n    return null;\n  }\n};\n\nexport interface WorktreeGitEvidence {\n  /**\n   * `true` when the worktree has no uncommitted changes — OR when the caller is\n   * not inside a git repo (a non-git caller is never \"dirty\", so SWS still runs).\n   */\n  gitClean: boolean;\n  /** Worktree root (`git rev-parse --show-toplevel`); `null` when not in a worktree. */\n  worktreePath: string | null;\n  /** Current branch (`git rev-parse --abbrev-ref HEAD`); `null` when not in a worktree. */\n  branch: string | null;\n}\n\n/**\n * SWS git evidence — the clean-status precondition input + the worktree\n * provenance (M23.2). Emits `null` provenance (and `gitClean: true`) when the\n * agent is not inside a git worktree, so SWS still records the WorkSession.\n */\nexport function readWorktreeGitEvidence(run: GitRunner = defaultGitRunner): WorktreeGitEvidence {\n  const worktreePath = run(['rev-parse', '--show-toplevel']);\n  if (worktreePath === null || worktreePath === '') {\n    // Not inside a git worktree — SWS still records the WorkSession.\n    return { gitClean: true, worktreePath: null, branch: null };\n  }\n  const branch = run(['rev-parse', '--abbrev-ref', 'HEAD']);\n  const status = run(['status', '--porcelain']);\n  return {\n    // A failed `git status` (null) must not block SWS → treat as clean.\n    gitClean: status === null ? true : status.trim() === '',\n    worktreePath,\n    branch: branch === null || branch === '' ? null : branch,\n  };\n}\n\n/** One injected file-change action (a subset of the AWS `record_file_change` payload). */\nexport interface LocalFileChangeAction {\n  action: 'record_file_change';\n  workSessionId: string;\n  ticketId: string;\n  expectedPath: string;\n  expectedAction: 'create' | 'modify' | 'delete';\n  actualAction: 'created' | 'modified' | 'deleted';\n  status: 'matched';\n}\n\ninterface DeriveCtx {\n  workSessionId: string;\n  ticketId: string;\n}\n\n/**\n * Parse `git status --porcelain` into the `record_file_change` set the MCP-local\n * injects in `validateFiles: 'local'` mode — one action per created/modified/\n * deleted path (the agent reports the `referenced` files itself). A rename (`R`)\n * surfaces as a create of the new path.\n */\nexport function deriveLocalFileChanges(\n  statusPorcelain: string | null,\n  ctx: DeriveCtx,\n): LocalFileChangeAction[] {\n  if (!statusPorcelain) return [];\n  const actions: LocalFileChangeAction[] = [];\n  for (const raw of statusPorcelain.split('\\n')) {\n    const line = raw.replace(/\\r$/, '');\n    if (line.trim() === '') continue;\n    // porcelain v1: `XY<space>path` — XY is the 2-char status, path starts at col 3.\n    const xy = line.slice(0, 2);\n    let path = line.slice(3).trim();\n    // Rename/copy renders as `old -> new`; record the new path.\n    const arrow = path.indexOf(' -> ');\n    if (arrow >= 0) path = path.slice(arrow + 4).trim();\n    // git quotes paths with special chars.\n    if (path.startsWith('\"') && path.endsWith('\"')) path = path.slice(1, -1);\n    if (path === '') continue;\n    const kind = classifyPorcelain(xy);\n    if (!kind) continue;\n    actions.push({\n      action: 'record_file_change',\n      workSessionId: ctx.workSessionId,\n      ticketId: ctx.ticketId,\n      expectedPath: path,\n      expectedAction: kind.expected,\n      actualAction: kind.actual,\n      status: 'matched',\n    });\n  }\n  return actions;\n}\n\n/**\n * Read the worktree's changed-file set (`git status --porcelain`) and map it to\n * the `record_file_change` actions the MCP-local injects (AWS `validateFiles:\n * 'local'`). Empty when not inside a git worktree.\n */\nexport function readLocalFileChanges(ctx: DeriveCtx, run: GitRunner = defaultGitRunner): LocalFileChangeAction[] {\n  return deriveLocalFileChanges(run(['status', '--porcelain']), ctx);\n}\n\nfunction classifyPorcelain(\n  xy: string,\n): { expected: 'create' | 'modify' | 'delete'; actual: 'created' | 'modified' | 'deleted' } | null {\n  const s = xy.trim();\n  if (s === '') return null;\n  // Untracked / added / renamed / copied → a new (created) file.\n  if (s === '??' || s.includes('A') || s.includes('R') || s.includes('C')) {\n    return { expected: 'create', actual: 'created' };\n  }\n  if (s.includes('D')) return { expected: 'delete', actual: 'deleted' };\n  if (s.includes('M') || s.includes('T') || s.includes('U')) {\n    return { expected: 'modify', actual: 'modified' };\n  }\n  return null;\n}\n"],"mappings":"AAyBA,SAAS,oBAAoB;AAMtB,MAAM,mBAA8B,CAAC,SAAS;AACnD,MAAI;AACF,UAAM,MAAM,aAAa,OAAO,MAAM;AAAA,MACpC,UAAU;AAAA,MACV,OAAO,CAAC,UAAU,QAAQ,QAAQ;AAAA,IACpC,CAAC;AACD,WAAO,IAAI,KAAK;AAAA,EAClB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAmBO,SAAS,wBAAwB,MAAiB,kBAAuC;AAC9F,QAAM,eAAe,IAAI,CAAC,aAAa,iBAAiB,CAAC;AACzD,MAAI,iBAAiB,QAAQ,iBAAiB,IAAI;AAEhD,WAAO,EAAE,UAAU,MAAM,cAAc,MAAM,QAAQ,KAAK;AAAA,EAC5D;AACA,QAAM,SAAS,IAAI,CAAC,aAAa,gBAAgB,MAAM,CAAC;AACxD,QAAM,SAAS,IAAI,CAAC,UAAU,aAAa,CAAC;AAC5C,SAAO;AAAA;AAAA,IAEL,UAAU,WAAW,OAAO,OAAO,OAAO,KAAK,MAAM;AAAA,IACrD;AAAA,IACA,QAAQ,WAAW,QAAQ,WAAW,KAAK,OAAO;AAAA,EACpD;AACF;AAwBO,SAAS,uBACd,iBACA,KACyB;AACzB,MAAI,CAAC,gBAAiB,QAAO,CAAC;AAC9B,QAAM,UAAmC,CAAC;AAC1C,aAAW,OAAO,gBAAgB,MAAM,IAAI,GAAG;AAC7C,UAAM,OAAO,IAAI,QAAQ,OAAO,EAAE;AAClC,QAAI,KAAK,KAAK,MAAM,GAAI;AAExB,UAAM,KAAK,KAAK,MAAM,GAAG,CAAC;AAC1B,QAAI,OAAO,KAAK,MAAM,CAAC,EAAE,KAAK;AAE9B,UAAM,QAAQ,KAAK,QAAQ,MAAM;AACjC,QAAI,SAAS,EAAG,QAAO,KAAK,MAAM,QAAQ,CAAC,EAAE,KAAK;AAElD,QAAI,KAAK,WAAW,GAAG,KAAK,KAAK,SAAS,GAAG,EAAG,QAAO,KAAK,MAAM,GAAG,EAAE;AACvE,QAAI,SAAS,GAAI;AACjB,UAAM,OAAO,kBAAkB,EAAE;AACjC,QAAI,CAAC,KAAM;AACX,YAAQ,KAAK;AAAA,MACX,QAAQ;AAAA,MACR,eAAe,IAAI;AAAA,MACnB,UAAU,IAAI;AAAA,MACd,cAAc;AAAA,MACd,gBAAgB,KAAK;AAAA,MACrB,cAAc,KAAK;AAAA,MACnB,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AACA,SAAO;AACT;AAOO,SAAS,qBAAqB,KAAgB,MAAiB,kBAA2C;AAC/G,SAAO,uBAAuB,IAAI,CAAC,UAAU,aAAa,CAAC,GAAG,GAAG;AACnE;AAEA,SAAS,kBACP,IACiG;AACjG,QAAM,IAAI,GAAG,KAAK;AAClB,MAAI,MAAM,GAAI,QAAO;AAErB,MAAI,MAAM,QAAQ,EAAE,SAAS,GAAG,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,SAAS,GAAG,GAAG;AACvE,WAAO,EAAE,UAAU,UAAU,QAAQ,UAAU;AAAA,EACjD;AACA,MAAI,EAAE,SAAS,GAAG,EAAG,QAAO,EAAE,UAAU,UAAU,QAAQ,UAAU;AACpE,MAAI,EAAE,SAAS,GAAG,KAAK,EAAE,SAAS,GAAG,KAAK,EAAE,SAAS,GAAG,GAAG;AACzD,WAAO,EAAE,UAAU,UAAU,QAAQ,WAAW;AAAA,EAClD;AACA,SAAO;AACT;","names":[]}

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAML,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAShC;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,IAAI,EAAE,CAslCjC;AAED;;GAEG;AACH,KAAK,WAAW,GAAG,CACjB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AA6EtB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GACnB,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAkU7B;AAiBD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,CAAC,CA4DlB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,GAAG,gBAAgB,CAAC,CAOrC;AAGD,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAML,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAUhC;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,IAAI,EAAE,CA6nCjC;AAED;;GAEG;AACH,KAAK,WAAW,GAAG,CACjB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AA6EtB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GACnB,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAmU7B;AAiBD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,CAAC,CA4DlB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,GAAG,gBAAgB,CAAC,CAOrC;AAGD,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/tools/index.js

@@ -7,6 +7,7 @@ import {
 } from "../validation/index.js";
 import { injectContext, injectContextRequired } from "./core/context-helper.js";
 import { probeExistingFiles } from "./core/file-existence-injection.js";
+import { readWorktreeGitEvidence } from "./core/git-injection.js";
 import { tryLoadProjectConfig, saveProjectConfig } from "../cli/config/index.js";
 import {
   appendPlanningSessionRegistry,
@@ -105,7 +106,7 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
             type: "array",
             items: {
               type: "string",
-              enum: ["pending", "ready", "active", "done"]
+              enum: ["pending", "ready", "active", "done", "blocked"]
             },
             description: "Filter by status"
           },
@@ -136,6 +137,37 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
           offset: {
             type: "number",
             description: "Pagination offset (default: 0)"
+          },
+          fields: {
+            type: "array",
+            items: {
+              type: "string",
+              enum: [
+                "id",
+                "epicId",
+                "ticketNumber",
+                "title",
+                "description",
+                "status",
+                "priority",
+                "complexity",
+                "estimatedHours",
+                "actualHours",
+                "acceptanceCriteria",
+                "implementation",
+                "technicalDetails",
+                "notes",
+                "tags",
+                "progress",
+                "testsPassed",
+                "order",
+                "startedAt",
+                "completedAt",
+                "createdAt",
+                "updatedAt"
+              ]
+            },
+            description: "Select specific fields to return. Returns all fields if not specified. id is always included."
           }
         }
       }
@@ -273,6 +305,8 @@ Format options:
                   "unlink_blueprint_to_tickets",
                   "create_dependencies",
                   "delete_dependencies",
+                  "justify",
+                  "unjustify",
                   "get_planning_status"
                 ],
                 description: "The planning operation to perform (lifecycle vocabulary). The type IS the backend PlanningOperationName; remaining fields are the operation payload."
@@ -283,7 +317,7 @@ Format options:
               {
                 properties: {
                   type: { const: "update_spec" },
-                  fields: { type: "object", description: "Partial spec update \u2014 only the keys you send are changed (e.g. background, goals, nonGoals, constraints, successCriteria)." }
+                  fields: { type: "object", description: "Partial spec update \u2014 only the keys you send are changed (e.g. background, goals, nonGoals, constraints, successCriteria). Fields that do not apply are declared with the `justify` op (undo with `unjustify`), never by writing values here." }
                 },
                 required: ["type", "fields"]
               },
@@ -305,7 +339,7 @@ Format options:
                   id: { type: "string", description: "Epic id (use list_epics / lookup_epic to find)." },
                   fields: {
                     type: "object",
-                    description: "Partial epic update \u2014 only the keys you send are changed.",
+                    description: "Partial epic update \u2014 only the keys you send are changed. Fields that do not apply are declared with the `justify` op (undo with `unjustify`), never by writing values here.",
                     properties: {
                       title: { type: "string" },
                       description: { type: "string" },
@@ -346,7 +380,7 @@ Format options:
                   id: { type: "string", description: "Ticket id (use list_tickets / lookup_ticket to find)." },
                   fields: {
                     type: "object",
-                    description: "Partial ticket update \u2014 only the keys you send are changed. Child-backed arrays (acceptanceCriteria, implementationSteps, filesToBe*, testSpecification.testTypes, codeSnippets, typeSnippets) replace the whole set. Blueprint links are NOT settable here \u2014 use link_blueprint_to_tickets (from ticket_decomposition onward), the sole writer of the blueprint\u2194ticket relation.",
+                    description: "Partial ticket update \u2014 only the keys you send are changed. Child-backed arrays (acceptanceCriteria, implementationSteps, filesToBe*, testSpecification.testTypes, codeSnippets, typeSnippets) replace the whole set. Blueprint links are NOT settable here \u2014 use link_blueprint_to_tickets (from ticket_decomposition onward), the sole writer of the blueprint\u2194ticket relation. Fields that do not apply are declared with the `justify` op (undo with `unjustify`), never by writing values here.",
                     properties: {
                       title: { type: "string" },
                       description: { type: "string" },
@@ -466,6 +500,30 @@ Format options:
                 },
                 required: ["type", "blueprintId", "ticketIds"]
               },
+              // justify — declare a field N/A (the paired declare op; unjustify removes it).
+              // Structural-neutral: it writes only the fieldDeclarations[scope] declaration,
+              // so it is native in EVERY planning phase and never rolls back. `scope` is the
+              // canonical field name the checks read (e.g. dependencies, codeReferences,
+              // apiContracts) — NOT a `fieldDeclarations`-shaped payload on update_*.
+              {
+                properties: {
+                  type: { const: "justify" },
+                  scope: { type: "string", description: "Canonical field name to mark not-applicable (e.g. 'dependencies', 'codeReferences', 'apiContracts')." },
+                  entityId: { type: "string", description: "The spec/epic/ticket id the field belongs to (resolved server-side; ids are unique across the spec)." },
+                  reason: { type: "string", description: "Why the field does not apply (must be at least 20 characters)." }
+                },
+                required: ["type", "scope", "entityId", "reason"]
+              },
+              // unjustify — remove a previously declared N/A (clears fieldDeclarations[scope]).
+              // A no-op if the scope was never justified. No reason (a delete is unconditional).
+              {
+                properties: {
+                  type: { const: "unjustify" },
+                  scope: { type: "string", description: "Canonical field name whose not-applicable declaration to remove." },
+                  entityId: { type: "string", description: "The spec/epic/ticket id the field belongs to." }
+                },
+                required: ["type", "scope", "entityId"]
+              },
               {
                 // Read-only poll/resume. To read a single ticket, use the `get` tool (type:'ticket').
                 properties: {
@@ -509,8 +567,8 @@ Format options:
       description: `Update checklist state during an active WorkSession. Combines step completion, AC validation, test result reporting, file tracking, reference review confirmation, and discovery reporting into a single atomic operation. All state changes are recorded on the WorkSession and its related validation/completion records.
 
 Use this instead of calling update_ticket for checklist changes. Provides:
-- Step completion (individual or bulk via WorkSessionStepCompletion)
-- Acceptance criteria validation (individual or bulk via WorkSessionACValidation)
+- Step completion (individual or bulk via WorkSessionImplStepCompletion)
+- Acceptance criteria validation (individual or bulk via WorkSessionAcceptanceCheck)
 - Test result reporting (merged by test type via WorkSessionTestResult)
 - File tracking (created, modified, deleted on WorkSession)
 - Discovery reporting (create discoveries for blockers, bugs, tech debt)
@@ -531,6 +589,33 @@ Set getTicket: true to fetch full ticket details in the response \u2014 useful f
             type: "string",
             description: "The ID of the ticket being worked on (must be in active status)"
           },
+          action: {
+            type: "object",
+            description: "The assay action to record \u2014 the AWS action vocabulary. `action` (the discriminator) is one of: mark_implementation_step_completion, mark_acceptance_check, record_test_result, add_skip_justification, amend_skip_justification, add_failure_justification, amend_failure_justification, record_file_change, add_file_change_justification, amend_file_change_justification, create_discovery (with `blocking`), update_discovery, set_discovery_resolved. Include `workSessionId` and the per-action fields. Forwarded verbatim as the lifecycle inner payload.",
+            properties: {
+              action: {
+                type: "string",
+                enum: [
+                  "mark_implementation_step_completion",
+                  "mark_acceptance_check",
+                  "record_test_result",
+                  "add_skip_justification",
+                  "amend_skip_justification",
+                  "add_failure_justification",
+                  "amend_failure_justification",
+                  "record_file_change",
+                  "add_file_change_justification",
+                  "amend_file_change_justification",
+                  "create_discovery",
+                  "update_discovery",
+                  "set_discovery_resolved"
+                ],
+                description: "The AWS action discriminator."
+              },
+              workSessionId: { type: "string", description: "The active WorkSession id (from start_work_session)." }
+            },
+            required: ["action"]
+          },
           steps: {
             type: "array",
             description: "Individual step completion updates",
@@ -974,53 +1059,6 @@ Set getTicket: true to fetch full ticket details in the response \u2014 useful f
         required: ["operation"]
       }
     },
-    {
-      name: "reset_work_session",
-      description: "Reset tickets to pending/ready status (calculated from dependencies). Returns statusCalculation showing how many became pending vs ready.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          specificationId: {
-            type: "string",
-            description: "The specification containing the tickets"
-          },
-          ticketIds: {
-            type: "array",
-            items: { type: "string" },
-            description: "Specific ticket IDs to reset"
-          },
-          fromTicketId: {
-            type: "string",
-            description: "Reset this ticket and all its dependents"
-          },
-          epicId: {
-            type: "string",
-            description: "Reset all tickets in this epic"
-          },
-          allTickets: {
-            type: "boolean",
-            description: "Reset all tickets in the specification"
-          },
-          resetDependents: {
-            type: "boolean",
-            description: "Also reset tickets that depend on the specified tickets (default: false)"
-          },
-          includeCompleted: {
-            type: "boolean",
-            description: "Include tickets with done status in the reset (default: false)"
-          },
-          preserveNotes: {
-            type: "boolean",
-            description: "Keep existing notes on tickets (default: true)"
-          },
-          clearTestResults: {
-            type: "boolean",
-            description: "Clear test result history (default: false)"
-          }
-        },
-        required: ["specificationId"]
-      }
-    },
     {
       name: "link_pull_request",
       description: "Associate a pull request with a ticket",
@@ -1300,29 +1338,19 @@ function createToolHandlers(apiClient) {
     },
     start_work_session: async (_client, args) => {
       validateRequired(args, "ticketId");
+      const git = readWorktreeGitEvidence();
       return await callLocal("start_work_session", {
-        ticketId: args.ticketId
+        ticketId: args.ticketId,
+        gitClean: git.gitClean,
+        worktreePath: git.worktreePath,
+        branch: git.branch
       });
     },
     action_work_session: async (_client, args) => {
       validateRequired(args, "ticketId");
       return await callLocal("action_work_session", {
         ticketId: args.ticketId,
-        steps: args.steps,
-        allStepsDone: args.allStepsDone,
-        acceptanceCriteria: args.acceptanceCriteria,
-        allACValidated: args.allACValidated,
-        testResults: args.testResults,
-        notes: args.notes,
-        filesCreated: args.filesCreated,
-        filesModified: args.filesModified,
-        filesDeleted: args.filesDeleted,
-        discovery: args.discovery,
-        blockReason: args.blockReason,
-        getTicket: args.getTicket,
-        includeFullContext: args.includeFullContext,
-        codeSnippetsReviewed: args.codeSnippetsReviewed,
-        typeReferencesReviewed: args.typeReferencesReviewed
+        payload: args.action ?? args.payload
       });
     },
     complete_work_session: async (_client, args) => {