@haposoft/cafekit 0.14.1 → 0.14.2

package/README.md

@@ -2,7 +2,7 @@
 
 > Claude Code-first spec-driven workflow and runtime bundle for AI coding assistants.
 
-[![Version](https://img.shields.io/badge/version-0.13.4-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.14.2-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Primary-orange.svg)](https://claude.ai/code)
 
@@ -82,10 +82,14 @@ Claude Code targets:
 ├── cafekit.json
 ├── status.cjs
 ├── runtime.json
-├── settings.json
-└── CLAUDE.md
+└── settings.json
+
+CLAUDE.md
 ```
 
+CafeKit owns only its marked block inside the project-root `CLAUDE.md`; project
+instructions outside that block are preserved across installs and upgrades.
+
 OpenCode targets:
 
 ```text

package/bin/__tests__/installer-safety.test.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+
+const backup = require('../lib/backup');
+const { copyClaudeMdFile } = require('../phases/claude-runtime');
+const { configureAddressing } = require('../phases/post-install');
+
+const START = '<!-- CAFEKIT CLAUDE START -->';
+const END = '<!-- CAFEKIT CLAUDE END -->';
+const TEMPLATE = fs.readFileSync(path.join(__dirname, '../../src/claude/CLAUDE.md'), 'utf8');
+
+function inTempProject(run) {
+  const originalCwd = process.cwd();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-installer-safety-'));
+  process.chdir(root);
+  try {
+    return run(root);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function installContext(pruned) {
+  return {
+    dryRun: false,
+    options: { forceOverwrite: true },
+    ownership: { '.claude': { files: {} } },
+    trackers: {
+      claude: {
+        recorded: () => null,
+        record: () => assert.fail('root CLAUDE.md must not be recorded'),
+        prune: (target) => pruned.push(target)
+      }
+    },
+    ui: { detail() {}, warn() {}, success() {} },
+    results: {
+      copied: 0,
+      updated: 0,
+      unchanged: 0,
+      preserved: 0,
+      missingDependencies: 0,
+      preservedFiles: []
+    }
+  };
+}
+
+test('managed CLAUDE block replacement preserves user bytes under force overwrite', () => {
+  inTempProject(() => {
+    const before = '# User preface\n\n';
+    const after = '\n\n## User tail\nKeep this exactly.\n';
+    fs.writeFileSync('CLAUDE.md', `${before}${START}\nold managed text\n${END}${after}`);
+
+    const pruned = [];
+    copyClaudeMdFile(installContext(pruned), 'claude');
+
+    const content = fs.readFileSync('CLAUDE.md', 'utf8');
+    assert.ok(content.startsWith(before));
+    assert.ok(content.endsWith(after));
+    assert.ok(content.includes(TEMPLATE.trimEnd()));
+    assert.equal(content.match(new RegExp(START, 'g')).length, 1);
+    assert.deepEqual(pruned, ['../CLAUDE.md']);
+  });
+});
+
+test('legacy pristine CLAUDE template migrates to one managed block', () => {
+  inTempProject(() => {
+    fs.writeFileSync('CLAUDE.md', TEMPLATE);
+    const pruned = [];
+
+    copyClaudeMdFile(installContext(pruned), 'claude');
+
+    const content = fs.readFileSync('CLAUDE.md', 'utf8');
+    assert.equal(content, `${START}\n${TEMPLATE.trimEnd()}\n${END}\n`);
+    assert.equal(content.match(new RegExp(START, 'g')).length, 1);
+    assert.deepEqual(pruned, ['../CLAUDE.md']);
+  });
+});
+
+test('addressing changes remain inside the managed CLAUDE block', () => {
+  inTempProject(() => {
+    const userSection = '## Addressing (Context Overflow Indicator)\n\nUser-owned wording.';
+    const managedSection = '## Addressing (Context Overflow Indicator)\n\nOld managed wording.';
+    fs.writeFileSync(
+      'CLAUDE.md',
+      `${userSection}\n\n${START}\n${managedSection}\n${END}\n`
+    );
+    const ctx = {
+      platforms: ['claude'],
+      ui: { success() {}, warn() {} },
+      t: () => 'updated'
+    };
+
+    configureAddressing(ctx, 'anh');
+
+    const content = fs.readFileSync('CLAUDE.md', 'utf8');
+    assert.ok(content.startsWith(`${userSection}\n\n${START}`));
+    assert.ok(content.includes('Claude Code always addresses the user as "anh"'));
+  });
+});
+
+test('backup restores existing targets and removes targets absent before the run', () => {
+  inTempProject(() => {
+    fs.mkdirSync('.claude/nested', { recursive: true });
+    fs.writeFileSync('.claude/nested/runtime.txt', 'before\n');
+    fs.writeFileSync('CLAUDE.md', 'user instructions\n');
+
+    const backupDir = backup.snapshot(
+      ['.claude', 'CLAUDE.md', '.gitignore'],
+      '20260729-test'
+    );
+    const metadata = JSON.parse(
+      fs.readFileSync(path.join(backupDir, 'snapshot.json'), 'utf8')
+    );
+    assert.deepEqual(metadata.targets, [
+      { target: '.claude', existed: true },
+      { target: 'CLAUDE.md', existed: true },
+      { target: '.gitignore', existed: false }
+    ]);
+
+    fs.writeFileSync('.claude/nested/runtime.txt', 'after\n');
+    fs.writeFileSync('CLAUDE.md', 'overwritten\n');
+    fs.writeFileSync('.gitignore', 'generated\n');
+    backup.restore(backupDir);
+
+    assert.equal(fs.readFileSync('.claude/nested/runtime.txt', 'utf8'), 'before\n');
+    assert.equal(fs.readFileSync('CLAUDE.md', 'utf8'), 'user instructions\n');
+    assert.equal(fs.existsSync('.gitignore'), false);
+    assert.equal(fs.existsSync(path.join(backupDir, 'snapshot.json')), true);
+  });
+});
+
+test('backup rejects traversal targets before snapshot or restore deletion', () => {
+  inTempProject(() => {
+    assert.throws(
+      () => backup.snapshot(['../outside'], '20260729-test'),
+      /Unsafe backup target/
+    );
+  });
+});

package/bin/install.js

@@ -170,11 +170,19 @@ async function main() {
     await runPostInstall(ctx);
     await setupSkillDeps(ctx);
     await setupRtk(ctx);
+
+    // Phase handlers may report recoverable-looking errors through counters
+    // instead of throwing. Treat them as transactional failure so the snapshot
+    // is restored before any success summary or backup pruning occurs.
+    if (ctx.results.errors > 0) {
+      throw new Error(`Installer reported ${ctx.results.errors} error${ctx.results.errors === 1 ? '' : 's'}`);
+    }
+
     printSummary(ctx);
 
     if (!ctx.dryRun) backup.prune(3);
 
-    exitCode = ctx.results.errors > 0 ? 1 : 0;
+    exitCode = 0;
   } catch (error) {
     const log = ctx && ctx.ui ? ctx.ui : { error: (m) => console.error(m) };
     const t = ctx ? ctx.t : (k) => k;

package/bin/lib/backup.js

@@ -14,6 +14,33 @@ const fs = require('fs');
 const path = require('path');
 
 const BACKUP_ROOT = '.cafekit-backup';
+const SNAPSHOT_METADATA = 'snapshot.json';
+const SNAPSHOT_DATA = 'data';
+
+function validateTarget(target) {
+  if (typeof target !== 'string' || !target || target.includes('\0')) {
+    throw new Error('Backup target must be a non-empty relative path');
+  }
+
+  // Validate both separator styles so a snapshot created on one platform
+  // cannot become unsafe when restored on another.
+  const portable = target.replace(/\\/g, '/');
+  const parts = portable.split('/');
+  if (path.isAbsolute(target) || portable.startsWith('/') || parts.includes('..') || parts.includes('')) {
+    throw new Error(`Unsafe backup target: ${target}`);
+  }
+  if (portable === '.' || portable === BACKUP_ROOT || portable.startsWith(`${BACKUP_ROOT}/`)) {
+    throw new Error(`Unsafe backup target: ${target}`);
+  }
+  return parts.join(path.sep);
+}
+
+function validateRunId(runId) {
+  if (typeof runId !== 'string' || !runId || runId === '.' || runId === '..' || /[\\/]/.test(runId)) {
+    throw new Error('Backup runId must be a single path segment');
+  }
+  return runId;
+}
 
 /**
  * Recursively copy a directory tree (verbatim, no transforms). Used for
@@ -40,42 +67,59 @@ function copyTree(src, dest) {
 }
 
 /**
- * Snapshot the given platform folders (relative to cwd, e.g. ['.claude']).
- * Only existing folders are captured. Returns the backup directory path, or
- * null if nothing existed to back up (fresh install → no rollback target).
+ * Snapshot explicit targets (relative to cwd, e.g. ['.claude', 'CLAUDE.md']).
+ * Every target is recorded, including targets absent before the run.
  *
  * @param {string[]} folders
  * @param {string} runId  unique id for this run (timestamp-based)
  */
 function snapshot(folders, runId) {
-  const existing = folders.filter((f) => fs.existsSync(f));
-  if (existing.length === 0) return null;
-
-  const backupDir = path.join(BACKUP_ROOT, runId);
+  const targets = [...new Set(folders.map(validateTarget))];
+  const backupDir = path.join(BACKUP_ROOT, validateRunId(runId));
+  const dataDir = path.join(backupDir, SNAPSHOT_DATA);
   fs.mkdirSync(backupDir, { recursive: true });
 
-  for (const folder of existing) {
-    copyTree(folder, path.join(backupDir, folder));
+  const records = [];
+  for (const target of targets) {
+    const existed = fs.existsSync(target);
+    records.push({ target, existed });
+    if (existed) copyTree(target, path.join(dataDir, target));
   }
+  fs.writeFileSync(
+    path.join(backupDir, SNAPSHOT_METADATA),
+    `${JSON.stringify({ schemaVersion: 1, targets: records }, null, 2)}\n`,
+    'utf8'
+  );
 
   return backupDir;
 }
 
 /**
- * Restore a snapshot back over the working tree. For each captured folder we
- * remove the current (possibly half-written) copy and replace it with the
- * snapshot, returning the tree to its pre-run state.
+ * Restore every explicit target to its pre-run state. Existing targets are
+ * replaced from backup; targets absent before the run are removed.
  *
  * @param {string} backupDir  path returned by snapshot()
  */
 function restore(backupDir) {
   if (!backupDir || !fs.existsSync(backupDir)) return;
 
-  for (const folder of fs.readdirSync(backupDir)) {
-    const target = folder; // backup mirrors cwd-relative folder names
-    const source = path.join(backupDir, folder);
+  const metadataPath = path.join(backupDir, SNAPSHOT_METADATA);
+  const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+  if (metadata?.schemaVersion !== 1 || !Array.isArray(metadata.targets)) {
+    throw new Error(`Invalid backup metadata: ${metadataPath}`);
+  }
+
+  for (const record of metadata.targets) {
+    if (!record || typeof record.existed !== 'boolean') {
+      throw new Error(`Invalid backup target metadata: ${metadataPath}`);
+    }
+    const target = validateTarget(record.target);
+    const source = path.join(backupDir, SNAPSHOT_DATA, target);
+    if (record.existed && !fs.existsSync(source)) {
+      throw new Error(`Backup data missing for target: ${target}`);
+    }
     fs.rmSync(target, { recursive: true, force: true });
-    copyTree(source, target);
+    if (record.existed) copyTree(source, target);
   }
 }
 

package/bin/lib/context.js

@@ -93,7 +93,7 @@ const PLATFORMS = {
     skillsRef: '.opencode/skills',
     commandPrefix: '/',
     sourceDir: 'claude',
-    sourceSubdir: 'archive-command'
+    sourceSubdir: 'commands'   // Dead config (manifest commands.core is []); kept for shape parity
   }
   // Add new platforms here:
   // cursor: {

package/bin/phases/claude-runtime.js

@@ -15,11 +15,50 @@ const {
   getRuntimeSupportTargetDir,
   getCopyOptions
 } = require('../lib/context');
+const { sha256 } = require('../lib/manifest');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
 const { normalizeOpenCodeBody } = require('../lib/opencode-install');
 
 const SRC = path.join(__dirname, '../../src');
+const CLAUDE_START = '<!-- CAFEKIT CLAUDE START -->';
+const CLAUDE_END = '<!-- CAFEKIT CLAUDE END -->';
+
+function managedClaudeBlock(template) {
+  return `${CLAUDE_START}\n${template.trimEnd()}\n${CLAUDE_END}`;
+}
+
+function managedClaudeRange(content) {
+  const start = content.indexOf(CLAUDE_START);
+  if (start === -1) return null;
+  const endStart = content.indexOf(CLAUDE_END, start + CLAUDE_START.length);
+  if (endStart === -1) return null;
+  return { start, end: endStart + CLAUDE_END.length, bodyStart: start + CLAUDE_START.length, bodyEnd: endStart };
+}
+
+/** Transform only the CafeKit-owned body, preserving all surrounding bytes. */
+function transformManagedClaudeContent(content, transform) {
+  const range = managedClaudeRange(content);
+  if (!range) return content;
+  const body = content.slice(range.bodyStart, range.bodyEnd);
+  return `${content.slice(0, range.bodyStart)}${transform(body)}${content.slice(range.bodyEnd)}`;
+}
+
+function upsertManagedClaudeBlock(existing, template, legacyOwned) {
+  const block = managedClaudeBlock(template);
+  const range = managedClaudeRange(existing);
+  if (range) {
+    return `${existing.slice(0, range.start)}${block}${existing.slice(range.end)}`;
+  }
+
+  // Whole-file migration is deliberately limited to exact shipped content or
+  // a file whose bytes still match the legacy ownership manifest.
+  if (existing === template || legacyOwned) return `${block}\n`;
+  if (!existing) return `${block}\n`;
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${separator}${block}\n`;
+}
 
 /** Copy ROUTING.md (SKILLS_DIR substituted; OpenCode body normalized). */
 function copyRoutingFile(ctx, platformKey) {
@@ -105,9 +144,22 @@ function copyClaudeMdFile(ctx, platformKey) {
     return;
   }
 
-  const { action } = writeManagedFile({
-    src, dest, platformFolder: PLATFORMS.claude.folder, ctx, tracker: ctx.trackers.claude
-  });
+  const tracker = ctx.trackers.claude;
+  // Older releases recorded the root file relative to .claude/. Never retain
+  // that whole-file ownership claim, even when this run makes no content change.
+  if (tracker) tracker.prune('../CLAUDE.md');
+
+  const template = fs.readFileSync(src, 'utf8');
+  const exists = fs.existsSync(dest);
+  const existing = exists ? fs.readFileSync(dest, 'utf8') : '';
+  const legacyRecord = ctx.ownership?.[PLATFORMS.claude.folder]?.files?.['../CLAUDE.md'];
+  const legacyOwned = Boolean(legacyRecord && legacyRecord.sha256 === sha256(existing));
+  const next = upsertManagedClaudeBlock(existing, template, legacyOwned);
+  const action = !exists ? 'created' : next === existing ? 'unchanged' : 'updated';
+
+  if (!ctx.dryRun && action !== 'unchanged') {
+    fs.writeFileSync(dest, next, 'utf8');
+  }
   report(ctx, action, 'CLAUDE.md');
 }
 
@@ -137,5 +189,6 @@ module.exports = {
   copyClaudeRuntimeFiles,
   removeObsoleteClaudeRuntimeFiles,
   copyClaudeMdFile,
-  copyRulesDirectory
+  copyRulesDirectory,
+  transformManagedClaudeContent
 };

package/bin/phases/post-install.js

@@ -16,6 +16,25 @@ const path = require('path');
 const { PLATFORMS } = require('../lib/context');
 const { LANGUAGE_LABELS } = require('../lib/i18n');
 const { setupOpenCodeModel } = require('../lib/opencode-install');
+const { transformManagedClaudeContent } = require('./claude-runtime');
+
+function updateManagedClaudeFile(filePath, transform) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const next = transformManagedClaudeContent(content, transform);
+  if (next === content) return false;
+  fs.writeFileSync(filePath, next, 'utf8');
+  return true;
+}
+
+function readManagedClaudeBody(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  let body = '';
+  transformManagedClaudeContent(content, (managed) => {
+    body = managed;
+    return managed;
+  });
+  return body;
+}
 
 /** Write `"language"` field into .claude/settings.json so it's visible at a glance. */
 function patchSettingsLanguage(ctx) {
@@ -64,20 +83,14 @@ Always respond in **${label}**. Technical terms, code identifiers, and file path
 
 `;
 
-  let content = fs.readFileSync(claudeMdFile, 'utf8');
-  // Replace if marker present, else replace the generic section.
+  // Replace only inside the installer-owned block.
   const markerRe = /## Language Consistency <!-- cafekit:lang -->[\s\S]*?(?=\n##|\n*$)/;
   const genericRe = /## Language Consistency\n[\s\S]*?(?=\n##|\n*$)/;
-
-  if (markerRe.test(content)) {
-    content = content.replace(markerRe, newSection);
-  } else if (genericRe.test(content)) {
-    content = content.replace(genericRe, newSection);
-  } else {
-    content += `\n${newSection}\n`;
-  }
-
-  fs.writeFileSync(claudeMdFile, content, 'utf8');
+  updateManagedClaudeFile(claudeMdFile, (managed) => {
+    if (markerRe.test(managed)) return managed.replace(markerRe, newSection);
+    if (genericRe.test(managed)) return managed.replace(genericRe, newSection);
+    return `${managed.trimEnd()}\n\n${newSection}\n`;
+  });
 }
 function patchRuntimeLocale(ctx) {
   for (const key of ctx.platforms) {
@@ -93,6 +106,10 @@ function patchRuntimeLocale(ctx) {
     // Use locale (freeform label) so custom languages propagate to the AI hook.
     const locale = ctx.locale || ctx.lang;
     if (data.locale.responseLanguage === locale) continue;
+    // Hardening: never downgrade an existing configured label to a bare default
+    // code when this run never made an explicit language choice (ctx.locale
+    // empty). Protects user config on any code path that skips selectLanguage.
+    if (!ctx.locale && data.locale.responseLanguage) continue;
     data.locale.responseLanguage = locale;
     fs.writeFileSync(rtPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
     if (ctx.trackers[key]) ctx.trackers[key].record(rtPath);
@@ -112,19 +129,18 @@ function configureAddressing(ctx, userAddress) {
   }
 
   const name = assistantName(ctx);
-  let content = fs.readFileSync(claudeMdFile, 'utf8');
   const addressingSection = `## Addressing (Context Overflow Indicator)
 
 ${name} always addresses the user as "${userAddress}" throughout the conversation. If it stops doing so, it is a sign the context has been compacted/truncated — tell the user to consider \`/clear\`.`;
 
-  // Idempotent: replace existing section (shared marker) or append.
+  // Idempotent and scoped to the installer-owned block.
   const regex = /##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?(?=\n##|\n*$)/;
-  content = regex.test(content)
-    ? content.replace(regex, addressingSection)
-    : `${content.endsWith('\n') ? content : `${content}\n`}\n${addressingSection}\n`;
-
-  fs.writeFileSync(claudeMdFile, content, 'utf8');
-  ctx.ui.success(ctx.t('addressingSet', { name, addr: userAddress }));
+  const changed = updateManagedClaudeFile(claudeMdFile, (managed) => (
+    regex.test(managed)
+      ? managed.replace(regex, addressingSection)
+      : `${managed.endsWith('\n') ? managed : `${managed}\n`}\n${addressingSection}\n`
+  ));
+  if (changed) ctx.ui.success(ctx.t('addressingSet', { name, addr: userAddress }));
 }
 
 async function setupAddressing(ctx) {
@@ -134,7 +150,7 @@ async function setupAddressing(ctx) {
   const claudeMdFile = path.join(process.cwd(), 'CLAUDE.md');
   let existingName = null;
   if (fs.existsSync(claudeMdFile)) {
-    const content = fs.readFileSync(claudeMdFile, 'utf8');
+    const content = readManagedClaudeBody(claudeMdFile);
     const match = content.match(/##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?always addresses the user as "([^"]+)"/);
     if (match) {
       existingName = match[1];
@@ -199,11 +215,8 @@ async function runPostInstall(ctx) {
   // Write "language" field into .claude/settings.json for visibility.
   patchSettingsLanguage(ctx);
 
-  // Re-record post-write baselines so installer-managed files stay "pristine",
-  // then flush each touched platform tracker.
-  if (ctx.platforms.includes('claude') && ctx.trackers.claude && fs.existsSync('CLAUDE.md')) {
-    ctx.trackers.claude.record('CLAUDE.md');
-  }
+  // Flush touched platform trackers. Root CLAUDE.md is block-managed and must
+  // never regain a whole-file ownership record.
   for (const key of ctx.platforms) {
     if (ctx.trackers[key]) ctx.trackers[key].write();
   }

package/bin/phases/select-platform.js

@@ -35,17 +35,22 @@ function getInstalledLocale() {
 
 /** First step: pick the installer/UI language (interactive only). */
 async function selectLanguage(ctx) {
-  if (!ctx.interactive || ctx.options.lang) return ctx;
-
-  // If already installed, restore saved locale and skip the prompt
-  const savedLocale = getInstalledLocale();
-  if (savedLocale) {
-    const code = Object.keys(LANGUAGE_LABELS).find((k) => LANGUAGE_LABELS[k] === savedLocale) || 'en';
-    ctx.setLang(code, savedLocale); // updates ctx.t to the saved language
-    ctx.ui.info(ctx.t('langKept', { lang: savedLocale }));
-    return ctx;
+  // Restore the saved locale BEFORE the interactivity check: a non-interactive
+  // upgrade (--yes) must not forget the configured language. Skipping this left
+  // ctx at the 'en' default, and patchRuntimeLocale then clobbered the user's
+  // responseLanguage on every upgrade.
+  if (!ctx.options.lang) {
+    const savedLocale = getInstalledLocale();
+    if (savedLocale) {
+      const code = Object.keys(LANGUAGE_LABELS).find((k) => LANGUAGE_LABELS[k] === savedLocale) || 'en';
+      ctx.setLang(code, savedLocale); // updates ctx.t to the saved language
+      if (ctx.interactive) ctx.ui.info(ctx.t('langKept', { lang: savedLocale }));
+      return ctx;
+    }
   }
 
+  if (!ctx.interactive || ctx.options.lang) return ctx;
+
   const options = [
     ...SUPPORTED.map((code) => ({ value: code, label: LANGUAGE_LABELS[code] })),
     { value: OTHER, label: OTHER_LABEL.en + ' / その他 / Ngôn ngữ khác' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -37,7 +37,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 ### 4. Goal-Driven Execution
 
 - Convert requests into verifiable success criteria.
-- For spec tasks, use `Completion Criteria` and `Evidence` as the source of truth. Existing task files may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
+- For spec tasks, use `Completion Criteria` and `## Evidence` (legacy heading aliases still parse) as the source of truth.
 - For bugs, reproduce with a failing test or concrete evidence when feasible before fixing.
 - Loop until verification passes or a real blocker is recorded.
 

package/src/claude/agents/code-auditor.md

@@ -23,7 +23,7 @@ Extract and verify:
 1. Declared deliverables (files, routes, entrypoints, UI surfaces, schemas, migrations)
 2. Declared task scope (`Related Files` and direct support files that are clearly justified)
 3. Completion Criteria
-4. Task Evidence expectations (or Task Test Plan & Verification Evidence / legacy Verification & Evidence)
+4. Task `## Evidence` (legacy heading aliases still parse) expectations
 5. Canonical Contracts & Invariants from the design
 6. Named technologies and runtime choices that the task/spec explicitly requires
 7. Runtime entrypoints/callers and reachability obligations from task evidence or the task-aware scout report

package/src/claude/agents/debugger.md

@@ -2,6 +2,7 @@
 name: debugger
 description: "Investigates bugs, incidents, CI/log/DB/performance/frontend failures, traces exact root causes with evidence, and hands off a verification-ready fix plan. Edits code only when explicitly requested by a fix workflow."
 model: sonnet
+memory: user
 tools: Glob, Grep, Read, Bash, WebFetch, WebSearch
 ---
 

package/src/claude/agents/god-developer.md

@@ -1,6 +1,6 @@
 ---
 name: god-developer
-description: "Primary code execution agent. Receives specifications (spec) from hapo:specs or task files and transforms them into production-grade source code. Operates on a Single-Track principle (linear, non-parallel)."
+description: "Primary code execution agent. Receives specifications (spec) from hapo:specs or task files and transforms them into production-grade source code. Operates on a Single-Track principle within its workspace (linear inside one working tree; multiple instances may run concurrently in separate isolated worktrees)."
 model: sonnet
 tools: Glob, Grep, Read, Edit, Write, NotebookEdit, Bash, WebFetch, WebSearch
 ---
@@ -94,3 +94,12 @@ Upon completion, output a concise report in this format:
 - Do not add AI attribution to code or commit messages.
 - Prioritize security (validate input, never hardcode secrets).
 - Code should be self-documenting — only add comments for complex logic.
+
+## Worktree Conduct (Parallel Wave dispatch)
+
+When dispatched into an isolated git worktree by `hapo:develop --parallel`:
+
+- Work ONLY inside this worktree; Single-Track discipline applies unchanged within it.
+- Do NOT edit `spec.json` or any `tasks/*.md` — the orchestrator is the single writer of spec state.
+- Do NOT touch files outside this task's `Related Files`.
+- Commit your completed work: `git commit -m "task(<id>): <title>"` — an uncommitted worktree cannot be merged back.

package/src/claude/agents/inspector.md

@@ -3,6 +3,7 @@ name: inspector
 tools: Glob, Grep, Read, Bash
 description: "Codebase structure scanner. Use this agent when you need to quickly scout/inspect the codebase architecture, files, and directories. Specializes in finding relevant files for a given work scope before implementation begins."
 model: haiku
+memory: user
 ---
 
 # Inspect — Codebase Scout

package/src/claude/agents/spec-maker.md

@@ -127,7 +127,7 @@ Before writing `design.md`, select a discovery mode and record the reason:
 - When requirement coverage format: list numeric IDs only, no descriptive suffixes
 - Apply `(P)` parallel markers when applicable (load `.claude/skills/specs/rules/tasks-parallel-analysis.md`)
 - Every task MUST use the compact implementation-ready shape: `Context`, `Steps`, `Requirements`, `Related Files`, `Completion Criteria`, `Evidence`, `Risk Assessment`.
-- `Evidence` MUST include exact commands, artifacts/runtime surfaces, runtime reachability proof, and negative-path checks. Existing specs may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
+- `## Evidence` (legacy heading aliases still parse) MUST include exact commands, artifacts/runtime surfaces, runtime reachability proof, and negative-path checks.
 - Completion criteria MUST be objective enough that a downstream quality gate can prove them without guesswork.
 - UI/app/runtime workflows MUST include a final integration/reachability task or final integration section that names the real entrypoint and proves all scoped user-facing surfaces are wired.
 - Do not allow orphan task outputs: components, services, hooks, routes, commands, workers, providers, reducers, data loaders, and generated artifacts must be reachable now or assigned to a named later integration task.

package/src/claude/agents/test-runner.md

@@ -11,7 +11,7 @@ You are a battle-hardened QA engineer who has been burned by production incident
 
 ## Task-Aware Inputs
 
-If the prompt includes task file paths, Completion Criteria, Evidence, Task Test Plan & Verification Evidence, or legacy Verification & Evidence instructions, treat them as authoritative.
+If the prompt includes task file paths, Completion Criteria, or `## Evidence` (legacy heading aliases still parse) instructions, treat them as authoritative.
 Diff-aware test selection does NOT replace task-specific verification.
 If the task/spec names a specific framework, auth system, transport, or shared-state boundary, keep that contract visible while evaluating evidence.
 If the prompt includes a feature name or `specs/<feature>`, load `spec.json`, `requirements.md`, `design.md`, and the active/recent task files. Treat `scope_lock`, Completion Criteria, and Evidence as the test contract.
@@ -30,7 +30,7 @@ Select tests by the task's touched surface:
 ## Command Resolution Order
 
 When the task file names exact commands, use this order:
-1. Run every exact executable command from `Evidence` (or `Task Test Plan & Verification Evidence` / legacy `Verification & Evidence`) in declaration order.
+1. Run every exact executable command from `## Evidence` (legacy heading aliases still parse) in declaration order.
 2. Run repo-default typecheck/test/build commands only to fill gaps not already covered above.
 3. Apply diff-aware test selection only after task-mandated commands are satisfied.