@haposoft/cafekit 0.16.7 → 0.18.0

package/src/claude/hooks/rules.cjs

@@ -70,6 +70,7 @@ try {
   const baseDir   = cwd;
   const plansPath = path.join(baseDir, runtime.paths?.plans || 'plans');
   const docsPath  = path.join(baseDir, runtime.paths?.docs  || 'docs');
+  const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
   const maxLoc    = runtime.docs?.maxLoc || 800;
 
   const lines = [];
@@ -84,7 +85,7 @@ try {
 
   lines.push(
     '## Rules',
-    `- Markdown files: Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
+    `- Markdown files: Specs → "${specsPath}/" | Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
     '- **DO NOT** create markdown files outside of those directories unless explicitly asked.',
     `- docs.maxLoc: ${maxLoc} lines max per doc file`
   );

package/src/claude/hooks/session.cjs

@@ -202,7 +202,6 @@ try {
   const envFile = process.env.CLAUDE_ENV_FILE;
   const cwd     = projectRoot();
   const runtime = readRuntime(cwd);
-  try { require('./completion-authority-state.cjs').clearState(cwd, payload.session_id); } catch { /* old installs remain fail-open */ }
 
   // Check CafeKit update in parallel with project detection (async, fail-open).
   const updateCheckPromise = checkCafeKitUpdate(cwd);

package/src/claude/hooks/spec-gate.cjs

@@ -90,17 +90,17 @@ try {
   let POLICY;
   let RESOLVER;
   let RECEIPT;
-  let FINAL_STATE;
   try {
     POLICY = require(policyPath);
+    // One gate run checks every done receipt against the same checkout; capture it once.
+    require(path.join(__dirname, '..', 'scripts', 'provenance.cjs')).enableSnapshotMemo();
     RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
     RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
-    FINAL_STATE = require('./completion-authority-check.cjs');
     if (typeof POLICY.validateCanonicalReceipt !== 'function'
       || typeof POLICY.completionDecisionForSpec !== 'function'
       || typeof RECEIPT.checkTaskReceipt !== 'function'
       || typeof RECEIPT.checkWorkflowReceiptSet !== 'function'
-      || typeof FINAL_STATE.evaluateCloseout !== 'function') {
+      || typeof RESOLVER.resolveWorkflowCandidate !== 'function') {
       throw new Error('shared workflow policy lacks completion authority functions');
     }
   } catch (error) {
@@ -127,9 +127,7 @@ try {
     || (typeof RESOLVER.readActiveFeatureTarget === 'function'
       ? RESOLVER.readActiveFeatureTarget({ projectRoot: baseDir, runtime })
       : null);
-  let resolved = typeof RESOLVER.resolveWorkflowCandidate === 'function'
-    ? RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true })
-    : FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
+  let resolved = RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true });
   if (typeof RESOLVER.refineWorkflowGateResolution === 'function') {
     resolved = RESOLVER.refineWorkflowGateResolution(resolved);
   }
@@ -150,7 +148,7 @@ try {
     const lines = [`⚠️ Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
     for (const failure of checked.failures) {
       lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
-      const hint = typeof RECEIPT.receiptFixHint === 'function' ? RECEIPT.receiptFixHint(failure.failures) : null;
+      const hint = typeof RECEIPT.receiptFixHint === 'function' ? RECEIPT.receiptFixHint(failure.failures, failure.body) : null;
       lines.push(`  Fix in \`specs/${failure.featureName}/${failure.taskPath}\`: ${hint || 'write a runtime-bound `## Receipt` with the planned command'}.`);
     }
     emitBlock(lines.slice(0, 8).join('\n'));
@@ -186,19 +184,10 @@ try {
   const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
   const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
     || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
-  if (!processWorkflow && activeSpec.schema_version === '2.1') {
-    const finalState = FINAL_STATE.evaluateCloseout({
-      resolver: RESOLVER,
-      policy: POLICY,
-      projectRoot: baseDir,
-      runtime,
-      payload: { ...payload, session_id: sessionIdentity(payload) },
-    });
-    if (!finalState.ok) {
-      emitBlock(`Completion gate: ${finalState.reason}`);
-      process.exit(0);
-    }
-    if (finalState.active) process.exit(0);
+  // Legacy 2.1 closeout is retired; a 2.1 packet mid-execution keeps the ordinary receipt checks.
+  if (!processWorkflow && activeSpec.schema_version === '2.1' && explicitCloseout) {
+    emitBlock('Completion gate: Legacy spec.json closeout is no longer supported; move the packet to plan.md with flat task files');
+    process.exit(0);
   }
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
@@ -251,12 +240,12 @@ try {
   );
   const featureDir = path.join(specsPath, featureName);
   const failures = allDoneTasks
-    .map((taskPath) => ({
-      taskPath,
-      fails: processWorkflow
-        ? RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY).failures
-        : RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
-    }))
+    .map((taskPath) => {
+      const proof = processWorkflow
+        ? RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY)
+        : RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY);
+      return { taskPath, fails: proof.failures, body: proof.body };
+    })
     .filter((f) => f.fails.length > 0);
 
   const featureCloseoutRequired = !processWorkflow && explicitCloseout && allDoneTasks.length > 0;
@@ -298,12 +287,12 @@ try {
       ? `⚠️ Completion gate: ${failures.length} done task(s) lack a verification receipt.`
       : '⚠️ Completion gate: workflow completion proof is incomplete.',
   ];
-  for (const { taskPath, fails } of failures) {
+  for (const { taskPath, fails, body } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
     lines.push(taskPath === 'feature-receipt.md'
       ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
       : processWorkflow
-        ? `  Fix in \`specs/${featureName}/${path.posix.basename(taskPath)}\`: ${(typeof RECEIPT.receiptFixHint === 'function' && RECEIPT.receiptFixHint(fails)) || 'write a runtime-bound `## Receipt` with command output'}.`
+        ? `  Fix in \`specs/${featureName}/${path.posix.basename(taskPath)}\`: ${(typeof RECEIPT.receiptFixHint === 'function' && RECEIPT.receiptFixHint(fails, body)) || 'write a runtime-bound `## Receipt` with command output'}.`
         : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {

package/src/claude/hooks/spec-state.cjs

@@ -44,6 +44,40 @@ function canonicalPath(value) {
   try { return fs.realpathSync(value); } catch { return null; }
 }
 
+/** Real path of `value`, resolving its deepest existing ancestor (the file may not exist yet). */
+function canonicalTarget(value) {
+  if (typeof value !== 'string' || !value) return null;
+  let current = path.resolve(value);
+  const rest = [];
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    rest.unshift(path.basename(current));
+    current = parent;
+  }
+  const real = canonicalPath(current);
+  return real ? path.join(real, ...rest) : null;
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Packets the prompt names: `specs/<name>`, a `/cf:<command> <name>` token, or the bare
+ * name when it carries `-`, `_` or a digit. A plain word such as `docs` must use `specs/`,
+ * so an ordinary sentence does not touch a packet.
+ */
+function packetsNamedIn(text, names) {
+  if (typeof text !== 'string' || !text) return [];
+  return names.filter((name) => {
+    const n = escapeRegExp(name);
+    if (new RegExp(`(^|[^\\w-])specs/${n}(?![\\w-])`).test(text)) return true;
+    if (new RegExp(`/cf:[\\w-]+\\s+(?:specs/)?${n}(?![\\w-])`).test(text)) return true;
+    return /[-_0-9]/.test(name) && new RegExp(`(^|[^\\w/-])${n}(?![\\w-])`).test(text);
+  });
+}
+
 try {
   // ── Main ──────────────────────────────────────────────────────────────────
 
@@ -51,7 +85,8 @@ try {
   if (!stdin) process.exit(0);
 
   const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
-  const payload = normalizeHookPayload(JSON.parse(stdin));
+  const rawPayload = JSON.parse(stdin);
+  const payload = normalizeHookPayload(rawPayload);
   const cwd     = payload.cwd || process.cwd();
 
   let POLICY;
@@ -84,6 +119,64 @@ try {
   const baseDir   = installedRoot || process.env.PROJECT_ROOT || cwd;
   const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
   const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
+
+  // ── Per-session touch set (Claude only) ───────────────────────────────────
+  // Several sessions can share one checkout. On Claude the tollgate speaks only about a
+  // packet this session touched. omp and Codex run their own copies, and grok sends
+  // `sessionId` before normalization, so all three keep the old behaviour.
+  const claudeSession = rawPayload && typeof rawPayload.session_id === 'string' && rawPayload.session_id
+    ? rawPayload.session_id
+    : null;
+  const touchFilter = runtimeDirName() === '.claude' && claudeSession !== null;
+  const touchFile = touchFilter
+    ? path.join(
+      require('./lib/hook-state-dir.cjs').hookStateDir(),
+      `spec-touched-${require('crypto').createHash('sha256').update(claudeSession).digest('hex')}.json`,
+    )
+    : null;
+  const readTouched = () => {
+    try {
+      const list = JSON.parse(fs.readFileSync(touchFile, 'utf8'));
+      return new Set(Array.isArray(list) ? list : []);
+    } catch { return new Set(); }
+  };
+  const addTouched = (names) => {
+    const touched = readTouched();
+    const before = touched.size;
+    for (const name of names) touched.add(name);
+    if (touched.size === before) return;
+    try {
+      fs.mkdirSync(path.dirname(touchFile), { recursive: true });
+      fs.writeFileSync(touchFile, JSON.stringify([...touched].sort()));
+    } catch { /* an unwritable state dir only loses the touch */ }
+  };
+  let specsRoot = null;
+  try { specsRoot = RESOLVER.specsDirectory(baseDir, runtime); } catch { /* resolver reports it below */ }
+
+  if (payload.hook_event_name === 'PostToolUse') {
+    // Record only; no resolve, no git, no tollgate cache.
+    if (touchFilter && specsRoot && /^(Edit|Write|MultiEdit)$/.test(payload.tool_name || '')) {
+      const realRoot = canonicalPath(specsRoot);
+      const realTarget = canonicalTarget(payload.tool_input && payload.tool_input.file_path);
+      if (realRoot && realTarget) {
+        const rel = path.relative(realRoot, realTarget);
+        const parts = rel.split(path.sep);
+        if (rel && parts[0] !== '..' && !path.isAbsolute(rel) && parts.length > 1) addTouched([parts[0]]);
+      }
+    }
+    process.exit(0);
+  }
+
+  if (touchFilter) {
+    let packets = [];
+    try {
+      packets = fs.readdirSync(specsRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    } catch { /* no specs root */ }
+    const named = packetsNamedIn(payload.prompt, packets);
+    if (typeof explicitFeature === 'string' && explicitFeature) named.push(explicitFeature);
+    if (named.length) addTouched(named);
+  }
+
   const resolveWorkflow = typeof RESOLVER.resolveWorkflowCandidate === 'function'
     ? RESOLVER.resolveWorkflowCandidate
     : RESOLVER.resolveActiveSpec;
@@ -118,6 +211,7 @@ try {
   const activeSpec = resolved.spec || {};
   const processWorkflow = resolved.layoutKind === 'process-v3';
   const featureName = resolved.featureName;
+  if (touchFilter && !readTouched().has(featureName)) process.exit(0);
   const specsPath = resolved.specsDir;
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,

package/src/claude/hooks/state.cjs

@@ -148,6 +148,21 @@ try {
     return data;
   }
 
+  /**
+   * True when latest.md holds something beyond the filler this hook writes itself:
+   * headings, HTML comments, the three placeholder bullets and timestamp-only agent results.
+   */
+  function hasPriorContent(text) {
+    const filler = [
+      /^#{1,6}\s/,
+      /^<!--.*-->$/,
+      /^- \((No completed tasks recorded|All tasks completed|No file changes detected)\)$/,
+      /^- Completed at \d{2}:\d{2}:\d{2}$/,
+    ];
+    return text.split('\n').map((line) => line.trim())
+      .some((line) => line && !filler.some((pattern) => pattern.test(line)));
+  }
+
   function buildStateContent(data) {
     const done = data.todos.filter((todo) => todo.status === 'completed' || todo.status === 'done');
     const pending = data.todos.filter((todo) => !['completed', 'done'].includes(todo.status));
@@ -226,14 +241,18 @@ try {
     if (!stdin) process.exit(0);
 
     const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
-    const data = normalizeHookPayload(JSON.parse(stdin));
+    const rawPayload = JSON.parse(stdin);
+    const data = normalizeHookPayload(rawPayload);
     const event = data.hook_event_name || '';
     const cwd = data.cwd || process.cwd();
     const dir = stateDir(cwd);
 
     if (event === 'SessionStart') {
       const previous = loadLatest(cwd);
-      if (previous) {
+      // Claude only: grok (camelCase sessionId), omp and Codex keep printing the block.
+      const claudeSession = runtimeDirName() === '.claude'
+        && typeof rawPayload.session_id === 'string' && rawPayload.session_id.length > 0;
+      if (previous && (!claudeSession || hasPriorContent(previous))) {
         console.log('\n=== Prior Execution Context ===');
         console.log(previous.trim());
         console.log('=== End of Prior Context ===\n');

package/src/claude/migration-manifest.json

@@ -7,23 +7,21 @@
   "skills": {
     "required": [
       "agent-browser",
+      "ask",
       "brainstorm",
       "chrome-devtools",
       "code-review",
       "debug",
-      "delegate",
       "develop",
+      "fix",
       "git",
-      "hotfix",
-      "inspect",
-      "loop",
       "orca",
-      "question",
       "research",
-      "route",
+      "scout",
       "specs",
       "sync",
       "test",
+      "ui-ux",
       "ui-ux-pro-max",
       "web-testing"
     ],
@@ -86,7 +84,13 @@
       "frontend-design",
       "mobile-development",
       "devops",
-      "react-best-practices"
+      "react-best-practices",
+      "inspect",
+      "hotfix",
+      "question",
+      "loop",
+      "route",
+      "delegate"
     ],
     "agents": {
       "claude": ["agents/god-developer.md"],
@@ -112,10 +116,27 @@
       "skills/specs/rules/ears-format.md",
       "skills/specs/rules/phase-decision-matrix.md",
       "skills/specs/rules/task-scoring-rubric.md",
-      "skills/specs/rules/tasks-generation.md"
+      "skills/specs/rules/tasks-generation.md",
+      "hooks/usage.cjs",
+      "hooks/completion-authority.cjs",
+      "hooks/completion-authority-check.cjs",
+      "hooks/completion-authority-state.cjs",
+      "hooks/semantic-review-authority.cjs",
+      "hooks/task-scaffold-guard.cjs"
     ],
     "settingsHookCommandSubstrings": [
-      "hooks/skill-router.cjs"
+      "hooks/skill-router.cjs",
+      ".claude/hooks/usage.cjs",
+      ".claude/hooks/docs-sync.cjs",
+      ".claude/hooks/completion-authority.cjs",
+      ".codex/hooks/completion-authority.cjs",
+      ".codex\\hooks\\completion-authority.cjs",
+      ".claude/hooks/semantic-review-authority.cjs",
+      ".codex/hooks/semantic-review-authority.cjs",
+      ".codex\\hooks\\semantic-review-authority.cjs",
+      ".claude/hooks/task-scaffold-guard.cjs",
+      ".codex/hooks/task-scaffold-guard.cjs",
+      ".codex\\hooks\\task-scaffold-guard.cjs"
     ]
   },
   "runtime": {
@@ -128,18 +149,12 @@
       "hooks/precompact.cjs",
       "hooks/docs-sync.cjs",
       "hooks/agent.cjs",
-      "hooks/usage.cjs",
       "hooks/privacy-block.cjs",
       "hooks/secret-output-guardrail.cjs",
       "hooks/inspect-block.cjs",
-      "hooks/task-scaffold-guard.cjs",
       "hooks/rules.cjs",
       "hooks/spec-state.cjs",
       "hooks/spec-gate.cjs",
-      "hooks/completion-authority.cjs",
-      "hooks/completion-authority-check.cjs",
-      "hooks/completion-authority-state.cjs",
-      "hooks/semantic-review-authority.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
       "hooks/lib/parser.cjs",

package/src/claude/rules/ai-dev-rules.md

@@ -42,7 +42,7 @@ Keep implementation simple, scoped, and verifiable.
 
 ## Git Hygiene
 
-- Lint before commit.
+- Lint before commit when the project has a linter.
 - Run required tests before push.
 - Keep commits focused.
 - Use conventional commits.

package/src/claude/rules/hook-protocols.md

@@ -4,28 +4,21 @@ Hooks are instruction boundaries. Do not bypass or work around them.
 
 ## Privacy Block Hook
 
-When a tool call is blocked by the privacy hook, the output contains a JSON marker between:
+When a tool call touches a sensitive file, or the hook cannot classify it safely,
+the privacy hook returns a permission decision of `ask` with the reason, and the
+host asks the user to approve or deny that one call. Do not ask again yourself.
+On a host whose hook can only deny, the call is blocked; ask the user instead of
+retrying it another way.
 
-```text
-@@PRIVACY_PROMPT_START@@
-...
-@@PRIVACY_PROMPT_END@@
-```
-
-Required flow:
-
-1. Parse the JSON payload from the marker.
-2. Ask the user for approval using the available user-question tool and the prompt/options from the payload.
-3. If approved, retry only the blocked action.
-4. If denied, continue without reading that file or performing that blocked action.
+- If approved, the call runs; do not widen it to other files.
+- If denied, continue without reading that file or performing that blocked action.
 
 Never use another command, path, encoding, or side channel to access a privacy-blocked file without explicit approval.
 
 ## State And Spec Hooks
 
 - If a hook reports state drift, run the appropriate sync/audit flow before continuing.
-- If a hook rejects task completion, keep the task `in_progress` or `blocked` until proof exists.
-- Do not mark a task `done` unless the matching task file contains a valid verification receipt.
+- If a hook rejects task completion, keep the task `in_progress` or `blocked` until proof exists; the receipt contract lives in `state-sync.md`.
 
 ## Hook Failure Handling
 

package/src/claude/rules/manage-docs.md

@@ -2,7 +2,7 @@
 
 ## Living Documents
 
-The project maintains these core documents in `./docs`:
+When the project keeps these core documents in `./docs`, keep them current (a project may have only some of them):
 
 | Document | Purpose |
 |----------|---------|
@@ -14,8 +14,6 @@ The project maintains these core documents in `./docs`:
 ### Freshness Rule
 
 - Before updating any doc, check its last modified date
-- If a doc hasn't been updated in >2 weeks while development is active, flag it for review
-- The `docs-keeper` agent should proactively scan for stale docs during weekly reviews
 
 ## When to Update
 
@@ -26,7 +24,6 @@ The `docs-keeper` agent is responsible for keeping these documents current. Trig
 - A significant feature ships or a critical bug is resolved
 - Security patches are applied or dependencies change
 - Project scope or timeline shifts
-- Weekly progress reviews are due
 
 ### Update Discipline
 
@@ -43,7 +40,7 @@ Use [Keep a Changelog](https://keepachangelog.com/) convention:
 ## [version] - YYYY-MM-DD
 
 ### Added
-- Feature description (#PR-number)
+- Feature description (#PR-number when there is one)
 
 ### Fixed
 - Bug fix description (#issue-number)
@@ -74,38 +71,27 @@ specs/
 
 Task files are direct children beside `plan.md`; do not place them in a task
 subdirectory.
-The plan records the C1 scope decision, explicit exclusions, acceptance
+The plan records the GATE-SCOPE scope decision, explicit exclusions, acceptance
 criteria, and task mapping. Each task owns one usable outcome, bounded paths,
 dependencies, acceptance, and a runnable Verification Plan.
 
 ### Gates and execution handoff
 
-- C1: the user chooses EXPAND, KEEP, or CUT before the plan is written.
-- C2: the user accepts, rejects, or revises deduplicated adversarial findings.
+- GATE-SCOPE: the user chooses EXPAND, KEEP, or CUT before the plan is written.
+- GATE-REVIEW: the user accepts, rejects, or revises deduplicated adversarial findings.
 - Specs stops after planning; implementation begins only through a new explicit
   Develop invocation.
-- C3: after execution, current receipts and limitations are shown and the user
+- GATE-DONE: after execution, current receipts and limitations are shown and the user
   decides whether the feature is complete.
 
 ### Task state and proof
 
-Each task contains exactly one `Status:` field. The final inline `## Receipt`
-is canonical proof and must contain the exact command, `Exit: 0`,
-`Verification: PASS`, runtime-derived Base and Head values, and non-empty
-fenced current output before the task becomes done.
+Task status, the inline `## Receipt` and its proof contract are defined in
+`state-sync.md`.
 
 Sync only observed state with surgical edits. Re-read the changed task after
 every update; never infer missing proof, approval, or readiness. When a done
 task changes user-facing behavior, architecture, API contracts, operations, or
 project status, classify docs impact and update only affected existing docs.
 
-Comply with the overarching rules in `./rules/ai-dev-rules.md`.
-
-## Legacy specification layout
-
-Existing features containing `spec.json`, nested `tasks/task-R*.md`, or other
-legacy kernel artifacts keep their installed adapters and original layout.
-Preserve `task_registry`, `semantic_model`, `planning_depth`, lane,
-`execution_tier`, machine authority, typed topology, separate receipts, and
-feature closeout files. Do not migrate them as part of unrelated documentation
-work.
+Comply with the overarching rules in `ai-dev-rules.md`.

package/src/claude/rules/orchestrator.md

@@ -22,10 +22,9 @@ Example prompt:
 
 ## Resource Constraints
 
-- Each subagent has a **200K token context window** — scope tasks to fit comfortably within it
-- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out. For parallel implementation waves the cap is 3 concurrent agents by default, never more than 5 (each agent carries the 200K budget above)
+- Each subagent has its own context window — scope tasks to fit comfortably within it
+- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out. For parallel implementation waves the cap is 3 concurrent agents by default, never more than 5 (each agent carries its own context window)
 - Prefer fewer, well-scoped agents over many overlapping ones
-- Include system resource info (from hook injection) when delegating tasks so subagents can self-regulate
 
 ---
 
@@ -132,7 +131,7 @@ Docs: [docs path]
 
 | ❌ Vague | ✅ Precise |
 |----------|-----------|
-| "Pick up where we left off" | "Add the `/users` POST endpoint per `phase-02.md`" |
+| "Pick up where we left off" | "Add the `/users` POST endpoint per `task-02-api.md`" |
 | "Fix the issues we talked about" | "Add null-check in `auth.ts:45` — root cause: missing input validation" |
 | "Explore the codebase" | "Read `src/api/routes.ts`, then add the missing handler" |
 | Dumping 50+ lines of chat history | A 5-line summary with file paths |

package/src/claude/rules/review-audit-self-decision.md

@@ -12,10 +12,10 @@ When rejecting an audit concern, name the verification source briefly.
 
 ## User Decisions
 
-Do not silently undo an explicit user decision. This covers the C1 scope choice,
-C2 finding dispositions, and C3 completion judgement, along with thresholds,
+Do not silently undo an explicit user decision. This covers the GATE-SCOPE scope choice,
+GATE-REVIEW finding dispositions, and GATE-DONE completion judgement, along with thresholds,
 selected libraries, feature scope, schema shape, pricing, timelines, compliance
-choices, and UX trade-offs. Those gates are defined in `workflow.md`; this rule
+choices, and UX trade-offs. Those gates are defined in `state-sync.md`; this rule
 governs only how a later review may treat them.
 
 If an audit suggests reversing a user decision, present:

package/src/claude/rules/skill-domain-routing.md

@@ -27,6 +27,4 @@ an entry condition for the primary. If zero valid capabilities match, continue
 inline when safe or name the gap. If multiple catalog entries expose the same
 public identity, do not auto-route; require explicit user disambiguation.
 
-Never infer an optional document capability from this rule. Never select the
-explicit-only numeric optimization capability unless the user invokes it with
-its required bounded metric/guard contract.
+Never infer an optional document capability from this rule.

package/src/claude/rules/skill-workflow-routing.md

@@ -9,9 +9,9 @@ workflow.
 1. If the user names a valid installed skill, use it directly.
 2. If one obvious low-risk installed skill covers the intent, use it directly.
 3. For direct factual conversation, answer directly or use the installed
-   evidence-answer capability; do not invoke Route or agents for ceremony.
-4. For ambiguous, multi-step, multi-domain, or elevated/high-risk work, use the
-   installed Route capability to classify and compose the shortest valid chain.
+   evidence-answer capability; do not spawn agents for ceremony.
+4. For ambiguous, multi-step, multi-domain, or elevated/high-risk work, classify
+   it yourself and compose the shortest valid chain below.
 
 Resolve every abstract link against the current runtime catalog. An absent,
 invalid, folder-mismatched, duplicate, or retired entry is not routable. Continue
@@ -28,5 +28,4 @@ owner, entry condition, and observable exit per retained link. Diagnosis does
 not authorize repair; implementation does not authorize commit, push, deploy,
 publish, or release; no route expands the user's existing authority.
 
-Use `skill-domain-routing.md` to resolve domain capability slots. The numeric
-optimization capability remains explicit-only and must never be auto-routed.
+Use `skill-domain-routing.md` to resolve domain capability slots.

package/src/claude/rules/state-sync.md

@@ -51,19 +51,10 @@ proves only the boundary it executed.
 
 ## Human gates and workflow ownership
 
-- C1 records the user's scope decision before the plan is written.
-- C2 records the user's disposition of deduplicated adversarial findings.
+- GATE-SCOPE records the user's scope decision before the plan is written.
+- GATE-REVIEW records the user's disposition of deduplicated adversarial findings.
 - Develop starts only after a new explicit user invocation and executes one
   unblocked task at a time.
 - Sync changes only observed file state and never starts implementation.
-- C3 occurs after current receipts and limitations are shown; the user decides
+- GATE-DONE occurs after current receipts and limitations are shown; the user decides
   whether the requested feature is complete.
-
-## Legacy compatibility
-
-Existing packets containing `spec.json`, nested `tasks/task-R*.md`, or other
-legacy kernel artifacts stay on their installed adapters. Preserve their
-`task_registry`, `semantic_model`, `planning_depth`, lane,
-`execution_tier`, typed topology, separate receipts, and feature closeout
-contract. Do not migrate that machine authority or storage shape while syncing
-an unrelated process-first packet.