Implement PlanAnvil skill

.agents/skills/plan-anvil/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: plan-anvil
+description: Generate and validate a rigorous, test-driven implementation plan in an isolated Git worktree. Use only when explicitly invoked as $plan-anvil. Never implement or execute the generated plan.
+---
+
+# PlanAnvil
+
+Create an auditable implementation contract, commit planning artifacts only, report the result, and stop.
+
+## Boundary
+
+- Never modify product code or product tests.
+- Never execute a generated stage or start the later executor.
+- Never stash, reset, clean, deploy, migrate, restart services, switch a live system, or push or merge the base branch.
+- Keep the source worktree unchanged. Treat canonical files and Git as durable state, not conversation memory.
+- Do not continue into implementation after approval in the same run.
+
+## Workflow
+
+1. Read every applicable repository instruction and `references/lifecycle.md`. Current official Codex documentation has higher authority than bundled references.
+2. Start the deterministic bootstrap controller:
+
+   ```text
+   python .agents/skills/plan-anvil/scripts/plan_anvil.py start \
+     --source "$PWD" \
+     --goal "<exact user goal>" \
+     --codex-version "<actual or unknown>" \
+     --model "<actual or unknown>" \
+     --permission-mode "<actual or unknown>" \
+     --project-trust <TRUSTED|UNTRUSTED|UNKNOWN> \
+     --hook-mode <HOOKS_TRUSTED|HOOKS_DISABLED|HOOKS_UNTRUSTED|HOOKS_UNAVAILABLE>
+   ```
+
+   This performs read-only preflight, a real reversible Git ref/branch/worktree/index/commit probe, planning-worktree isolation, profiling, run scaffolding, and durable bootstrap evidence. On any non-ready result, preserve evidence, report the exact blocker, and stop.
+3. Continue only in the returned planning worktree and run root. Fully read and hash all applicable instruction files, resolve their scope and precedence, and write the instruction map with `map_instructions.py`. A remaining critical conflict blocks the run.
+4. Analyze the goal from repository evidence. Record immutable `evidence/analysis.md` and `.json` with `record_analysis.py`. A critical unknown blocks readiness; non-critical ambiguity requires an evidence-backed interpretation and verification method.
+5. Using the templates and references, author `PLAN.md`, stable stage briefs, acceptance criteria, risks, controls, rollback, recovery, approvals, and complete traceability. Write requirements for a separate later execution run, not executable product changes. Seal the contract with `seal_artifacts.py`.
+6. Run `validate_all.py --phase pre-review`. Do not proceed unless profiles, schemas, privacy, source immutability, instruction coverage, plan structure, traceability, risks, and the planning-branch diff all pass.
+7. Build the immutable review bundle with `prepare_review_bundle.py`. Dispatch a fresh read-only reviewer without planner reasoning, record its single blind result with `record_blind_review.py`, then run `compare_review.py`. Any failed or stale review blocks readiness.
+8. Run `commit_plan.py`. It repeats the final gates, writes the final report, commits only allowlisted planning/control artifacts, preserves the source worktree, and never pushes.
+9. Report status, planning branch, commit SHA, plan path, assumptions, unknowns, review result, and the separate execution-run prompt. State: `No implementation was executed. Start a separate Codex run using the execution prompt in PLAN.md.` Then stop.
+
+## Decision policy
+
+Ask the user only when the unresolved decision materially changes business scope, public behavior, architecture, irreversible behavior, security/privacy/legal policy, live switching, base integration, or critical acceptance and rollback evidence. Derive and record all other implementation-planning decisions from the strongest available evidence.
+
+## References
+
+- `references/lifecycle.md` — state order, Git isolation, ownership, and blockers
+- `references/plan-contract.md` — required plan and stage content
+- `references/artifact-contract.md` — canonical state, schemas, privacy, and path safety
+- `references/review-and-stop.md` — validation, blind review, commit, and hard stop
+- `references/execution-contract.md` — contract for the separate later implementation run

.agents/skills/plan-anvil/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "PlanAnvil"
+  short_description: "Generate a validated implementation plan without executing it"
+  default_prompt: "Use $plan-anvil to generate and validate an implementation plan for this goal. Do not implement the plan."
+policy:
+  allow_implicit_invocation: false

.agents/skills/plan-anvil/references/artifact-contract.md

@@ -0,0 +1,38 @@
+# Artifact contract
+
+## Run layout
+
+`.pursue/runs/<TIMESTAMP>_<PLAN-ID>_<SLUG>/` contains `PLAN.md`, `manifest.json`, `state.json`, `compliance.json`, `traceability.json`, ignored `local-state.json`, and the `stages`, `checkpoints`, `reports`, `risks`, `evidence`, `diffs`, `logs`, `incidents`, and `final` directories.
+
+Canonical machine state is JSON. Markdown is human-readable and never overrides JSON. Bootstrap evidence includes `evidence/git-capability.json` and `evidence/lifecycle.json`; goal analysis uses immutable `evidence/analysis.md` and `.json`.
+
+## Canonical conventions
+
+- UTF-8, LF, sorted keys, two-space indentation, terminal newline
+- schema version `1.1.0`
+- RFC 3339 UTC timestamps
+- SHA-256 values prefixed with `sha256:`
+- unknown fields rejected unless explicitly allowed
+- atomic replacement for mutable state
+- monotonic `state.json.revision`
+- exactly one `next_action`
+- immutable checkpoints and blind-review artifacts
+
+## Privacy
+
+Committed artifacts must not contain absolute local paths, usernames, machine-specific services, credentials, private keys, cookies, copied `.env` data, or private repository URLs.
+
+Machine-specific locators belong only in ignored:
+
+- `.pursue/SYSTEM_PROFILE.local.md`
+- `.pursue/runs/<RUN-ID>/local-state.json`
+
+Validators must prove these files are ignored and untracked.
+
+## Path safety
+
+Resolve every write, reject traversal, symlink escapes, `.git` writes outside dedicated Git commands, case-insensitive escapes, and submodule writes not explicitly in scope. Match allowlists using repository-relative POSIX paths.
+
+## Goal analysis
+
+`evidence/analysis.md` and `evidence/analysis.json` are immutable analysis inputs. The JSON records the goal hash, classification, risk, affected paths, evidence, assumptions, unknowns, and Markdown hash. A critical unknown transitions the run to `BLOCKED_BY_CRITICAL_UNKNOWN`.

.agents/skills/plan-anvil/references/execution-contract.md

@@ -0,0 +1,33 @@
+# Separate execution-run contract
+
+These rules are written into the generated plan; they are never started by PlanAnvil.
+
+## Roles and topology
+
+The later executor uses a flat direct-child topology: Jim coordinates, Jenny owns approved tests only, one implementation agent modifies approved product paths, an independent verifier remains read-only, and Winston Wolfe performs read-only incident analysis only after six exhausted implementation attempts.
+
+Jim never modifies product code or tests. Jenny never modifies production code. Only one agent modifies repository files at a time.
+
+## Evidence cycle
+
+Behavior-changing stages use:
+
+`GREEN BASELINE → EXPECTED RED → IMPLEMENTATION → FULL GREEN → INDEPENDENT VERIFICATION`
+
+The red result must fail for the intended behavioral reason. Non-behavior stages use an equivalent evidence cycle.
+
+## Retry model
+
+Use three attempts for one strategy, then three attempts for a materially different strategy. Preserve failed-attempt evidence. After six failures, run read-only incident analysis and stop with `BLOCKED_BY_UNRESOLVED_FAILURE`.
+
+## Git and control ownership
+
+Task branch: `pursue/<PLAN-ID>/<slug>`. Integration branch: `pursue/integration/<PLAN-ID>/<slug>`.
+
+Control state, reports, checkpoints, and evidence stay in the retained planning worktree. Product code and tests change only in task or integration worktrees. Each completed stage ends in one coherent implementation-and-test commit.
+
+Never automatically push or merge the base branch. Require explicit approval before live switching, irreversible operations, or base integration.
+
+## Stateful changes
+
+Use discover, recovery point, expand, migrate, switch, observe, and a separate later contraction. Require resumability, integrity checks, compatibility, rollback evidence, and explicit approval for irreversible steps.

.agents/skills/plan-anvil/references/lifecycle.md

@@ -0,0 +1,36 @@
+# Generator lifecycle
+
+Authority order: current official OpenAI Codex documentation, `docs/IMPLEMENTATION_SPEC.md`, architecture, artifact schemas, compliance record, capability baseline, examples.
+
+## Mandatory state order
+
+`SOURCE_PREFLIGHT → GIT_CAPABILITY_CHECK → CREATE_PLANNING_BRANCH_AND_WORKTREE → CREATE_OR_VALIDATE_PROFILES → DISCOVER_INSTRUCTIONS → ANALYZE_GOAL → GENERATE_ARTIFACTS → DETERMINISTIC_VALIDATION → BLIND_PLAN_REVIEW → COMPARISON_AND_FINAL_VALIDATION → COMMIT_PLANNING_ARTIFACTS → REPORT_AND_STOP`
+
+No state may be skipped. Bootstrap transitions are preserved in `evidence/lifecycle.json`; the complete successful Git probe is preserved in `evidence/git-capability.json`. Both are schema-validated and hashed into canonical state before instruction mapping.
+
+## Source preflight
+
+The source worktree is read-only. Verify Git, repository root, `HEAD`, cleanliness, conflicts, active Git operations, branch/base identity, and linked worktrees. Preflight must not create files, refs, branches, commits, or repository-local temporary directories.
+
+## Git capability probe
+
+Use an external temporary directory and unique probe names. Verify temporary refs, a branch, linked worktree, file creation, index update, a real commit under current identity/signing/hooks policy, cleanup, and unchanged source branch, `HEAD`, index, and files.
+
+A commit check is mandatory for `GIT_READY`. Return a precise blocker for identity, signing, hooks, permissions, worktree support, dirty state, active operations, or ambiguous detached `HEAD`.
+
+## Planning isolation
+
+Create `pursue/plan/<PLAN-ID>/<slug>` from the verified base and retain an external linked planning worktree. The source remains unchanged. All profiles and run artifacts are created only after this worktree exists.
+
+The planning worktree is the durable control root. It may contain only `.pursue/SYSTEM_PROFILE.md`, required ignore rules, generated plan/control/evidence artifacts, and plan-specific documentation. Product implementation and product tests are forbidden.
+
+## Blocking statuses
+
+- `BLOCKED_BY_GIT_STATE`
+- `BLOCKED_BY_GIT_PERMISSIONS`
+- `BLOCKED_BY_RUNTIME_PREREQUISITE`
+- `BLOCKED_BY_INSTRUCTION_CONFLICT`
+- `BLOCKED_BY_CRITICAL_UNKNOWN`
+- `PLAN_VALIDATION_FAILED`
+
+Preserve evidence and describe safe remediation. Never hide failures with destructive Git commands.

.agents/skills/plan-anvil/references/plan-contract.md

@@ -0,0 +1,33 @@
+# Plan and stage contract
+
+`PLAN.md` records stable decisions and guardrails. Stage briefs contain execution detail. Plans describe what must be true, not speculative full implementations.
+
+## PLAN.md required content
+
+- identity and contract versions;
+- original goal, outcome, and definition of done;
+- generator stop boundary;
+- separate execution-run prompt;
+- scope and exclusions;
+- assumptions, unknowns, confidence, and evidence;
+- applicable instructions and conflict resolutions;
+- system, component, data, and state-flow summaries;
+- dependencies and change classification;
+- stable stage index;
+- requirement → stage → criterion → risk → control/test → evidence traceability;
+- testing, Git, integration, production verification, rollback, recovery, resume, and approval rules;
+- status, exactly one next action, and final report requirements.
+
+Reject unsupported signatures, stale permanent line numbers, unverified deployment commands, placeholders, or instructions that continue implementation in the generator run.
+
+## Stage rules
+
+Each stage has a permanent ID such as `STAGE-03` or `STAGE-03A`, one outcome, scope, exclusions, affected paths or discovery procedure, `applicable_instructions` path/hash metadata, dependencies, conflicts, acceptance criteria, risks, controls, one modifier role at a time, independent verification, one coherent implementation commit, and one verified control checkpoint.
+
+Split stages across independent domains, unrelated responsibilities, distinct risks, criteria, deployments, or rollback boundaries.
+
+## Critical unknowns
+
+Block readiness when expected behavior, critical evidence, public API behavior, migration behavior, rollback, irreversible actions, security/permissions, or production switching cannot be safely defined.
+
+Every critical requirement must reach verifiable evidence. Any critical traceability gap blocks `PLAN_READY`.

.agents/skills/plan-anvil/references/review-and-stop.md

@@ -0,0 +1,25 @@
+# Validation, blind review, commit, and stop
+
+## Deterministic validation
+
+Before readiness, verify required files and schemas, canonical JSON, source-worktree immutability, planning-branch allowlist, ignored local state, instruction completeness, stable IDs, traceability, risk-control coverage, privacy, absence of placeholders, and agreement between JSON and Markdown.
+
+## Blind review
+
+Build a bundle containing only the original goal, bootstrap Git/lifecycle evidence, profiles, instruction map, immutable goal analysis, generated plan and stages, traceability, risks, and deterministic validator output.
+
+Use a fresh read-only reviewer. Do not provide planner reasoning or self-review. The reviewer must assess completeness, contradictions, unsupported assumptions, rollback, testing, approvals, generator/executor separation, and critical traceability gaps.
+
+Write `reports/plan-review/blind-review.md` and `.json` once. Hash both before comparison. Comparison writes separate output and never edits the blind review.
+
+## Commit gate
+
+Before commit, rerun profile, artifact, plan, diff, privacy, review, and comparison validation. Stage only allowlisted planning artifacts. Honor repository signing and hooks. Do not push unless separately requested and confirmed safe.
+
+## Final report and hard stop
+
+Report status, planning branch, commit SHA, plan path, assumptions, unknowns, review result, and the execution prompt.
+
+Use the explicit statement: `No implementation was executed. Start a separate Codex run using the execution prompt in PLAN.md.`
+
+Then stop.

.agents/skills/plan-anvil/schemas/analysis.schema.json

@@ -0,0 +1,140 @@
+{
+  "$defs": {
+    "hash": {
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "type": "string"
+    },
+    "relative_path": {
+      "minLength": 1,
+      "not": {
+        "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)|^(?:/|[A-Za-z]:[\\\\/]|\\\\\\\\)"
+      },
+      "type": "string"
+    },
+    "timestamp": {
+      "format": "date-time",
+      "type": "string"
+    }
+  },
+  "$id": "https://keyffms.github.io/PlanAnvil/schemas/analysis.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "affected_paths": {
+      "items": {
+        "$ref": "#/$defs/relative_path"
+      },
+      "minItems": 1,
+      "type": "array",
+      "uniqueItems": true
+    },
+    "assumptions": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "confidence": {
+            "enum": [
+              "VERIFIED",
+              "USER_CONFIRMED",
+              "INFERRED"
+            ]
+          },
+          "evidence": {
+            "items": {
+              "$ref": "#/$defs/relative_path"
+            },
+            "type": "array",
+            "uniqueItems": true
+          },
+          "text": {
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "text",
+          "confidence",
+          "evidence"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "classification": {
+      "enum": [
+        "ISOLATED",
+        "CROSS_COMPONENT",
+        "STATEFUL",
+        "PUBLIC_API",
+        "SECURITY",
+        "LIVE_OPERATION",
+        "DOCUMENTATION"
+      ]
+    },
+    "created_at": {
+      "$ref": "#/$defs/timestamp"
+    },
+    "evidence": {
+      "items": {
+        "$ref": "#/$defs/relative_path"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    "goal_hash": {
+      "$ref": "#/$defs/hash"
+    },
+    "markdown_hash": {
+      "$ref": "#/$defs/hash"
+    },
+    "risk": {
+      "enum": [
+        "LOW",
+        "MEDIUM",
+        "HIGH"
+      ]
+    },
+    "schema_version": {
+      "const": "1.1.0"
+    },
+    "unknowns": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "critical": {
+            "type": "boolean"
+          },
+          "text": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "verification": {
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "text",
+          "critical",
+          "verification"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "schema_version",
+    "created_at",
+    "goal_hash",
+    "markdown_hash",
+    "classification",
+    "risk",
+    "affected_paths",
+    "evidence",
+    "assumptions",
+    "unknowns"
+  ],
+  "title": "PlanAnvil goal analysis",
+  "type": "object"
+}