pan-wizard 3.35.0 → 3.37.0

package/docs/specs/workflow_state_consistency_featureai.md

@@ -0,0 +1,183 @@
+# Workflow State Consistency & Multi-Runtime Manifest Coverage — Feature Specification
+
+**Generated:** 2026-03-09
+**Version:** 1.0
+**Status:** Proposed
+**Source:** Deployment audit of d:\xxxx (PAN v2.8.0, 5 runtimes: Claude, Gemini, OpenCode, Codex, Copilot CLI)
+
+---
+
+## Problem Statement
+
+A deployment audit of a completed 5-phase Rust project with all 5 PAN runtimes installed simultaneously revealed systemic gaps in state consistency and multi-runtime manifest coverage:
+
+1. **Workflow state not auto-updated on phase/plan completion.** When phases execute and complete, REQUIREMENTS.md checkboxes and ROADMAP.md plan checkboxes/counts are not automatically updated. In the audited project, STATE.md correctly showed 42/42 requirements and 9/9 plans complete, yet REQUIREMENTS.md had 28/43 unchecked and ROADMAP.md had 6/9 plans unchecked with wrong counts ("0/0 plans complete"). This creates a trust gap — the project appears incomplete when it is actually done.
+
+2. **Copilot CLI runtime has 42 orphaned files.** The `.github/` runtime installed 39 skill files and 3 hook scripts that are not tracked in `pan-file-manifest.json`. The manifest generator does not cover `.github/copilot-skills/` or `.github/hooks/` paths, making these files invisible to the upgrade, patch-save, and validation systems.
+
+3. **Hook files not tracked across any runtime.** The 3 hook scripts (`pan-check-update.js`, `pan-context-monitor.js`, `pan-statusline.js`) are absent from the manifest in all 5 runtimes (#154 files tracked, 0 hooks). User modifications to hooks are silently overwritten during `pan-update`.
+
+4. **OpenCode runtime missing hook registration.** The `opencode.json` configuration file contains permissions but no hook registration entries. Context-monitor, status-line, and update-check hooks may not fire in the OpenCode runtime, degrading the user experience silently.
+
+5. **Phase/plan naming inconsistency.** Phases 1-3 use `NN-PLAN-MM-slug.md` naming (e.g., `01-PLAN-01-cli-connection.md`) while Phases 4-5 use `NN-MM-PLAN.md` (e.g., `04-01-PLAN.md`). PAN's state-tracking code must handle both patterns, but the inconsistency suggests plan creation doesn't enforce a canonical format.
+
+## Demand Evidence
+
+| Evidence Type | Source | Finding |
+|---|---|---|
+| Deployment audit | d:\xxxx REQUIREMENTS.md | 28/43 requirement checkboxes unchecked despite all code implemented |
+| Deployment audit | d:\xxxx ROADMAP.md | 6/9 plan checkboxes unchecked, plan counts showed "0/0" for completed phases |
+| Deployment audit | d:\xxxx STATE.md | Correctly showed 42/42 requirements, 5/5 phases — inconsistent with REQUIREMENTS.md |
+| Manifest scan | .github/pan-file-manifest.json | 154 entries; 39 skills + 3 hooks in `.github/` not tracked |
+| Manifest scan | .claude/pan-file-manifest.json | 154 entries; 3 hooks not tracked (same as all runtimes) |
+| Config review | .opencode/opencode.json | No hook registration section; only permissions present |
+| File listing | .planning/phase-*/ | Plans 1-3 use `NN-PLAN-MM-slug` format; Plans 4-5 use `NN-MM-PLAN` format |
+| Code review | install-lib.cjs `generateManifest()` | Skips `hooks/` directory and runtime-specific skill paths |
+
+## Success Criteria
+
+```
+SC-1: Phase completion auto-updates REQUIREMENTS.md checkboxes for mapped requirements
+SC-2: Phase completion auto-updates ROADMAP.md plan checkboxes and X/Y counts
+SC-3: All installed files (hooks, skills, agents, commands, core) tracked in manifest across all 5 runtimes
+SC-4: OpenCode runtime registers hooks in opencode.json during installation
+SC-5: Plan creation enforces a single canonical naming format
+SC-6: No regression in existing 1622+ tests
+SC-7: STATE.md ↔ REQUIREMENTS.md ↔ ROADMAP.md consistency is verifiable via /pan:health
+```
+
+## Competitive Landscape
+
+No competing AI workflow tool maintains cross-document state consistency or multi-runtime manifest tracking at this level.
+
+| Tool | State Auto-Sync | Manifest Tracking | Multi-Runtime | Cross-Doc Validation |
+|---|---|---|---|---|
+| **PAN Wizard** | STATE.md only | Partial (no hooks) | 5 runtimes | None |
+| **Aider** | N/A (no state) | None | 1 (CLI) | N/A |
+| **Cursor** | N/A | None | 1 (editor) | N/A |
+| **Cline** | N/A | None | 1 (editor) | N/A |
+
+## Design
+
+### Architecture
+
+```
+┌─────────────────────────────────────┐
+│        Phase Execution Flow         │
+│  (pan-executor completes a plan)    │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────┐
+│   State Sync Module (NEW)            │
+│  ┌────────────────────────────────┐  │
+│  │ syncRequirements(phase, plans) │  │ ← Check requirement boxes mapped to completed phase
+│  │ syncRoadmap(phase, plans)      │  │ ← Check plan boxes + update X/Y counts
+│  │ validateConsistency()          │  │ ← Cross-check STATE ↔ REQ ↔ ROADMAP
+│  └────────────────────────────────┘  │
+└──────────────────────────────────────┘
+
+┌─────────────────────────────────────┐
+│     Manifest Generator (ENHANCED)   │
+│  generateManifest() now covers:     │
+│  - pan-wizard-core/   ✓ (existing)  │
+│  - commands/           ✓ (existing)  │
+│  - agents/             ✓ (existing)  │
+│  - hooks/              ★ (NEW)       │
+│  - copilot-skills/     ★ (NEW)       │
+└─────────────────────────────────────┘
+
+┌─────────────────────────────────────┐
+│     OpenCode Installer (ENHANCED)   │
+│  writeOpenCodeConfig() now adds:    │
+│  - hook registration entries  ★ NEW  │
+└─────────────────────────────────────┘
+```
+
+### Key Design Decisions
+
+1. **State sync runs post-plan, not post-phase.** Each plan knows its parent phase and requirement mappings. Syncing after each plan gives incremental progress visibility rather than a batch update at phase end.
+2. **Cross-doc validation added to /pan:health.** The `validate health` route gains a `state-consistency` check that compares STATE.md counts against REQUIREMENTS.md checkboxes and ROADMAP.md plan checkboxes.
+3. **Manifest generation is additive.** Hooks and skills are added to the existing manifest structure — no schema change needed, just expanding the file walker's include paths.
+
+## Feature Ladder
+
+| Priority | Feature | Effort | Impact | Dependency |
+|---|---|---|---|---|
+| P0 | B.1 Manifest covers hooks in all runtimes | S | High | None |
+| P0 | B.2 Manifest covers Copilot skills | S | High | None |
+| P0 | B.3 OpenCode hook registration | S | Medium | None |
+| P1 | B.4 State sync: REQUIREMENTS.md auto-update | M | High | None |
+| P1 | B.5 State sync: ROADMAP.md auto-update | M | High | B.4 |
+| P1 | B.6 Cross-doc consistency check in /pan:health | M | High | B.4, B.5 |
+| P2 | B.7 Canonical plan naming enforcement | S | Low | None |
+| P2 | B.8 Plan summary enforcement (all plans get SUMMARY.md) | S | Low | None |
+
+## Implementation Tasks
+
+| ID | Task | Points | Dependencies | Priority |
+|---|---|---|---|---|
+| B.1 | Add hooks/ to `generateManifest()` file walker in install-lib.cjs | 2 | — | P0 |
+| B.2 | Add `.github/copilot-skills/` to manifest walker for Copilot runtime | 2 | — | P0 |
+| B.3 | Add hook registration to `writeOpenCodeConfig()` in install.js | 2 | — | P0 |
+| B.4 | Create `syncRequirements()` in state-mutations or new state-sync module | 5 | — | P1 |
+| B.5 | Create `syncRoadmap()` — update plan checkboxes and X/Y counters | 5 | B.4 | P1 |
+| B.6 | Add `state-consistency` check to `validate health` route | 3 | B.4, B.5 | P1 |
+| B.7 | Enforce canonical `NN-PLAN-MM-slug.md` format in plan creation | 2 | — | P2 |
+| B.8 | Check for missing SUMMARY.md on completed plans in health check | 2 | — | P2 |
+| B.9 | Tests for B.1-B.3 (manifest and config) | 3 | B.1, B.2, B.3 | P0 |
+| B.10 | Tests for B.4-B.6 (state sync and health) | 5 | B.4, B.5, B.6 | P1 |
+| **Total** | | **31** | | |
+
+### Dependency Graph
+
+```
+B.1 ──┐
+B.2 ──┼── B.9 (tests)
+B.3 ──┘
+B.4 ──── B.5 ──┐
+                ├── B.6 ──── B.10 (tests)
+                │
+B.7 (independent)
+B.8 (independent)
+```
+
+## Test Plan
+
+### Unit Tests
+- `generateManifest()` includes hooks/ entries with correct SHA256
+- `generateManifest()` includes `.github/copilot-skills/` for Copilot runtime
+- `writeOpenCodeConfig()` produces valid JSON with hook registrations
+- `syncRequirements()` checks boxes for specified requirement IDs
+- `syncRoadmap()` checks plan boxes and updates count strings
+- `validateConsistency()` returns mismatch list when STATE ↔ REQ diverge
+
+### Integration Tests
+- Full install + audit cycle: install all 5 runtimes → verify manifest covers all files
+- Phase execution → verify REQUIREMENTS.md + ROADMAP.md updated
+- `/pan:health` reports state inconsistency when manually introduced
+
+### Acceptance Criteria
+- Audit of a completed multi-phase project shows 0 state inconsistencies
+- Audit of a multi-runtime install shows 0 orphaned files
+
+## Security Considerations
+
+- Manifest SHA256 hashes prevent undetected file tampering
+- No user input enters file paths (all paths derived from known install prefixes)
+
+## Risk Register
+
+| Risk | Probability | Impact | Mitigation |
+|---|---|---|---|
+| State sync corrupts REQUIREMENTS.md | Medium | High | Write atomically (temp + rename); validate markdown structure before write |
+| Regex-based checkbox update mismatches | Medium | Medium | Unit tests with diverse markdown formatting; match requirement IDs exactly |
+| OpenCode hook format changes | Low | Medium | Pin to known opencode.json schema; test against current version |
+| Plan naming migration breaks existing projects | Low | Medium | Enforce only on new plans; add migration command for existing projects |
+
+## Sources
+
+- Deployment audit of d:\xxxx (2026-03-09): 5-runtime install, completed Rust project
+- Deployment audit of d:\pantesting (2026-03-09): fresh Claude single-runtime install
+- PAN Wizard source: install-lib.cjs `generateManifest()`, install.js `writeOpenCodeConfig()`
+- PAN executor agent: pan-executor.md phase completion flow

package/hooks/dist/pan-context-monitor.js

@@ -412,12 +412,18 @@ function buildContextWarning(metrics, warnState, nowSeconds, opts = {}) {
   // No figures (O7): a countdown makes a model wrap up early, and a percentage is
   // the thing it would count down. The note names the checkpoint, says compaction
   // is safe, and asks for no shortcuts.
+  // Name .planning/state.md only in a project that keeps one: elsewhere the note sent the
+  // session to update a file the project does not have (field report, 2026-10-21).
+  const where = opts.hasState === false
+    ? 'wherever this project records its progress'
+    : '.planning/state.md';
+  const pause = opts.hasState === false ? '' : '; /pan:pause writes it';
   const message = isCritical
     ? 'PAN context note (from the context-monitor hook, not the user): the host will compact this session soon. ' +
-      'Before your next step, make sure .planning/state.md records where you are — the phase, the plan and task, and what comes next; /pan:pause writes it. ' +
+      `Before your next step, make sure ${where} records where you are — the phase, the plan and task, and what comes next${pause}. ` +
       'Then carry on with the current task as normal. After compaction PAN restores the planning state, so finish the task properly rather than quickly.'
     : 'PAN context note (from the context-monitor hook, not the user): this session\'s context is filling up. ' +
-      'At your next natural stopping point, such as a finished task or a commit, make sure .planning/state.md records where you are; /pan:pause writes it. ' +
+      `At your next natural stopping point, such as a finished task or a commit, make sure ${where} records where you are${pause}. ` +
       'Nothing needs to stop: the host compacts on its own and PAN restores the planning state afterwards, so keep working at full quality, with no shortcuts and no skipped verification.';
 
   return {
@@ -502,6 +508,7 @@ function main() {
       }
 
       const decision = buildContextWarning(metrics, warnData, now, {
+        hasState: fs.existsSync(path.join(data.cwd || process.cwd(), '.planning', 'state.md')),
         env: process.env,
         settings: Number.isFinite(Number(metrics.total_input_tokens)) ? settings : [],
       });

package/hooks/dist/pan-cost-logger.js

@@ -227,6 +227,10 @@ const COMMAND_TAIL_BYTES = 262144;
 // so only these are attributed — a host UI command (`/model`, `/compact`) and a plain
 // typed prompt leave the row honestly unattributed instead of borrowing a name.
 const PAN_COMMAND_RE = /<command-name>\s*\/?pan[:-]([a-z0-9][a-z0-9-]*)\s*<\/command-name>/i;
+// Autodev's lean execute unit types no slash command: its prompt names the exec-lean
+// workflow (autodev.cjs unitPrompt). Without this the lean sessions, most of a lean
+// project's spend, carried `command: null` (2026-10-25).
+const LEAN_UNIT_RE = /^PAN autodev unit, lean phase \d/i;
 
 /**
  * The PAN command in whose turn this agent ran, read from the PARENT session transcript.
@@ -286,6 +290,7 @@ function readCommandFromTranscript(transcriptPath) {
       if (!typed) continue;
       const m = typed.match(PAN_COMMAND_RE);
       if (m) return m[1].toLowerCase();
+      if (LEAN_UNIT_RE.test(typed.trim())) return 'exec-lean';
     }
     return null;
   } catch {

package/hooks/dist/pan-guard.js

@@ -12,14 +12,18 @@
 //                         or a long key=value secret)
 //   state_write           a direct write to PAN's own state: state.md, findings.jsonl,
 //                         the token ledger (pan-tools owns those)
+//   judge_write           a judge (verifier, reviewer, plan-checker, design-checker)
+//                         writing outside the planning tree; the payload names the
+//                         agent (`agent_type`) only on hosts that say so
 //   undeclared_test_edit  a test file the phase in flight does not declare in any
 //                         unfinished plan's files_modified
 //
 // Mode, from the planning tree's config.json `hooks.guard`:
 //   off      nothing
 //   report   (default) every match is appended to <planning>/guard.jsonl, the call proceeds
-//   enforce  as report, and a secret_write is denied; the other rules still only report
-//            until the writers of PAN's state go through pan-tools verbs (A7b)
+//   enforce  as report, and secret_write, state_write and judge_write are denied (the
+//            writers of state.md go through pan-tools verbs since A7b);
+//            undeclared_test_edit still only reports
 //
 // Inert outside a PAN project. Fail-open on anything it cannot parse; never fail-open
 // on a matched deny. Never writes outside the planning tree.
@@ -32,6 +36,9 @@ const SECRET_KV_RE = /\b(api[_-]?key|access[_-]?token|auth[_-]?token|refresh[_-]
 const TEST_PATH_RE = /(^|\/)(tests?|__tests__|specs?)\//i;
 const TEST_FILE_RE = /(\.(test|spec)\.[a-z0-9]+|(^|\/)test_[^/]+\.py|_test\.(py|go)|Tests?\.(java|kt|cs))$/i;
 const MODES = ['off', 'report', 'enforce'];
+// The agents that judge work and must not change it. Their reports go in the planning tree.
+const JUDGES = new Set(['pan-verifier', 'pan-reviewer', 'pan-plan-checker', 'pan-design-checker']);
+const DENIED = ['secret_write', 'state_write', 'judge_write'];
 
 // ─── R39: one run per hook when Claude and Copilot share a project ───────────
 // Copilot CLI also runs the hooks in a repository's .claude/settings.json and
@@ -130,7 +137,8 @@ function normalise(payload) {
       if (cur && line.startsWith('+')) cur.text += line.slice(1) + '\n';
     }
   }
-  return { tool, writes, command };
+  const agent = String(p.agent_type || p.subagent_type || p.agentType || '') || null;
+  return { tool, writes, command, agent };
 }
 
 /** Project-relative POSIX path, or null when the path is outside the project. */
@@ -184,6 +192,7 @@ function evaluate(call, projectDir, planningRel) {
     if (hasSecret(w.text)) hits.push({ rule: 'secret_write', path: r || w.path });
     if (!r) continue;
     if (ownState.has(r)) hits.push({ rule: 'state_write', path: r });
+    if (call.agent && JUDGES.has(call.agent) && !(r === planningRel || r.startsWith(`${planningRel}/`))) hits.push({ rule: 'judge_write', path: r, agent: call.agent });
     if (declared && isTestFile(r) && !declared.has(r)) hits.push({ rule: 'undeclared_test_edit', path: r });
   }
   return hits;
@@ -191,7 +200,11 @@ function evaluate(call, projectDir, planningRel) {
 
 function decide(hits, mode) {
   if (mode !== 'enforce') return null;
-  return hits.find((h) => h.rule === 'secret_write') || null;
+  for (const rule of DENIED) {
+    const hit = hits.find((h) => h.rule === rule);
+    if (hit) return hit;
+  }
+  return null;
 }
 
 /** The host whose deny format this call needs: Copilot by payload shape, else the --host flag. */
@@ -201,6 +214,16 @@ function hostOf(payload, flagHost) {
   return flagHost;
 }
 
+function denyReason(deny) {
+  if (deny.rule === 'state_write') {
+    return `PAN guard: ${deny.path} is PAN's own state. Write it through pan-tools (\`pan-tools state init|section|apply|patch|update\`, \`findings record\`), which keeps it consistent, then retry. (hooks.guard: enforce)`;
+  }
+  if (deny.rule === 'judge_write') {
+    return `PAN guard: ${deny.agent} is a judge and does not change the work it judges (${deny.path}). Report the defect in your verdict instead; your own report goes in the planning tree. (hooks.guard: enforce)`;
+  }
+  return `PAN guard: this write puts a credential into ${deny.path}. Keep secrets out of the repository (an environment variable or a local, ignored file), then retry. (hooks.guard: enforce)`;
+}
+
 function main() {
   const flagHost = (process.argv[process.argv.indexOf('--host') + 1] || 'claude').toLowerCase();
   let raw = '';
@@ -230,7 +253,7 @@ function main() {
     fs.appendFileSync(path.join(planning, 'guard.jsonl'), lines.join('\n') + '\n');
   } catch { /* the log is best effort; a deny below still stands */ }
   if (!deny) return;
-  const reason = `PAN guard: this write puts a credential into ${deny.path}. Keep secrets out of the repository (an environment variable or a local, ignored file), then retry. (hooks.guard: enforce)`;
+  const reason = denyReason(deny);
   if (host === 'copilot') {
     process.stdout.write(JSON.stringify({ permissionDecision: 'deny', permissionDecisionReason: reason }) + '\n');
     return;

package/hooks/dist/pan-stop-guard.js

@@ -59,7 +59,11 @@
 // Copilot also ends the turn itself after eight consecutive blocks.
 //
 // Escape hatch: set workflow.stop_guard to false in .planning/config.json to
-// disable the guard entirely without turning off auto_advance.
+// disable the guard entirely without turning off auto_advance. That is the user's
+// setting: the block reason tells an agent that was asked to stop to end its turn
+// again (the guard is one-shot), never to change it (2026-10-25: a harness session
+// told to stop after /pan:new-project followed the old reason's advice and
+// committed workflow.stop_guard: false into the project, disarming every later run).
 //
 // Fail-open everywhere: no .planning, unparseable config/state/roadmap, bad
 // stdin — exit 0 silently. This guard must never block a stop on uncertainty;
@@ -73,10 +77,6 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-// The CLI the block reason tells the agent to run. Installs and the plugin put the
-// core beside hooks/; no `pan-tools` bin is on PATH.
-const PAN_TOOLS = `node "${path.join(__dirname, '..', 'pan-wizard-core', 'bin', 'pan-tools.cjs').split(path.sep).join('/')}"`;
-
 // ─── R39: one run per hook when Claude and Copilot share a project ───────────
 // Copilot CLI also runs the hooks in a repository's .claude/settings.json and
 // .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
@@ -209,10 +209,10 @@ function buildStopDecision({ stopHookActive, config, stateContent, roadmapConten
       `Continue the chain now: if the current phase is finished, follow transition.md's ` +
       `offer_next_phase Route A and spawn Phase ${nextPhase} as a Task subagent ` +
       `(plan-phase orchestrator, ARGUMENTS='${nextPhase} --auto'); if the current phase is ` +
-      `mid-flight, resume it instead. If the user explicitly asked to stop, first run ` +
-      `\`${PAN_TOOLS} config-set workflow.auto_advance false\` (under mode: yolo, which arms this ` +
-      `guard by itself, set \`workflow.stop_guard false\` the same way instead) — then stop. ` +
-      `(Disable this guard permanently with workflow.stop_guard: false.)`
+      `mid-flight, resume it instead. If the user or the command you are running explicitly ` +
+      `said to stop here, end your turn again: this guard blocks a stop only once, so the next ` +
+      `stop goes through. Do not change workflow.auto_advance, workflow.stop_guard or mode to ` +
+      `get past it: they are the user's settings and every later session reads them.`
   };
 }
 

package/hooks/dist/pan-trace-logger.js

@@ -223,6 +223,10 @@ const COMMAND_TAIL_BYTES = 262144;
 // so only these are attributed — a host UI command (`/model`, `/compact`) and a plain
 // typed prompt leave the row honestly unattributed instead of borrowing a name.
 const PAN_COMMAND_RE = /<command-name>\s*\/?pan[:-]([a-z0-9][a-z0-9-]*)\s*<\/command-name>/i;
+// Autodev's lean execute unit types no slash command: its prompt names the exec-lean
+// workflow (autodev.cjs unitPrompt). Without this the lean sessions, most of a lean
+// project's spend, carried `command: null` (2026-10-25).
+const LEAN_UNIT_RE = /^PAN autodev unit, lean phase \d/i;
 
 /**
  * The PAN command in whose turn this agent ran, read from the PARENT session transcript.
@@ -282,6 +286,7 @@ function readCommandFromTranscript(transcriptPath) {
       if (!typed) continue;
       const m = typed.match(PAN_COMMAND_RE);
       if (m) return m[1].toLowerCase();
+      if (LEAN_UNIT_RE.test(typed.trim())) return 'exec-lean';
     }
     return null;
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.35.0",
+  "version": "3.37.0",
   "description": "Command a bot army for your codebase: a reasoning-tier Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"
@@ -14,7 +14,10 @@
     "hooks/dist",
     "scripts",
     "assets",
-    "pan-zcode"
+    "pan-zcode",
+    "docs",
+    "!docs/branding/assets",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "claude",
@@ -73,6 +76,11 @@
     "test:coverage": "node scripts/coverage-gate.cjs",
     "test:surface": "node scripts/test-surface.cjs --check",
     "test:mutate": "node scripts/mutation-probe.cjs",
+    "ci:local": "node scripts/local-ci.cjs",
+    "ci:local:fast": "node scripts/local-ci.cjs --fast",
+    "hooks:pre-push": "node scripts/install-pre-push.cjs",
+    "ci:schedule": "node scripts/local-schedule.cjs",
+    "land": "node scripts/land.cjs",
     "build:plugin": "node scripts/build-plugin.js",
     "build:agent-plugin": "node scripts/build-agent-plugin.js",
     "harness": "node harness/src/run.cjs --tier 0",

package/pan-wizard-core/bin/lib/agents-md.cjs

@@ -6,7 +6,11 @@
 // OpenCode and Copilot CLI read it natively, Claude Code only through the @AGENTS.md
 // import in CLAUDE.md; Gemini CLI reads GEMINI.md by default, not this file. PAN contributes one
 // marker-fenced section so agents in any runtime understand the PAN context
-// when reading the repo. User content outside the markers is never touched.
+// when reading the repo. User content outside the markers is never touched, and
+// neither is a section the project edited inside them: PAN replaces only text it
+// generated itself, this release's or an earlier one's (sectionState). A project
+// whose work does not live in .planning/ said so in its own words there, and an
+// update put PAN's generic text back (field report, 2026-10-21).
 //
 // SSOT NOTE: these builders are the single source of truth for the AGENTS.md
 // PAN section and the CLAUDE.md @AGENTS.md bridge. They live under
@@ -16,6 +20,30 @@
 
 const PAN_AGENTS_BEGIN = '<!-- BEGIN PAN WIZARD -->';
 const PAN_AGENTS_END = '<!-- END PAN WIZARD -->';
+const crypto = require('crypto');
+
+// What earlier releases generated between the markers, by sha256 (first 16 hex) of the
+// text with LF line endings, trimmed. Taken from the builders at every commit that
+// changed them. A section with any other text was written by the project.
+const PRIOR_AGENTS_SECTIONS = Object.freeze([
+  'a92a7488b866611d', // to 2026-10-03: "PAN commands install as pan-* skills/commands"
+  'c66f9afd44d80489', // 2026-10-03 to 2026-10-21: commands named per runtime (M34)
+]);
+const PRIOR_CLAUDE_BRIDGES = Object.freeze([
+  '918b1c90559355ef', // the @AGENTS.md import alone
+  '90d0654c91061ec1', // the import and compact instructions (O8), to 2026-10-21
+]);
+
+const innerHash = (text) => crypto.createHash('sha256').update(String(text).replace(/\r\n/g, '\n').trim()).digest('hex').slice(0, 16);
+
+/** The text between PAN's markers, or null when the markers are absent. */
+function fencedInner(existing) {
+  if (!existing) return null;
+  const b = existing.indexOf(PAN_AGENTS_BEGIN);
+  const e = existing.indexOf(PAN_AGENTS_END);
+  if (b === -1 || e === -1 || e < b) return null;
+  return existing.slice(b + PAN_AGENTS_BEGIN.length, e);
+}
 
 /**
  * Build the PAN section for AGENTS.md (marker-fenced, runtime-neutral).
@@ -28,7 +56,7 @@ function buildAgentsMdSection() {
     '',
     'This project uses PAN Wizard for structured, phase-based planning and execution.',
     '',
-    '- `.planning/` is PAN\'s state directory (state.md, roadmap.md, phase directories). Treat it as the source of truth for planning state and modify it through PAN commands, not by hand.',
+    '- When this project plans with PAN, `.planning/` holds that state (state.md, roadmap.md, phase directories): change it through PAN commands, not by hand. Where this project keeps its work elsewhere, its own instructions say so and win.',
     // One section serves every runtime in the project, so it names each one's form
     // (the README's list); `/pan-help` alone sent Claude Code users to a command
     // that does not exist there (prompt audit, market-ideas M34).
@@ -38,11 +66,27 @@ function buildAgentsMdSection() {
   ].join('\n');
 }
 
+/**
+ * Whose text sits between PAN's markers: 'absent' (no markers), 'pan' (this release's
+ * text or an earlier release's), or 'edited' (the project changed it).
+ * @param {string|null} existing - AGENTS.md (or CLAUDE.md) content
+ * @param {'agents'|'claude'} [kind]
+ */
+function sectionState(existing, kind = 'agents') {
+  const inner = fencedInner(existing);
+  if (inner === null) return 'absent';
+  const known = kind === 'claude'
+    ? [...PRIOR_CLAUDE_BRIDGES, innerHash(fencedInner(buildClaudeMdBridge()))]
+    : [...PRIOR_AGENTS_SECTIONS, innerHash(fencedInner(buildAgentsMdSection()))];
+  return known.includes(innerHash(inner)) ? 'pan' : 'edited';
+}
+
 /**
  * Insert or replace the PAN section in AGENTS.md content.
  * - No existing content (null/empty) → just the section.
- * - Markers present → replace exactly the fenced block, preserving everything
- *   around it.
+ * - Markers present around text PAN generated → replace exactly the fenced block,
+ *   preserving everything around it.
+ * - Markers present around text the project edited → return the content unchanged.
  * - Markers absent → append with a separating blank line.
  * @param {string|null} existing - Current AGENTS.md content, or null if absent
  * @param {string} section - Output of buildAgentsMdSection()
@@ -55,6 +99,7 @@ function upsertAgentsMdSection(existing, section) {
   const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
   const endIdx = existing.indexOf(PAN_AGENTS_END);
   if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    if (sectionState(existing, 'agents') === 'edited') return existing;
     const before = existing.slice(0, beginIdx);
     const after = existing.slice(endIdx + PAN_AGENTS_END.length);
     return before + section + after;
@@ -101,8 +146,8 @@ function buildClaudeMdBridge() {
     '# Compact instructions',
     '',
     'When this conversation is compacted, keep what PAN work needs to resume where it stopped:',
-    '- the current phase and plan, and the task in progress with its stopping point (`.planning/state.md` records them; keep that path);',
-    '- decisions made in this session that `.planning/state.md` does not yet hold;',
+    '- the current phase and plan, and the task in progress with its stopping point, with the path of the file that records them (`.planning/state.md` when the project keeps one);',
+    '- decisions made in this session that are not yet written down;',
     '- the files changed since the last commit.',
     'Leave out file contents and command output: they can be read again.',
     PAN_AGENTS_END,
@@ -126,8 +171,9 @@ function ensureClaudeMdImport(existing) {
   const beginIdx = existing.indexOf(PAN_AGENTS_BEGIN);
   const endIdx = existing.indexOf(PAN_AGENTS_END);
   if (beginIdx !== -1) {
-    // PAN's own bridge: bring it up to date. Any other PAN block is left alone.
-    if (endIdx > beginIdx && /^@AGENTS\.md\s*$/m.test(existing.slice(beginIdx, endIdx))) {
+    // PAN's own bridge, as some release generated it: bring it up to date. A block the
+    // project edited, or any other PAN block, is left alone.
+    if (endIdx > beginIdx && sectionState(existing, 'claude') === 'pan') {
       const eol = existing.includes('\r\n') ? '\r\n' : '\n';
       return existing.slice(0, beginIdx) + block.replace(/\n/g, eol) + existing.slice(endIdx + PAN_AGENTS_END.length);
     }
@@ -150,6 +196,9 @@ function removeClaudeMdImport(existing) {
 }
 
 module.exports = {
+  sectionState,
+  PRIOR_AGENTS_SECTIONS,
+  PRIOR_CLAUDE_BRIDGES,
   PAN_AGENTS_BEGIN,
   PAN_AGENTS_END,
   buildAgentsMdSection,