prizmkit 1.1.156 → 1.1.160

package/bundled/templates/project-memory-template.md

@@ -4,30 +4,30 @@
 This project uses PrizmKit with the Prizm documentation system for AI-optimized progressive context loading.
 
 ### Progressive Loading Protocol
-- ON SESSION START: Always read `.prizmkit/prizm-docs/root.prizm` first (L0 — project map)
-- ON RESUME (feature/bugfix directory has session-summary.md): Read session-summary.md first for prior context, then load only L1/L2 for modules mentioned in it
-- ON TASK: Read L1 (`.prizmkit/prizm-docs/<module>.prizm`) for relevant modules referenced in MODULE_INDEX or MODULE_GROUPS. If entries have keyword tags (e.g., `[login, jwt, oauth]`), match user's task against tags to prioritize which modules to load.
-- ON FILE EDIT: Read L2 (`.prizmkit/prizm-docs/<module>/<submodule>.prizm`) before modifying files. Pay attention to TRAPS and DECISIONS.
-- NEVER load all .prizm docs at once. Load only what is needed for the current task.
-
-### Auto-Update Protocol
-- BEFORE EVERY COMMIT: Update affected `.prizmkit/prizm-docs/` files
-- Platform hooks (rules or UserPromptSubmit) will remind you automatically
-- Use `/prizmkit-committer` for the complete commit workflow
+- ON SESSION START: Read exact `.prizmkit/prizm-docs/root.prizm` first when it exists; it alone is L0.
+- ON TASK: Read only relevant direct-child L1 documents (`.prizmkit/prizm-docs/<module>.prizm`) selected through MODULE_INDEX or MODULE_GROUPS pointers.
+- ON FILE EDIT: Read the complete relevant nested L2 and complete parent/child documents needed to resolve its SUBDIRS or DETAILS pointer. Grep-only fragments are insufficient modification context.
+- IF L2 IS ABSENT: Inspect bounded target source and narrowly implicated contracts without creating a placeholder; documentation creation belongs to Retrospective or explicit repair.
+- NEVER load all `.prizm` docs at once, load unrelated modules, or create L3.
+
+### Framework Directory and Maintenance Protocol
+- `.prizmkit/**` is the PrizmKit framework directory; owning capabilities may read/write their exact managed artifacts.
+- The project alone controls whether framework paths are ignored, untracked, or tracked. Do not add, remove, force-add, stage, commit, or interpret `.gitignore` entries as documentation maintenance.
+- Run `/prizmkit-retrospective` after validated changes when structure, interfaces, dependencies, behavior, or durable knowledge changed; it never owns staging/commit.
+- Use `/prizmkit-committer` for an exact commit operation. A Git-visible `.prizmkit/**` intended path receives ordinary exact-manifest and Secret checks; ignored paths remain absent.
 
 ### Doc Format Rules
 - All `.prizm` files use KEY: value format, not prose
-- Size limits: L0 = 4KB, L1 = 4KB, L2 = 5KB
+- Path levels and raw UTF-8 limits: exact `root.prizm` = L0/4096B; other direct `.prizm` children = L1/4096B; nested `.prizm` documents = L2/5120B
 - Arrow notation (->) indicates load pointers to other .prizm docs
 - Memory files must not contain CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths
-- Update durable sections in place; git history is the change log
-- No date/time fields — git is the authoritative source for temporal info
-
-### Creating New L2 Docs
-- When you first modify files in a sub-module that has no L2 doc:
-  1. Read the source files in that sub-module
-  2. Generate a new L2 `.prizm` file following Prizm specification
-  3. Add a pointer in the parent L1 doc's SUBDIRS section
+- Update durable sections in place; temporal and workflow history stays outside Prizm memory
+- No date/time fields and no Git-history requirement
+
+### Missing L2 Fallback
+- When relevant L2 is absent, inspect only bounded source needed for the current modification.
+- Do not create a placeholder merely because source was read or changed.
+- Retrospective or explicit documentation repair may later write a complete Value-Gate-qualified L2 and resolving parent pointer after identity, ownership, capacity, and format checks pass.
 
 ### Available Commands
 Run `/prizmkit` to see all available PrizmKit commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.156",
+  "version": "1.1.160",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/clean.js

@@ -5,13 +5,12 @@ import { loadMetadata, loadRulesMetadata } from './metadata.js';
 import { readManifest } from './manifest.js';
 import { privateProjectMemoryFile, projectMemoryFile } from './platforms.js';
 
+// Cleanup owns only deterministic private host-memory entries. Existing
+// `.prizmkit/**` ignore policy is project-owned and must remain untouched.
 const PRIZMKIT_GITIGNORE_HEADERS = new Set([
-  '# PrizmKit',
-  '# PrizmKit 运行时全部产物（state/、prizm-docs/、.env、logs 等）',
+  '# PrizmKit private host memory',
 ]);
 const PRIZMKIT_GITIGNORE_ENTRIES = new Set([
-  '.prizmkit/',
-  '.prizmkit/*',
   'CLAUDE.private.md',
   'AGENTS.private.md',
   'CODEBUDDY.private.md',
@@ -298,7 +297,7 @@ export async function runClean(directory, options = {}) {
     results.push(await cleanMarkedProjectMemory(projectRoot, privateMemoryFile, dryRun));
   }
 
-  // ── .gitignore cleanup ────────────────────────────────────────────────────
+  // ── Private host-memory .gitignore cleanup (never `.prizmkit/**`) ─────────
   const gitignoreResult = await cleanGitignore(projectRoot, dryRun);
 
   // ── Global team (optional) ────────────────────────────────────────────────
@@ -326,9 +325,9 @@ export async function runClean(directory, options = {}) {
 
   if (gitignoreResult.updated) {
     if (gitignoreResult.reason === 'dry_run') {
-      console.log(chalk.gray('    [dry-run] 将更新 .gitignore（移除 PrizmKit 段）'));
+      console.log(chalk.gray('    [dry-run] 将更新 .gitignore（仅移除私有主机记忆条目）'));
     } else {
-      console.log(chalk.green('    ✓ 已更新 .gitignore（移除 PrizmKit 段）'));
+      console.log(chalk.green('    ✓ 已更新 .gitignore（仅移除私有主机记忆条目）'));
     }
   }
 

package/src/gitignore-template.js

@@ -1,22 +1,18 @@
 /**
- * .gitignore 模板
- * 为新创建的 PrizmKit 项目生成合适的 .gitignore 内容。
+ * Generate only explicit private host-memory ignores.
+ *
+ * `.prizmkit/**` tracking policy is project-controlled: this module never adds,
+ * removes, or interprets framework-directory ignore entries.
  */
 
 /**
- * 生成 .gitignore 内容
- * @param {Object} options - { pipeline: boolean }
+ * @param {Object} options - { privateMemoryFiles?: string[] }
  * @returns {string}
  */
 export function generateGitignore(options = {}) {
   const privateMemoryFiles = Array.isArray(options.privateMemoryFiles)
-    ? options.privateMemoryFiles.filter(Boolean)
+    ? [...new Set(options.privateMemoryFiles.filter(Boolean))]
     : [];
-  const lines = [
-    '# PrizmKit',
-    '.prizmkit/*',
-    ...privateMemoryFiles,
-  ];
-
-  return [...new Set(lines)].join('\n');
+  if (privateMemoryFiles.length === 0) return '';
+  return ['# PrizmKit private host memory', ...privateMemoryFiles].join('\n');
 }

package/src/scaffold.js

@@ -4,7 +4,7 @@
  * 全部使用 Copy 模式（不使用 symlink），项目完全独立于框架仓库。
  * 通过 adapters 转换 core/ 资源为平台特定格式。
  * 不安装框架开发文件（docs、tests、scripts 等）。
- * 自动生成 .gitignore。
+ * 仅按显式平台需要合并私有记忆文件 ignore；`.prizmkit/**` Git 策略由项目控制。
  */
 
 import chalk from 'chalk';
@@ -381,6 +381,57 @@ export async function installSkills(platform, skills, projectRoot, dryRun, runti
  * Skill-owned references now provide inline reviewer/implementation subagent contracts.
  */
 
+const MANAGED_HOOK_MARKERS = [
+  '.prizmkit/scripts/commit-intent-status.py',
+  '.prizmkit/scripts/post-command-prizm-drift.py',
+  'PRIZMKIT_DOC_UPDATE_REQUIRED',
+  'PrizmKit: .prizmkit/prizm-docs found',
+];
+
+function isManagedHookEntry(entry) {
+  let serialized = '';
+  try {
+    serialized = JSON.stringify(entry);
+  } catch {
+    return false;
+  }
+  return MANAGED_HOOK_MARKERS.some(marker => serialized.includes(marker));
+}
+
+export function mergeManagedHooks(existingHooks = {}, managedHooks = {}) {
+  if (!existingHooks || typeof existingHooks !== 'object' || Array.isArray(existingHooks)) {
+    throw new Error('Cannot preserve malformed user hooks: hooks must be an object');
+  }
+  const merged = {};
+  for (const [event, entries] of Object.entries(existingHooks)) {
+    if (!Array.isArray(entries)) {
+      throw new Error(`Cannot preserve malformed user hooks: ${event} must be an array`);
+    }
+    merged[event] = entries.filter(entry => !isManagedHookEntry(entry));
+  }
+  for (const [event, entries] of Object.entries(managedHooks || {})) {
+    if (!Array.isArray(entries)) {
+      throw new Error(`Managed hook template is invalid: ${event} must be an array`);
+    }
+    const preserved = Array.isArray(merged[event]) ? merged[event] : [];
+    merged[event] = [...preserved, ...entries];
+  }
+  return merged;
+}
+
+async function readUserSettings(settingsPath) {
+  if (!await fs.pathExists(settingsPath)) return {};
+  try {
+    const value = await fs.readJSON(settingsPath);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error('settings root must be an object');
+    }
+    return value;
+  } catch (error) {
+    throw new Error(`Cannot preserve malformed user settings at ${settingsPath}: ${error.message}`);
+  }
+}
+
 /**
  * 安装平台配置文件（settings/hooks/rules）
  */
@@ -412,11 +463,16 @@ export async function installSettings(platform, projectRoot, options, dryRun, ru
 
     await fs.ensureDir(path.dirname(settingsPath));
 
-    // Read hook definition from unified template.
+    // Replace only deterministic managed hook entries and preserve user settings/hooks.
     const templatesDir = getTemplatesDir();
     const hookTemplate = await fs.readJSON(path.join(templatesDir, 'hooks', 'commit-intent.json'));
+    const existingSettings = await readUserSettings(settingsPath);
+    const settings = {
+      ...existingSettings,
+      hooks: mergeManagedHooks(existingSettings.hooks, hookTemplate.hooks),
+    };
 
-    await fs.writeFile(settingsPath, JSON.stringify(hookTemplate, null, 2));
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
     console.log(chalk.green(`      ✓ .codebuddy/settings.json`));
 
     // Install rules for CodeBuddy
@@ -466,26 +522,37 @@ export async function installSettings(platform, projectRoot, options, dryRun, ru
       'Bash(jq *)',
     ];
 
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const existingSettings = await readUserSettings(settingsPath);
+    const existingPermissions = existingSettings.permissions && typeof existingSettings.permissions === 'object'
+      ? existingSettings.permissions
+      : {};
+    const mergedPermissions = [...new Set([
+      ...(Array.isArray(existingPermissions.allow) ? existingPermissions.allow : []),
+      ...permissions,
+    ])];
+    const managedHooks = {
+      ...hookTemplate.hooks,
+      SessionStart: [
+        {
+          matcher: 'startup',
+          hooks: [
+            {
+              type: 'command',
+              command: 'test -f .prizmkit/prizm-docs/root.prizm && echo "PrizmKit: .prizmkit/prizm-docs found. Read exact root.prizm for project context." || echo "PrizmKit: No .prizmkit/prizm-docs found. Run /prizmkit-init to bootstrap."',
+            },
+          ],
+        },
+      ],
+    };
     const settings = {
-      permissions: { allow: permissions },
-      hooks: {
-        ...hookTemplate.hooks,
-        SessionStart: [
-          {
-            matcher: 'startup',
-            hooks: [
-              {
-                type: 'command',
-                command: 'test -f .prizmkit/prizm-docs/root.prizm && echo "PrizmKit: .prizmkit/prizm-docs found. Read root.prizm for project context." || echo "PrizmKit: No .prizmkit/prizm-docs found. Run /prizmkit-init to bootstrap."',
-              },
-            ],
-          },
-        ],
-      },
+      ...existingSettings,
+      permissions: { ...existingPermissions, allow: mergedPermissions },
+      hooks: mergeManagedHooks(existingSettings.hooks, managedHooks),
     };
 
     await fs.writeFile(
-      path.join(claudeDir, 'settings.json'),
+      settingsPath,
       JSON.stringify(settings, null, 2)
     );
     console.log(chalk.green(`      ✓ .claude/settings.json`));
@@ -553,59 +620,33 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function ensureTrailingNewline(value) {
-  return value.endsWith('\n') ? value : `${value}\n`;
-}
-
-function buildStandalonePrizmHook(templateContent) {
-  const content = templateContent.trimEnd();
-  const firstNewline = content.indexOf('\n');
-
-  if (content.startsWith('#!') && firstNewline !== -1) {
-    return [
-      content.slice(0, firstNewline),
-      PRIZMKIT_HOOK_MARKER_START,
-      content.slice(firstNewline + 1),
-      PRIZMKIT_HOOK_MARKER_END,
-      '',
-    ].join('\n');
-  }
-
-  return [
-    PRIZMKIT_HOOK_MARKER_START,
-    content,
-    PRIZMKIT_HOOK_MARKER_END,
-    '',
-  ].join('\n');
-}
-
 function buildShellPythonLauncherHook() {
   return [
     PRIZMKIT_HOOK_MARKER_START,
-    '# PrizmKit Python validation launcher',
-    'PRIZMKIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || PRIZMKIT_ROOT=""',
-    'if [ -n "$PRIZMKIT_ROOT" ] && [ -f "$PRIZMKIT_ROOT/.prizmkit/prizm-docs/root.prizm" ]; then',
-    '  PRIZMKIT_VALIDATE="$PRIZMKIT_ROOT/.prizmkit/scripts/validate-prizm-docs.py"',
-    '  [ -f "$PRIZMKIT_VALIDATE" ] || PRIZMKIT_VALIDATE="$PRIZMKIT_ROOT/.prizmkit/dev-pipeline/scripts/validate-prizm-docs.py"',
-    '  if [ -f "$PRIZMKIT_VALIDATE" ]; then',
-    '    if command -v python3 >/dev/null 2>&1; then',
-    '      python3 "$PRIZMKIT_VALIDATE" --staged || exit $?',
-    '    elif command -v python >/dev/null 2>&1; then',
-    '      python "$PRIZMKIT_VALIDATE" --staged || exit $?',
-    '    elif command -v py >/dev/null 2>&1; then',
-    '      py -3 "$PRIZMKIT_VALIDATE" --staged || exit $?',
-    '    else',
-    '      echo "PrizmKit: Python 3 is required for .prizm docs validation." >&2',
-    '      exit 1',
-    '    fi',
-    '  fi',
+    '# PrizmKit host-neutral staged documentation validation',
+    'PRIZMKIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0',
+    'PRIZMKIT_RUNNER="$PRIZMKIT_ROOT/.prizmkit/scripts/run-python-hook.cjs"',
+    'PRIZMKIT_PRE_COMMIT="$PRIZMKIT_ROOT/.prizmkit/scripts/prizm-pre-commit.py"',
+    'if [ -f "$PRIZMKIT_RUNNER" ] && [ -f "$PRIZMKIT_PRE_COMMIT" ] && command -v node >/dev/null 2>&1; then',
+    '  node "$PRIZMKIT_RUNNER" "$PRIZMKIT_PRE_COMMIT" || exit $?',
+    'elif git diff --cached --quiet -- .prizmkit/prizm-docs; then',
+    '  :',
+    'else',
+    '  echo "PrizmKit: staged Prizm documents require the installed host-neutral validator launcher." >&2',
+    '  exit 1',
     'fi',
     PRIZMKIT_HOOK_MARKER_END,
     '',
   ].join('\n');
 }
 
+function buildStandalonePrizmHook(templateContent) {
+  void templateContent;
+  return `#!/bin/sh\n${buildShellPythonLauncherHook()}`;
+}
+
 function buildAppendedPrizmHook(templateContent, userHookContent) {
+  void templateContent;
   if (/^#!.*\bpython[0-9.]*\b/i.test(userHookContent)) {
     return [
       PRIZMKIT_HOOK_MARKER_START,
@@ -613,13 +654,15 @@ function buildAppendedPrizmHook(templateContent, userHookContent) {
       'prizmkit_root_result = subprocess.run(["git", "rev-parse", "--show-toplevel"], text=True, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, check=False)',
       'if prizmkit_root_result.returncode == 0:',
       '    prizmkit_root = pathlib.Path(prizmkit_root_result.stdout.strip())',
-      '    prizmkit_validate = prizmkit_root / ".prizmkit/scripts/validate-prizm-docs.py"',
-      '    if not prizmkit_validate.is_file():',
-      '        prizmkit_validate = prizmkit_root / ".prizmkit/dev-pipeline/scripts/validate-prizm-docs.py"',
-      '    if prizmkit_validate.is_file():',
-      '        prizmkit_result = subprocess.run([sys.executable, str(prizmkit_validate), "--staged"], cwd=prizmkit_root, check=False)',
+      '    prizmkit_pre_commit = prizmkit_root / ".prizmkit/scripts/prizm-pre-commit.py"',
+      '    prizmkit_diff = subprocess.run(["git", "diff", "--cached", "--quiet", "--", ".prizmkit/prizm-docs"], cwd=prizmkit_root, check=False)',
+      '    if prizmkit_pre_commit.is_file():',
+      '        prizmkit_result = subprocess.run([sys.executable, str(prizmkit_pre_commit)], cwd=prizmkit_root, check=False)',
       '        if prizmkit_result.returncode != 0:',
       '            raise SystemExit(prizmkit_result.returncode)',
+      '    elif prizmkit_diff.returncode != 0:',
+      '        print("PrizmKit: staged Prizm documents require the installed validator.", file=sys.stderr)',
+      '        raise SystemExit(1)',
       PRIZMKIT_HOOK_MARKER_END,
       '',
     ].join('\n');
@@ -630,7 +673,10 @@ function buildAppendedPrizmHook(templateContent, userHookContent) {
 
 function insertPrizmHookIntoUserHook(userHookContent, prizmHookBlock) {
   const content = userHookContent.trimEnd();
-  const terminalSuccessExitPattern = /(^|\n)([ \t]*exit[ \t]+0[ \t]*(?:#.*)?)[ \t]*$/;
+  const isPython = /^#!.*\bpython[0-9.]*\b/i.test(content);
+  const terminalSuccessExitPattern = isPython
+    ? /(^|\n)([ \t]*(?:sys\.exit\(0\)|raise[ \t]+SystemExit\(0\)|exit\(0\))[ \t]*(?:#.*)?)[ \t]*$/
+    : /(^|\n)([ \t]*exit[ \t]+0[ \t]*(?:#.*)?)[ \t]*$/;
   const match = content.match(terminalSuccessExitPattern);
 
   if (!match) {
@@ -760,9 +806,11 @@ export async function installPrizmkitScripts(projectRoot, dryRun, runtime = 'pyt
 
   const scripts = [
     'validate-prizm-docs.py',
+    'prizm-pre-commit.py',
     'diff-prizm-docs.py',
     'commit-intent-status.py',
     'post-command-prizm-drift.py',
+    'run-python-hook.cjs',
   ];
   const legacyManagedScripts = [
     'validate-prizm-docs.sh',
@@ -1277,8 +1325,13 @@ export async function installGitignore(projectRoot, options = {}, dryRun) {
     privateMemoryFiles: options.privateMemoryFiles || [],
   });
 
+  if (!templateContent) {
+    if (dryRun) console.log(chalk.gray('      [dry-run] .gitignore (no managed private-memory entries)'));
+    return;
+  }
+
   if (dryRun) {
-    console.log(chalk.gray(`      [dry-run] .gitignore`));
+    console.log(chalk.gray(`      [dry-run] .gitignore (private host memory only)`));
     return;
   }
 
@@ -1291,14 +1344,15 @@ export async function installGitignore(projectRoot, options = {}, dryRun) {
 
     if (missing.length > 0) {
       const separator = existing.endsWith('\n') ? '' : '\n';
-      const header = existingLines.has('# PrizmKit') ? '' : '# PrizmKit\n';
+      const managedHeader = '# PrizmKit private host memory';
+      const header = existingLines.has(managedHeader) ? '' : `${managedHeader}\n`;
       await fs.appendFile(targetPath, separator + '\n' + header + missing.join('\n') + '\n');
       console.log(chalk.green(`      ✓ .gitignore (added ${missing.length} entries)`));
     } else {
       console.log(chalk.green('      ✓ .gitignore (up-to-date)'));
     }
   } else {
-    await fs.writeFile(targetPath, templateContent);
+    await fs.writeFile(targetPath, `${templateContent}\n`);
     console.log(chalk.green('      ✓ .gitignore'));
   }
 }

package/bundled/skills/prizmkit/references/workflow-state-protocol.md

@@ -1,178 +0,0 @@
-# PrizmKit Workflow State Protocol
-
-`workflow-state.json` is lifecycle metadata for one formal requirement. It preserves stage handoff, orchestrator ownership, and resume information without replacing skill-owned artifacts or any host-owned execution checkpoint.
-
-## Location and Identity
-
-The state filename uses the validated exact basename of `artifact_dir` without a second slug transformation:
-
-```text
-.prizmkit/state/workflows/<requirement-identity>.json
-```
-
-An existing state path whose recorded `artifact_dir` differs from the active artifact is a blocking collision; never overwrite, merge, or suffix it automatically. The active `artifact_dir` is preserved exactly across every stage:
-
-```text
-.prizmkit/specs/<requirement-slug>/
-.prizmkit/bugfix/<bug-id>/
-.prizmkit/refactor/<refactor-id>/
-```
-
-Never select another recent plan when resuming. Any external execution checkpoint remains separate from this state. Never merge, substitute, or infer one schema from the other.
-
-## Authority
-
-The state file is an index, not the authority for stage completion:
-
-| Information | Authority |
-|---|---|
-| Requirement goals and acceptance criteria | `{artifact_dir}/spec.md` |
-| Implementation tasks and completion | `{artifact_dir}/plan.md` plus current workspace |
-| Review findings and result | `{artifact_dir}/review-report.md` |
-| Test semantics and native execution | `{artifact_dir}/test-report.md` |
-| Terminal testing result | `{artifact_dir}/test-result.json` |
-| Retrospective completion | `{artifact_dir}/retrospective-result.json` |
-| Durable architecture knowledge | `.prizmkit/prizm-docs/` |
-| Local commit | Git history and runtime- or user-verified commit identity |
-| Current stage, orchestrator, and resume entry | Workflow state |
-| External orchestration progress | External host checkpoint |
-
-Every consumer compares workflow state with the skill-owned artifacts and current workspace. Missing or stale state is reconstructed from those sources and is never accepted as success by itself.
-
-## Schema
-
-```json
-{
-  "schema_version": 1,
-  "artifact_dir": ".prizmkit/specs/example",
-  "orchestrator": "prizmkit-workflow",
-  "stage": "test",
-  "status": "completed",
-  "stage_result": "TEST_PASS",
-  "completed_stages": ["plan", "implement", "code-review", "test"],
-  "repair_scope": null,
-  "repair_round": 0,
-  "next_stage": "retrospective",
-  "resume_from": "prizmkit-retrospective"
-}
-```
-
-### Fields
-
-| Field | Meaning |
-|---|---|
-| `schema_version` | State schema version. |
-| `artifact_dir` | Generic requirement artifact root reused by every stage. |
-| `orchestrator` | Semantic coordinator identifier, or null for direct stage use. |
-| `stage` | Stage that most recently wrote state. |
-| `status` | Lifecycle status: `pending`, `in_progress`, `completed`, `failed`, or `skipped`. |
-| `stage_result` | Coordinator-recorded lifecycle result mapped from a validated atomic result and its required artifacts, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
-| `completed_stages` | Ordered stages completed for this requirement. |
-| `repair_scope` | Optional caller-owned routing scope. The test skill reports high-risk repairs through `test-result.json` instead of scheduling another stage. |
-| `repair_round` | Optional outer cross-stage repair round, from 0 through 3. It is not a test-internal repair counter. |
-| `next_stage` | Next semantic stage, or null when stopped. |
-| `resume_from` | Exact atomic skill that can resume, or null when none is selected. |
-
-`status` and `stage_result` are deliberately separate. Lifecycle status values must never be replaced with domain result values.
-
-## Lifecycle and Result Mappings
-
-```text
-PLAN_READY
-→ IMPLEMENTED
-→ REVIEW_PASS
-→ TEST_PASS
-→ RETRO_COMPLETE
-→ COMMIT_PENDING
-→ COMMITTED
-```
-
-No formal stage is silently optional. Domain artifacts map to workflow state as follows:
-
-```text
-plan PLAN_READY                  → status=completed,  stage_result=PLAN_READY
-plan PLAN_BLOCKED                → status=failed,     stage_result=PLAN_BLOCKED
-implementation IMPLEMENTED       → status=completed,  stage_result=IMPLEMENTED
-implementation repair/block      → status=failed,     stage_result=IMPLEMENT_REPAIR or IMPLEMENT_BLOCKED
-review-report PASS               → status=completed,  stage_result=REVIEW_PASS
-review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEEDS_FIXES
-test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
-test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
-test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
-retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED   → status=completed, stage_result=RETRO_COMPLETE
-retrospective outcome=RETRO_COMPLETE, result=NO_DOC_CHANGE  → status=completed, stage_result=RETRO_COMPLETE
-retrospective outcome=RETRO_BLOCKED                         → status=failed,    stage_result=RETRO_BLOCKED
-runtime commit preparation       → status=in_progress, stage_result=COMMIT_PENDING
-local commit confirmed           → status=completed,  stage_result=COMMITTED
-commit blocked                   → status=failed,     stage_result=COMMIT_BLOCKED
-```
-
-`DOCS_UPDATED` and `NO_DOC_CHANGE` remain retrospective artifact `result` values. The workflow `stage_result` is the retrospective stage result `RETRO_COMPLETE`.
-
-`TEST_PASS` requires both `test-report.md` and a consistent `test-result.json`. No manifest, attestation, evidence package, or test-internal checkpoint is part of this contract.
-
-## Non-Pass Results and Routing Boundary
-
-`prizmkit-test` performs its own bounded failure repair and review loops before returning. The test skill never invokes another lifecycle stage.
-
-```text
-TEST_NEEDS_FIXES
-→ a known correction remains
-→ caller decides whether and how to arrange another invocation
-
-TEST_BLOCKED
-→ truth, input, safe environment, or reliable execution prevents a verdict
-→ never make speculative production edits
-→ caller or external host owns recovery policy
-```
-
-A test result is not an AI CLI session classification. `TEST_NEEDS_FIXES` and `TEST_BLOCKED` must not be rewritten as crash or infrastructure failure merely because they stop lifecycle progression.
-
-Any outer repair or continuation policy is independently owned by the caller and cannot alter the test report. The Main-Agent test review limit of ten rounds, independent Test Reviewer limit of five responses, and execution-failure repair limit of three rounds are internal to one test invocation and do not update outer counters.
-
-## Orchestrator Ownership and Handoff
-
-1. An atomic stage performs only its own stage, writes its truthful result and artifact paths, and returns control.
-2. When `orchestrator` is non-null, only that orchestrator invokes the next skill.
-3. Direct atomic use returns only its local result and artifacts; it does not report or select another invocation.
-4. Every handoff preserves the same `artifact_dir`.
-5. External automation invokes atomic stages directly and does not nest the composite workflow.
-6. Workflow state never replaces or absorbs an external host checkpoint.
-
-## Commit Execution Ownership
-
-Interactive execution:
-
-```text
-committer previews intended files and message
-→ waits for explicit current-user confirmation
-→ stages, creates, and verifies the local commit
-```
-
-Pipeline execution:
-
-```text
-external coordinator validates its required gates and supplies exact readiness evidence
-→ committer validates only that evidence and writes an exact runtime-commit-request.json
-→ external coordinator maps COMMIT_REQUEST_READY to its checkpoint's in_progress/COMMIT_PENDING state
-→ Python runtime validates the request, commits, verifies Git, and writes checkpoint completed/COMMITTED
-→ remote publication remains separate
-```
-
-The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode.
-
-## Recovery
-
-When state is missing, stale, or inconsistent:
-
-1. Reuse current context, then read `spec.md` and `plan.md` only when needed.
-2. Inspect task markers and current workspace.
-3. Read the current review report when needed to establish review authority.
-4. Validate that `test-report.md` and terminal `test-result.json` exist, agree, and reflect the claimed result.
-5. Validate `retrospective-result.json` when retrospective is claimed complete.
-6. Verify the commit when commit is claimed complete.
-7. Let an active external host validate its own checkpoint independently.
-8. Reconstruct the latest safe predecessor and report the reconstruction.
-9. Continue only from the first incomplete or invalid stage.
-
-Stale state never bypasses review, testing, retrospective, commit preparation/execution, or external checkpoint enforcement.