Plan-driven orchestration, atomic skills, review + grounding axes, diagrams

[bburda]

Summary

Large cleanup and capability expansion of Pharaoh skills, centred on making reverse-engineering (feat + comp_req from code) work end-to-end via declarative plans instead of prose orchestration. Adds 41 new atomic skills, a plan executor, a review/grounding axis set, a diagram view set, and finishes with a cross-cutting audit cleanup.

What's new

Plan-driven orchestration

• pharaoh-write-plan — template engine that renders a declarative plan.yaml from a named template (reverse-engineer-project, reverse-engineer-module). Plan is data, not prose.
• pharaoh-execute-plan — generic DAG executor that reads a plan.yaml and dispatches tasks in topological order, with inline, subagents, family-bundle, and ask execution modes, foreach expansion, typed refs (${task.field}), and a closed helper set. Schema specced in pharaoh-execute-plan/schema.md, including the explicit Outputs binding rules between skill output and downstream refs.
• Replaces the prose-orchestration skills that used to encode a 12-step flow the LLM had to read and execute. Composition skills deleted in favour of plan templates.

Atomic skills (41 new SKILL.md files)

Most new emission and review skills declare explicit (a)-(e) atomicity criteria (indivisible, typed I/O, reward-testable, reusable, composable); pre-existing composition / orchestration skills (e.g. pharaoh-plan, pharaoh-mece, pharaoh-spec) inherit a more flexible contract since the (a)-(e) shape is a design gate for atoms, not for orchestrators. Highlights:

• Feat drafting: pharaoh-feat-draft-from-docs, pharaoh-feat-file-map, pharaoh-feat-component-extract, pharaoh-feat-flow-extract, pharaoh-feat-balance, pharaoh-feat-review.
• ID / convention: pharaoh-id-allocate, pharaoh-id-convention-check.
• Req emission + review: pharaoh-req-from-code, pharaoh-req-codelink-annotate, pharaoh-req-code-grounding-check, pharaoh-api-coverage-check.
• Diagrams: one shipped per-view drafter (pharaoh-use-case-diagram-draft) plus eight design-only scaffolds (sequence, component, class, state, activity, block, deployment, fault-tree) whose description: declares Status — PLANNED. Component and flow views are emitted directly from code by pharaoh-feat-component-extract and pharaoh-feat-flow-extract. Diagram tooling: pharaoh-diagram-lint, pharaoh-diagram-review.
• Review infrastructure: pharaoh-decision-review, pharaoh-fmea-review, and the self-review invariant wired through every emission skill.
• Gate checks: pharaoh-quality-gate plus delegated atoms (pharaoh-self-review-coverage-check, pharaoh-dispatch-signal-check, pharaoh-papyrus-non-empty-check, pharaoh-link-completeness-check, pharaoh-status-lifecycle-check, pharaoh-reproducibility-check).
• Tailoring: pharaoh-tailor-bootstrap (zero-to-tailored scaffolding from ubproject.toml) and pharaoh-tailor-code-grounding-filters (language-specific filter generation).
• Output contracts: pharaoh-output-validate enforces named schemas; pharaoh-toctree-emit wires emitted RST into the Sphinx tree.

Review / grounding axis set

• Added ISO 26262 Part 8 §6 -aligned axes to pharaoh-req-review — 4 mechanized binary axes (atomicity, internal consistency, verifiability, schema) and 3 subjective 0-3 axes (unambiguity, comprehensibility, feasibility). Set-level axes (completeness, external consistency, no duplication) and the chain-level axis (maintainability) are recorded as deferred / null with reasoning.
• pharaoh-req-code-grounding-check scores CREQs against their cited source: exception raise sites, trigger conditions, named-symbol existence, type-framework imports, backtick-symbol presence, weasel-adjective absence, quantifier enumeration, source_doc resolution, and branch-count alignment. Pluggable language-specific filters via code-grounding-filters.yaml + the tailoring skill.
• verification placeholder pathway: status: draft + :verification: matching ^(tc|test_case)__TBD$ now scores 0.5 instead of 0, letting the regenerate loop terminate on iteratively improved drafts.

Shall-clause discipline

pharaoh-req-from-code ships seven rules governing the CREQ body:

1. Subject is the component (or an external actor at an interface boundary) — never a function, class, or file.
2. No internal implementation details in the body — no private names, file paths, or line numbers.
3. :source_doc: must point at real source code, not at the spec RST.
4. Every CREQ adds a constraint beyond its parent feat (no tautologies).
5. Enumerate boundary-observable structures exhaustively; one shall per body, no intra-clause conjunctions.
6. :verification: is always present (placeholder tc__TBD acceptable).
7. Backticks are reserved for code / protocol tokens — a whitelist of external-surface identifiers (CLI flags, env vars, TOML keys, HTTP routes, protocol tokens).

Diagram view set

• One shipped per-view drafter (pharaoh-use-case-diagram-draft) plus eight design-only scaffolds for the remaining UML / SysML views. Scaffolds carry Status — PLANNED in their frontmatter and a sentinel-FAIL implementation contract; they exist as design contracts and reward fixtures so the implementation can land later without bikeshedding the spec.
• pharaoh-diagram-lint runs every emitted diagram through the configured renderer (Mermaid or PlantUML) before the build passes, catching parse bugs that sphinx-build would wave through as opaque literals.
• pharaoh-diagram-review checks mechanized + subjective axes: trace-to-parent, element-count threshold, naming clarity, renderer-preference alignment.
• shared/diagram-safe-labels.md documents label-escaping rules; shared/uml-relationship-semantics.md canonicalises arrow semantics.

Tailoring + bootstrap

• pharaoh-bootstrap was updated for sphinx-needs 8.x TOML format, mode-aware defaults, and a sane .gitignore preset.
• pharaoh-tailor-bootstrap scaffolds .pharaoh/project/{workflows,id-conventions,artefact-catalog}.yaml + per-type checklists from the project's declared [[needs.types]]. Emits a canonical checklists/requirement.md alias so downstream review skills can load by well-known filename regardless of project-specific directive naming.
• pharaoh-gate-advisor walks projects up the strictness ladder in value-cost order, avoiding the "flip strictness first, enable gates later" trap.

Self-review invariant

Every emission skill ends with a ## Last step — typically a review-atom invocation matching the artefact (pharaoh-feat-review, pharaoh-req-review, pharaoh-arch-review, etc.). Skills with no matching review atom (pharaoh-req-codelink-annotate, pharaoh-toctree-emit — both structural one-shot operations) document an inline structural self-verification + delegate set-level coverage to pharaoh-quality-gate invariants. pharaoh-self-review-coverage-check (called from pharaoh-quality-gate) verifies that every draft has a review before the gate passes. Covers the "LLM skipped the review to save tokens" failure class.

Plan schema + template correctness

• execution_mode canonicalised to {inline, subagents, family-bundle, ask} everywhere; earlier parallel_agents references (never a valid schema mode) cleaned up.
• Closed helper set in the ref grammar: flatten, to_papyrus_seeds, to_files_flat, to_id_requests, by_stem, with_entry_point, unique, keys, heuristics.split_strategy. Unknown helpers fail static validation.
• foreach: is always a scalar ref. Templates iterate over structured task outputs (${reqs_from_code.reqs | flatten}, ${draft_feats.feats}) instead of phantom emitted_ids fields; pharaoh-feat-draft-from-docs and pharaoh-req-from-code now emit JSON {feats: [...]} / {reqs: [...]} so downstream refs resolve cleanly.
• Schema explicitly documents Outputs binding: how expected_output_schema parses skill output and populates fields named in the task's outputs: declaration.

Audit cleanup

• Consolidated duplicated rule sections (req-from-code shall-clause rules), dropped a deprecated axis (minimum_grounding_density) that had driven a Goodhart failure mode toward code-narration, renumbered remaining axes.
• Stripped domain-specific identifiers from prose; fixtures and worked examples retain a recurring third-party example for narrative consistency (Jama is the most-used placeholder name across pharaoh-api-coverage-check / pharaoh-toctree-emit / pharaoh-diagram-review fixtures).
• Diagram-drafter PLANNED status now lives in each skill's description: frontmatter so skill-discovery surfaces design-only stubs honestly without requiring a separate index.
• Created shared/tailoring-access.md documenting the canonical tailoring-file resolution order, closing dead cross-refs in several draft skills.
• Renamed the map_path invariant key to self_review_map_path to match the delegated skill's input contract.
• pharaoh-id-allocate cap aligned with format: seq ranges 01..99 (3-digit 100 would break the :02d zero-pad).

Verification

• Every ${...} ref in both plan templates uses only helpers in skills/pharaoh-execute-plan/schema.md.
• Every skill: reference in plan templates resolves to a real skills/<name>/ directory.
• Every foreach: in both plan templates is a scalar ref.
• Every axis reference by number resolves to a correctly numbered axis in the target skill.
• Both plan templates Jinja-render and YAML-parse cleanly; the rewired ${task.field | flatten} patterns satisfy the schema's foreach-shape rules.

Test plan

• Markdown-only repo — no Python tests. Correctness enforced by the skill-level reward fixtures in each SKILL.md's atomicity (c) criterion.
• Cross-reference check: every [link](../path.md) between skills resolves.
• Helper + skill ref audit on the plan templates.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR refactors Pharaoh toward plan-driven orchestration and expands the atomic-skill ecosystem with new review/grounding checks, diagram tooling, and extensive reward fixtures to validate the new behaviors.

Changes:

• Add new atomic skills and fixtures for tailoring, validation/gates (status lifecycle, self-review coverage, reproducibility, link completeness, output validation, API coverage), and diagram review.
• Update multiple emission skills to enforce the “self-review invariant” via ## Last step review invocations.
• Remove legacy prose/composition orchestration (pharaoh-reqs-from-module) in favor of plan/template execution patterns.

Reviewed changes

Copilot reviewed 300 out of 329 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-typer/src/env.py	Adds Python fixture source to trigger env-var prefix detection.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-typer/src/cli.py	Adds Typer + dataclass fixture source to drive filter tailoring.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-typer/expected-report.json	Defines expected tailoring detection report for Typer fixture.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-typer/expected-filters.yaml	Defines expected emitted code-grounding filter set for Typer fixture.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-typer/README.md	Documents fixture intent/coverage for tailoring skill.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-click-click/src/cli.py	Adds Click fixture source to contrast framework-specific behavior.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-click-click/expected-report.json	Defines expected detection report for Click fixture.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-click-click/expected-filters.yaml	Defines expected emitted filter set for Click fixture.
skills/pharaoh-tailor-code-grounding-filters/fixtures/python-click-click/README.md	Documents Click fixture goals.
skills/pharaoh-status-lifecycle-check/fixtures/mixed-enforcing/input-workflows.yaml	Adds lifecycle workflow fixture input (mixed statuses, enforcing).
skills/pharaoh-status-lifecycle-check/fixtures/mixed-enforcing/input-needs.json	Adds needs graph fixture input (mixed statuses, enforcing).
skills/pharaoh-status-lifecycle-check/fixtures/mixed-enforcing/expected-output.json	Expected enforcing failure output for mixed statuses.
skills/pharaoh-status-lifecycle-check/fixtures/mixed-enforcing/README.md	Documents enforcing mixed-status case.
skills/pharaoh-status-lifecycle-check/fixtures/fully-reviewed-enforcing/input-workflows.yaml	Adds workflow fixture input for enforcing pass case.
skills/pharaoh-status-lifecycle-check/fixtures/fully-reviewed-enforcing/input-needs.json	Adds needs fixture input (no drafts).
skills/pharaoh-status-lifecycle-check/fixtures/fully-reviewed-enforcing/expected-output.json	Expected enforcing pass output.
skills/pharaoh-status-lifecycle-check/fixtures/fully-reviewed-enforcing/README.md	Documents enforcing pass semantics (past-draft sufficient).
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-enforcing/input-workflows.yaml	Adds workflow fixture input for all-draft enforcing fail.
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-enforcing/input-needs.json	Adds needs fixture input (all draft).
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-enforcing/expected-output.json	Expected enforcing failure output with blockers enumerated.
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-enforcing/README.md	Documents all-draft enforcing behavior.
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-advisory/input-workflows.yaml	Adds workflow fixture input for advisory mode.
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-advisory/input-needs.json	Adds needs fixture input for advisory mode.
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-advisory/expected-output.json	Expected advisory pass output with informational blocker line.
skills/pharaoh-status-lifecycle-check/fixtures/all-draft-advisory/README.md	Documents advisory mode semantics.
skills/pharaoh-standard-conformance/SKILL.md	Updates built-in default profile wording and required field defaults.
skills/pharaoh-self-review-coverage-check/fixtures/scalar-mapped/input-skill.md	Adds fixture for scalar map backward-compat behavior.
skills/pharaoh-self-review-coverage-check/fixtures/scalar-mapped/input-map.yaml	Adds scalar-valued self-review map fixture input.
skills/pharaoh-self-review-coverage-check/fixtures/scalar-mapped/expected-output.json	Expected pass output for scalar map case.
skills/pharaoh-self-review-coverage-check/fixtures/scalar-mapped/README.md	Documents scalar-map regression protection.
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-partial/input-skill.md	Adds fixture for list-valued map partial invocation failure.
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-partial/input-map.yaml	Adds list-valued self-review map fixture input.
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-partial/expected-output.json	Expected fail output for missing mapped review invocation.
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-partial/README.md	Documents failure path for list-valued mapping.
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-complete/input-skill.md	Adds fixture for list-valued map complete invocation pass.
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-complete/input-map.yaml	Adds list-valued mapping fixture input (complete).
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-complete/expected-output.json	Expected pass output for complete list-valued mapping.
skills/pharaoh-self-review-coverage-check/fixtures/list-mapped-complete/README.md	Documents list-valued mapping success path.
skills/pharaoh-review-completeness/SKILL.md	Removes Score-specific fallback path reference.
skills/pharaoh-reqs-from-module/SKILL.md	Removes legacy composition skill in favor of plan templates.
skills/pharaoh-req-regenerate/SKILL.md	Updates default-tailoring wording and verifiability placeholder behavior.
skills/pharaoh-req-draft/SKILL.md	Adds internal-symbol exclusion checks and self-review “Last step”.
skills/pharaoh-req-code-grounding-check/fixtures/weasel-adjectives/input-source.py	Adds grounding-check fixture source for weasel-adjective detection.
skills/pharaoh-req-code-grounding-check/fixtures/weasel-adjectives/input-creq.rst	Adds CREQ fixture containing weasel adjectives.
skills/pharaoh-req-code-grounding-check/fixtures/weasel-adjectives/expected-output.json	Expected fail output for weasel-adjective axis.
skills/pharaoh-req-code-grounding-check/fixtures/weasel-adjectives/README.md	Documents weasel-adjective failure pattern.
skills/pharaoh-req-code-grounding-check/fixtures/unbounded-all/input-source.py	Adds grounding-check fixture source for unbounded quantifier.
skills/pharaoh-req-code-grounding-check/fixtures/unbounded-all/input-creq.rst	Adds CREQ fixture with “all …” quantifier without enumeration.
skills/pharaoh-req-code-grounding-check/fixtures/unbounded-all/expected-output.json	Expected fail output for quantifier enumeration axis.
skills/pharaoh-req-code-grounding-check/fixtures/unbounded-all/README.md	Documents unbounded-quantifier failure pattern.
skills/pharaoh-req-code-grounding-check/fixtures/typer-kebab-filter/input-source.py	Adds fixture source for Typer kebab flag mapping.
skills/pharaoh-req-code-grounding-check/fixtures/typer-kebab-filter/input-creq.rst	Adds CREQ citing kebab flags.
skills/pharaoh-req-code-grounding-check/fixtures/typer-kebab-filter/expected-output.json	Expected pass output validating kebab filter resolution.
skills/pharaoh-req-code-grounding-check/fixtures/typer-kebab-filter/code-grounding-filters.yaml	Supplies tailored filter config for the fixture.
skills/pharaoh-req-code-grounding-check/fixtures/typer-kebab-filter/README.md	Documents filter-step exercise for kebab conversion.
skills/pharaoh-req-code-grounding-check/fixtures/toml-section-filter/input-source.py	Adds fixture source for TOML section token skipping.
skills/pharaoh-req-code-grounding-check/fixtures/toml-section-filter/input-creq.rst	Adds CREQ citing TOML section header token.
skills/pharaoh-req-code-grounding-check/fixtures/toml-section-filter/expected-output.json	Expected pass output with TOML-section filter.
skills/pharaoh-req-code-grounding-check/fixtures/toml-section-filter/README.md	Documents TOML-section filter rationale.
skills/pharaoh-req-code-grounding-check/fixtures/pydantic-halluc/input-source.py	Adds fixture source to detect type-framework mismatch.
skills/pharaoh-req-code-grounding-check/fixtures/pydantic-halluc/input-creq.rst	Adds CREQ claiming Pydantic where source is dataclass.
skills/pharaoh-req-code-grounding-check/fixtures/pydantic-halluc/expected-output.json	Expected fail output for type-framework mismatch axis.
skills/pharaoh-req-code-grounding-check/fixtures/pydantic-halluc/README.md	Documents hallucinated framework failure mode.
skills/pharaoh-req-code-grounding-check/fixtures/passing-case/input-source.py	Adds canonical passing grounding fixture source.
skills/pharaoh-req-code-grounding-check/fixtures/passing-case/input-creq.rst	Adds canonical passing CREQ.
skills/pharaoh-req-code-grounding-check/fixtures/passing-case/expected-output.json	Expected passing output for all mechanical axes.
skills/pharaoh-req-code-grounding-check/fixtures/passing-case/README.md	Documents passing case expectations.
skills/pharaoh-req-code-grounding-check/fixtures/misattributed-config-field/input-source.py	Adds consumer-vs-config misattribution fixture source.
skills/pharaoh-req-code-grounding-check/fixtures/misattributed-config-field/input-creq.rst	Adds CREQ citing config defaults/mismatched tokens.
skills/pharaoh-req-code-grounding-check/fixtures/misattributed-config-field/expected-output.json	Expected fail output with actionable retarget guidance.
skills/pharaoh-req-code-grounding-check/fixtures/misattributed-config-field/config/export_config.py	Adds config module source referenced by filter strategy.
skills/pharaoh-req-code-grounding-check/fixtures/misattributed-config-field/code-grounding-filters.yaml	Tailors cross-file literal-default filter for fixture.
skills/pharaoh-req-code-grounding-check/fixtures/misattributed-config-field/README.md	Documents cross-file leak failure mode.
skills/pharaoh-req-code-grounding-check/fixtures/inverted-trigger/input-source.py	Adds fixture source for inverted trigger condition detection.
skills/pharaoh-req-code-grounding-check/fixtures/inverted-trigger/input-creq.rst	Adds CREQ asserting incorrect trigger literal/operator.
skills/pharaoh-req-code-grounding-check/fixtures/inverted-trigger/expected-output.json	Expected fail output highlighting trigger divergence.
skills/pharaoh-req-code-grounding-check/fixtures/inverted-trigger/README.md	Documents inverted-trigger failure mode.
skills/pharaoh-req-code-grounding-check/fixtures/external-dotted-path/input-source.py	Adds fixture source for external dotted import path token resolution.
skills/pharaoh-req-code-grounding-check/fixtures/external-dotted-path/input-creq.rst	Adds CREQ citing third-party dotted path token.
skills/pharaoh-req-code-grounding-check/fixtures/external-dotted-path/expected-output.json	Expected pass output with dotted-import resolution filter.
skills/pharaoh-req-code-grounding-check/fixtures/external-dotted-path/code-grounding-filters.yaml	Tailors dotted-import resolution filter.
skills/pharaoh-req-code-grounding-check/fixtures/external-dotted-path/README.md	Documents dotted-path filter semantics.
skills/pharaoh-req-code-grounding-check/fixtures/env-var-glob/input-source.py	Adds fixture source for env-var glob expansion.
skills/pharaoh-req-code-grounding-check/fixtures/env-var-glob/input-creq.rst	Adds CREQ citing env-var glob token.
skills/pharaoh-req-code-grounding-check/fixtures/env-var-glob/expected-output.json	Expected pass output with env-var glob filter.
skills/pharaoh-req-code-grounding-check/fixtures/env-var-glob/code-grounding-filters.yaml	Supplies env-var glob filter config.
skills/pharaoh-req-code-grounding-check/fixtures/env-var-glob/README.md	Documents env-var glob false-positive avoidance.
skills/pharaoh-req-code-grounding-check/fixtures/dead-exception/input-source.py	Adds fixture source for “declared but never raised” exceptions.
skills/pharaoh-req-code-grounding-check/fixtures/dead-exception/input-creq.rst	Adds CREQ claiming raises for dead exceptions.
skills/pharaoh-req-code-grounding-check/fixtures/dead-exception/expected-output.json	Expected fail output for missing raise sites.
skills/pharaoh-req-code-grounding-check/fixtures/dead-exception/README.md	Documents dead-class exception mismatch.
skills/pharaoh-req-code-grounding-check/fixtures/collapsed-branches/input-source.py	Adds fixture source with multiple observable branches.
skills/pharaoh-req-code-grounding-check/fixtures/collapsed-branches/input-creq.rst	Adds CREQ covering only success path.
skills/pharaoh-req-code-grounding-check/fixtures/collapsed-branches/expected-output.json	Expected fail output for branch-count alignment axis.
skills/pharaoh-req-code-grounding-check/fixtures/collapsed-branches/README.md	Documents subjective branch alignment failure.
skills/pharaoh-req-code-grounding-check/fixtures/abstract-prose/input-source.py	Adds fixture source for “too abstract to verify” case.
skills/pharaoh-req-code-grounding-check/fixtures/abstract-prose/input-creq.rst	Adds abstract-prose CREQ fixture.
skills/pharaoh-req-code-grounding-check/fixtures/abstract-prose/expected-output.json	Expected fail output (source_doc_resolves + branch alignment).
skills/pharaoh-req-code-grounding-check/fixtures/abstract-prose/README.md	Documents abstract-prose regression guard.
skills/pharaoh-reproducibility-check/fixtures/identical-output/rerun/needs.json	Adds reproducibility baseline/rerun fixture needs.json (rerun).
skills/pharaoh-reproducibility-check/fixtures/identical-output/rerun/module.rst	Adds reproducibility rerun module RST.
skills/pharaoh-reproducibility-check/fixtures/identical-output/input-mask-rules.yaml	Adds mask rules fixture input for timestamp masking.
skills/pharaoh-reproducibility-check/fixtures/identical-output/expected-output.json	Expected pass output for identical-after-masking case.
skills/pharaoh-reproducibility-check/fixtures/identical-output/baseline/needs.json	Adds reproducibility baseline needs.json.
skills/pharaoh-reproducibility-check/fixtures/identical-output/baseline/module.rst	Adds reproducibility baseline module RST.
skills/pharaoh-reproducibility-check/fixtures/identical-output/README.md	Documents identical-output masking semantics.
skills/pharaoh-reproducibility-check/fixtures/drifted-titles/rerun/needs.json	Adds drift fixture rerun titles changes.
skills/pharaoh-reproducibility-check/fixtures/drifted-titles/input-mask-rules.yaml	Adds mask rules fixture input (no-op).
skills/pharaoh-reproducibility-check/fixtures/drifted-titles/expected-output.json	Expected fail output for title drift fields.
skills/pharaoh-reproducibility-check/fixtures/drifted-titles/baseline/needs.json	Adds drift fixture baseline needs.json.
skills/pharaoh-reproducibility-check/fixtures/drifted-titles/README.md	Documents drifted-titles failure behavior.
skills/pharaoh-reproducibility-check/fixtures/drifted-ids-but-masked/rerun/needs.json	Adds drift fixture rerun with randomized IDs.
skills/pharaoh-reproducibility-check/fixtures/drifted-ids-but-masked/input-mask-rules.yaml	Adds mask rules for generated_run_id masking.
skills/pharaoh-reproducibility-check/fixtures/drifted-ids-but-masked/expected-output.json	Expected pass output after masking non-deterministic fields.
skills/pharaoh-reproducibility-check/fixtures/drifted-ids-but-masked/baseline/needs.json	Adds drift fixture baseline with different generated ids.
skills/pharaoh-reproducibility-check/fixtures/drifted-ids-but-masked/README.md	Documents masking escape hatch semantics.
skills/pharaoh-process-audit/SKILL.md	Generalizes example paths away from Score-specific references.
skills/pharaoh-papyrus-non-empty-check/SKILL.md	Adds a new gate check to ensure Papyrus workspace is non-empty.
skills/pharaoh-output-validate/fixtures/graph-missing-tags/input-needs.json	Adds graph-mode metadata validation missing-tags fixture.
skills/pharaoh-output-validate/fixtures/graph-missing-tags/input-artefact-catalog.yaml	Adds catalog policy for missing-tags fixture.
skills/pharaoh-output-validate/fixtures/graph-missing-tags/expected-output.json	Expected output for missing required metadata fields.
skills/pharaoh-output-validate/fixtures/graph-missing-tags/README.md	Documents missing-tags behavior and sorting.
skills/pharaoh-output-validate/fixtures/graph-empty-required-list/input-needs.json	Adds graph-mode fixture for empty required list short-circuit.
skills/pharaoh-output-validate/fixtures/graph-empty-required-list/input-artefact-catalog.yaml	Adds explicit empty required list policy fixture.
skills/pharaoh-output-validate/fixtures/graph-empty-required-list/expected-output.json	Expected pass output when nothing is required.
skills/pharaoh-output-validate/fixtures/graph-empty-required-list/README.md	Documents “empty list means no check” semantics.
skills/pharaoh-output-validate/fixtures/graph-all-metadata-present/input-needs.json	Adds graph-mode happy-path fixture (all metadata present).
skills/pharaoh-output-validate/fixtures/graph-all-metadata-present/input-artefact-catalog.yaml	Adds catalog policy for all-metadata-present fixture.
skills/pharaoh-output-validate/fixtures/graph-all-metadata-present/expected-output.json	Expected pass output when all metadata is present.
skills/pharaoh-output-validate/fixtures/graph-all-metadata-present/README.md	Documents graph-mode happy path.
skills/pharaoh-link-completeness-check/fixtures/tailoring-declares-verifies-optional/input-needs.json	Adds fixture showing optional link types don’t fail the gate.
skills/pharaoh-link-completeness-check/fixtures/tailoring-declares-verifies-optional/input-artefact-catalog.yaml	Adds catalog policy marking verifies optional.
skills/pharaoh-link-completeness-check/fixtures/tailoring-declares-verifies-optional/expected-output.json	Expected pass output with optional verifies missing.
skills/pharaoh-link-completeness-check/fixtures/tailoring-declares-verifies-optional/README.md	Documents optional-link downgrade semantics.
skills/pharaoh-link-completeness-check/fixtures/partial-coverage/input-needs.json	Adds fixture for missing links + unresolved targets.
skills/pharaoh-link-completeness-check/fixtures/partial-coverage/input-artefact-catalog.yaml	Adds required link policy for partial coverage fixture.
skills/pharaoh-link-completeness-check/fixtures/partial-coverage/expected-output.json	Expected fail output with uncovered + unresolved targets.
skills/pharaoh-link-completeness-check/fixtures/partial-coverage/README.md	Documents all three failure modes.
skills/pharaoh-link-completeness-check/fixtures/all-covered/input-needs.json	Adds fixture with complete required-link coverage.
skills/pharaoh-link-completeness-check/fixtures/all-covered/input-artefact-catalog.yaml	Adds canonical required/optional link policy fixture.
skills/pharaoh-link-completeness-check/fixtures/all-covered/expected-output.json	Expected pass output for full link coverage.
skills/pharaoh-link-completeness-check/fixtures/all-covered/README.md	Documents happy path for link completeness.
skills/pharaoh-id-convention-check/fixtures/some-violate/input-needs.json	Adds mixed-conformance needs corpus fixture.
skills/pharaoh-id-convention-check/fixtures/some-violate/input-id-conventions.yaml	Adds per-type regex tailoring fixture input.
skills/pharaoh-id-convention-check/fixtures/some-violate/expected-output.json	Expected fail output listing violating IDs.
skills/pharaoh-id-convention-check/fixtures/some-violate/README.md	Documents deterministic ordering and per-type regex.
skills/pharaoh-id-convention-check/fixtures/alternation-regex/input-needs.json	Adds fixture for alternation regex allowing two schemes.
skills/pharaoh-id-convention-check/fixtures/alternation-regex/input-id-conventions.yaml	Adds alternation regex tailoring input.
skills/pharaoh-id-convention-check/fixtures/alternation-regex/expected-output.json	Expected pass output for alternation-allowed IDs.
skills/pharaoh-id-convention-check/fixtures/alternation-regex/README.md	Documents “policy is tailoring regex” semantics.
skills/pharaoh-id-convention-check/fixtures/all-conform/input-needs.json	Adds fully conforming corpus fixture.
skills/pharaoh-id-convention-check/fixtures/all-conform/input-id-conventions.yaml	Adds tailoring input for all-conform fixture.
skills/pharaoh-id-convention-check/fixtures/all-conform/expected-output.json	Expected pass output for all-conform fixture.
skills/pharaoh-id-convention-check/fixtures/all-conform/README.md	Documents fullmatch behavior and per-type resolution.
skills/pharaoh-id-allocate/SKILL.md	Adds new skill spec for deterministic pre-allocation of IDs.
skills/pharaoh-gate-advisor/fixtures/step-1-enabled/input-pharaoh.toml	Adds fixture for post-default step-1 enabled state.
skills/pharaoh-gate-advisor/fixtures/step-1-enabled/expected-output.json	Expected recommendation output (step 2) when step 1 enabled.
skills/pharaoh-gate-advisor/fixtures/step-1-enabled/README.md	Documents step-1-enabled branch.
skills/pharaoh-gate-advisor/fixtures/fresh-from-bootstrap/input-pharaoh.toml	Adds fixture for “all gates off” bootstrap state.
skills/pharaoh-gate-advisor/fixtures/fresh-from-bootstrap/expected-output.json	Expected recommendation output (step 1) from fresh bootstrap.
skills/pharaoh-gate-advisor/fixtures/fresh-from-bootstrap/README.md	Documents pre-2026-04-22 baseline state.
skills/pharaoh-gate-advisor/fixtures/all-steps-enabled/input-pharaoh.toml	Adds fixture where ladder is complete.
skills/pharaoh-gate-advisor/fixtures/all-steps-enabled/expected-output.json	Expected output returning recommended_next_gate: null.
skills/pharaoh-gate-advisor/fixtures/all-steps-enabled/README.md	Documents ladder-complete branch.
skills/pharaoh-fmea/SKILL.md	Adds self-review “Last step” invocation for FMEA emission.
skills/pharaoh-fmea-review/SKILL.md	Adds atomic skill spec for reviewing a single FMEA entry.
skills/pharaoh-finding-record/SKILL.md	Generalizes subject_id wording away from Score-specific ID.
skills/pharaoh-feat-review/SKILL.md	Adds atomic skill spec for reviewing a single feat.
skills/pharaoh-dispatch-signal-check/SKILL.md	Adds gate skill to detect subagent dispatch collapse vs plan.
skills/pharaoh-diagram-review/fixtures/return-to-user-wrong/input-source.py	Adds diagram-review fixture source for invalid terminal return.
skills/pharaoh-diagram-review/fixtures/return-to-user-wrong/input-diagram.rst	Adds invalid terminal-return diagram fixture.
skills/pharaoh-diagram-review/fixtures/return-to-user-wrong/expected-output.json	Expected fail output for returns-to-non-caller axis.
skills/pharaoh-diagram-review/fixtures/return-to-user-wrong/README.md	Documents “invented User” failure mode.
skills/pharaoh-diagram-review/fixtures/return-to-caller-correct/input-source.py	Adds diagram-review fixture source for valid return stack.
skills/pharaoh-diagram-review/fixtures/return-to-caller-correct/input-diagram.rst	Adds valid return-to-caller diagram fixture.
skills/pharaoh-diagram-review/fixtures/return-to-caller-correct/expected-output.json	Expected pass output for return stack check.
skills/pharaoh-diagram-review/fixtures/return-to-caller-correct/README.md	Documents entrypoint exception for terminal return.
skills/pharaoh-diagram-review/fixtures/external-lib-present/input-source.py	Adds fixture source with external dependency call.
skills/pharaoh-diagram-review/fixtures/external-lib-present/input-diagram.rst	Adds diagram fixture that includes external participant.
skills/pharaoh-diagram-review/fixtures/external-lib-present/expected-output.json	Expected pass output for external participant axis.
skills/pharaoh-diagram-review/fixtures/external-lib-present/README.md	Documents alias semantics for participant detection.
skills/pharaoh-diagram-review/fixtures/external-lib-missing/input-source.py	Adds fixture source with external dependency call.
skills/pharaoh-diagram-review/fixtures/external-lib-missing/input-diagram.rst	Adds diagram fixture missing external participant.
skills/pharaoh-diagram-review/fixtures/external-lib-missing/expected-output.json	Expected fail output for missing external participant.
skills/pharaoh-diagram-review/fixtures/external-lib-missing/README.md	Documents external dependency omission failure.
skills/pharaoh-diagram-review/fixtures/conditional-present/input-source.py	Adds fixture source with branching control flow.
skills/pharaoh-diagram-review/fixtures/conditional-present/input-diagram.rst	Adds diagram fixture with alt block showing branches.
skills/pharaoh-diagram-review/fixtures/conditional-present/expected-output.json	Expected pass output for conditional branches marked.
skills/pharaoh-diagram-review/fixtures/conditional-present/README.md	Documents renderer-agnostic conditional marker detection.
skills/pharaoh-diagram-review/fixtures/conditional-missing/input-source.py	Adds fixture source with branching control flow.
skills/pharaoh-diagram-review/fixtures/conditional-missing/input-diagram.rst	Adds linear diagram fixture missing branch markers.
skills/pharaoh-diagram-review/fixtures/conditional-missing/expected-output.json	Expected fail output for missing alt/opt/loop/group markers.
skills/pharaoh-diagram-review/fixtures/conditional-missing/README.md	Documents conditional omission detection.
skills/pharaoh-deployment-diagram-draft/SKILL.md	Adds deployment diagram draft skill (currently marked PLANNED).
skills/pharaoh-decision-review/SKILL.md	Adds atomic skill spec for reviewing decisions.
skills/pharaoh-decision-record/SKILL.md	Adds self-review “Last step” invocation for decision emission.
skills/pharaoh-coverage-gap/SKILL.md	Generalizes example paths away from Score-specific references.
skills/pharaoh-arch-draft/SKILL.md	Adds self-review “Last step” invocation for arch emission.
skills/pharaoh-api-coverage-check/fixtures/unsupported-extension/input-source.lua	Adds unsupported-language fixture source (.lua).
skills/pharaoh-api-coverage-check/fixtures/unsupported-extension/input-needs.json	Adds needs corpus for unsupported-language fixture.
skills/pharaoh-api-coverage-check/fixtures/unsupported-extension/expected-output.json	Expected fail output for unsupported language branch.
skills/pharaoh-api-coverage-check/fixtures/unsupported-extension/README.md	Documents unsupported-extension failure and remediation.
skills/pharaoh-api-coverage-check/fixtures/typescript-fully-covered/input-source.ts	Adds TS fixture source for exported symbol coverage.
skills/pharaoh-api-coverage-check/fixtures/typescript-fully-covered/input-needs.json	Adds needs corpus covering all TS public symbols/throws.
skills/pharaoh-api-coverage-check/fixtures/typescript-fully-covered/expected-output.json	Expected pass output for full TS coverage.
skills/pharaoh-api-coverage-check/fixtures/typescript-fully-covered/README.md	Documents TS regex row and throw-site extraction.
skills/pharaoh-api-coverage-check/fixtures/rust-fully-covered/input-source.rs	Adds Rust fixture source for pub item coverage.
skills/pharaoh-api-coverage-check/fixtures/rust-fully-covered/input-needs.json	Adds needs corpus covering Rust public items.
skills/pharaoh-api-coverage-check/fixtures/rust-fully-covered/expected-output.json	Expected pass output for full Rust coverage.
skills/pharaoh-api-coverage-check/fixtures/rust-fully-covered/README.md	Documents Rust regex row and vacuous raise-site dimension.
skills/pharaoh-api-coverage-check/fixtures/python-uncovered-raises/input-source.py	Adds Python fixture source for uncovered raise-site exceptions.
skills/pharaoh-api-coverage-check/fixtures/python-uncovered-raises/input-needs.json	Adds needs corpus with missing raise-site coverage.
skills/pharaoh-api-coverage-check/fixtures/python-uncovered-raises/expected-output.json	Expected fail output driven by raise-site gaps.
skills/pharaoh-api-coverage-check/fixtures/python-uncovered-raises/README.md	Documents reverse-coverage motivating case.
skills/pharaoh-api-coverage-check/fixtures/python-half-covered/input-source.py	Adds Python fixture source with partial symbol/raise coverage.
skills/pharaoh-api-coverage-check/fixtures/python-half-covered/input-needs.json	Adds needs corpus covering subset of symbols.
skills/pharaoh-api-coverage-check/fixtures/python-half-covered/expected-output.json	Expected fail output at default threshold.
skills/pharaoh-api-coverage-check/fixtures/python-half-covered/README.md	Documents combined ratio computation.
skills/pharaoh-api-coverage-check/fixtures/python-fully-covered/input-source.py	Adds Python fixture source for full coverage.
skills/pharaoh-api-coverage-check/fixtures/python-fully-covered/input-needs.json	Adds needs corpus covering all symbols/raise sites.
skills/pharaoh-api-coverage-check/fixtures/python-fully-covered/expected-output.json	Expected pass output at default threshold.
skills/pharaoh-api-coverage-check/fixtures/python-fully-covered/README.md	Documents canonical passing Python case.
skills/pharaoh-api-coverage-check/fixtures/language-override/input-source.txt	Adds fixture source requiring explicit language override.
skills/pharaoh-api-coverage-check/fixtures/language-override/input-needs.json	Adds needs corpus for language override fixture.
skills/pharaoh-api-coverage-check/fixtures/language-override/input-meta.yaml	Adds meta input specifying explicit language override.
skills/pharaoh-api-coverage-check/fixtures/language-override/expected-output.json	Expected pass output when language override applied.
skills/pharaoh-api-coverage-check/fixtures/language-override/README.md	Documents override escape hatch.
skills/pharaoh-api-coverage-check/fixtures/java-fully-covered/input-source.java	Adds Java fixture source for public symbol + throw coverage.
skills/pharaoh-api-coverage-check/fixtures/java-fully-covered/input-needs.json	Adds needs corpus for Java fixture.
skills/pharaoh-api-coverage-check/fixtures/java-fully-covered/expected-output.json	Expected pass output for Java fixture.
skills/pharaoh-api-coverage-check/fixtures/java-fully-covered/README.md	Documents Java regex row and throw-site extraction.
skills/pharaoh-api-coverage-check/fixtures/go-fully-covered/input-source.go	Adds Go fixture source for exported symbol detection.
skills/pharaoh-api-coverage-check/fixtures/go-fully-covered/input-needs.json	Adds needs corpus for Go fixture.
skills/pharaoh-api-coverage-check/fixtures/go-fully-covered/expected-output.json	Expected pass output for Go fixture.
skills/pharaoh-api-coverage-check/fixtures/go-fully-covered/README.md	Documents Go identifier-case visibility rule.
skills/pharaoh-api-coverage-check/fixtures/cpp-fully-covered/input-source.cpp	Adds C++ fixture source for class/struct + throw coverage.
skills/pharaoh-api-coverage-check/fixtures/cpp-fully-covered/input-needs.json	Adds needs corpus for C++ fixture.
skills/pharaoh-api-coverage-check/fixtures/cpp-fully-covered/expected-output.json	Expected pass output for C++ fixture.
skills/pharaoh-api-coverage-check/fixtures/cpp-fully-covered/README.md	Documents C++ throw syntax support.
skills/pharaoh-api-coverage-check/fixtures/c-fully-covered/input-source.c	Adds C fixture source for public function detection.
skills/pharaoh-api-coverage-check/fixtures/c-fully-covered/input-needs.json	Adds needs corpus for C fixture.
skills/pharaoh-api-coverage-check/fixtures/c-fully-covered/expected-output.json	Expected pass output for C fixture.
skills/pharaoh-api-coverage-check/fixtures/c-fully-covered/README.md	Documents C regex row and private-prefix filtering.
skills/pharaoh-activity-diagram-draft/SKILL.md	Adds activity diagram draft skill (currently marked PLANNED).
pharaoh.toml.example	Updates example config comments to describe gate-enablement ladder.
.github/agents/pharaoh.use-case-diagram-draft.agent.md	Adds GitHub agent wrapper for use-case diagram draft skill.
.github/agents/pharaoh.tailor-code-grounding-filters.agent.md	Adds agent wrapper for code-grounding filter tailoring skill.
.github/agents/pharaoh.status-lifecycle-check.agent.md	Adds agent wrapper for status lifecycle gate check.
.github/agents/pharaoh.sphinx-extension-add.agent.md	Adds agent wrapper for Sphinx extension injection skill.
.github/agents/pharaoh.self-review-coverage-check.agent.md	Adds agent wrapper for self-review coverage check.
.github/agents/pharaoh.reqs-from-module.agent.md	Removes agent wrapper for deleted orchestration skill.
.github/agents/pharaoh.req-code-grounding-check.agent.md	Adds agent wrapper for requirement code grounding check.
.github/agents/pharaoh.reproducibility-check.agent.md	Adds agent wrapper for reproducibility check.
.github/agents/pharaoh.papyrus-non-empty-check.agent.md	Adds agent wrapper for Papyrus non-empty check.
.github/agents/pharaoh.link-completeness-check.agent.md	Adds agent wrapper for link completeness check.
.github/agents/pharaoh.id-convention-check.agent.md	Adds agent wrapper for ID convention check.
.github/agents/pharaoh.gate-advisor.agent.md	Adds agent wrapper for gate advisor ladder walker.
.github/agents/pharaoh.fmea-review.agent.md	Adds agent wrapper for FMEA review.
.github/agents/pharaoh.feat-review.agent.md	Adds agent wrapper for feat review.
.github/agents/pharaoh.dispatch-signal-check.agent.md	Adds agent wrapper for dispatch signal check.
.github/agents/pharaoh.diagram-review.agent.md	Adds agent wrapper for diagram review.
.github/agents/pharaoh.diagram-lint.agent.md	Adds agent wrapper for diagram lint.
.github/agents/pharaoh.decision-review.agent.md	Adds agent wrapper for decision review.
.github/agents/pharaoh.bootstrap.agent.md	Adds agent wrapper for bootstrap skill.
.github/agents/pharaoh.api-coverage-check.agent.md	Adds agent wrapper for API coverage check.

Comments suppressed due to low confidence (1)

skills/pharaoh-req-regenerate/SKILL.md:1

• The example still describes a gd_req directive prefix while the fallback defaults are now defined in terms of req. If gd_req is no longer the canonical built-in profile, update the example prefix here (and any related “default profile” references) to avoid implying that gd_req is still the default type.

---

[patdhlk]

Code Review — PR #9

Overview

Massive refactor (360 files; +12,818 / −224 LOC; squashed into single commit 0eec11f). Converts Pharaoh from prose-orchestrated composition skills to plan-driven DAG execution:

• New engine: pharaoh-write-plan emits a declarative plan.yaml; pharaoh-execute-plan consumes it with a closed ref-grammar, helper set, and four execution modes (inline | subagents | family-bundle | ask).
• ~41 new atomic skills (feat extraction, review/grounding axes, diagram ecosystem, tailoring, gate checks, output validation).
• ISO 26262-8 §6 axis split for pharaoh-req-review (4 mechanized binary + 3 subjective 0-3; set/chain axes deferred).
• pharaoh-req-from-code adds seven shall-clause rules and config-driven tailoring.
• Deletes pharaoh-reqs-from-module and its prose orchestration.

Strengths

• Atomicity discipline. Every skill declares (a)-(e) criteria; most back (c) with reward fixtures. Right contract.
• Defense in depth. output_presence_audit (execute-plan Step 4.10), self_review_coverage, dispatch_signal_matches_plan, papyrus_non_empty each close a specific documented failure mode ("LLM skipped the review to save tokens", "collapsed foreach to inline", etc.).
• Schema first. pharaoh-execute-plan/schema.md specifies ref grammar, helper set, cycle detection, foreach semantics, and execution modes explicitly; unknown helpers/fields fail static validation.
• Clean tailoring surface. ubproject.toml / pharaoh.toml / .pharaoh/project/ resolution order documented in shared/tailoring-access.md; pharaoh-req-from-code and diagram skills read from it consistently.
• Rationale notes are excellent. Design-note stubs explain why family-bundle breaks per-instance caps, why ask is the default, why the B1 "enrich, never strip" invariant holds.

Issues — blocking

1. Template refs target fields that don't exist

templates/reverse-engineer-project.yaml.j2 references outputs that no task declares in its outputs: map and no skill emits:

• Lines 119, 134: \${reqs_from_code.emitted_ids} — pharaoh-req-from-code emits RST directive blocks, not a structured `emitted_ids` list. Task declares `outputs.emitted_ids: list` (documentary only), but the executor has no mechanism to populate it.
• Lines 206, 219: \${draft_feats.emitted_feat_ids} — draft_feats declares `outputs.feats: list`, not `emitted_feat_ids`. Neither is emitted by the skill.

Runtime would fail with unresolved_ref at dispatch time for review_comp_reqs, grounding_check_comp_reqs, review_feats, draft_use_case_diagrams.

2. Schema violation: ref interpolation inside larger strings

schema.md line 47: "A value may ONLY be wholly a ref (no interpolation inside larger strings)". Templates violate:

• id_allocate.existing_ids_file: \${project_root}/docs/_build/needs/needs.json
• api_coverage_comp_reqs.needs_json_path: \${project_root}/docs/source/_build/needs/needs.json

Either relax the schema (a path_join helper is the obvious fix) or substitute {{ project_root }} at Jinja-render time.

3. Outputs binding is under-specified

schema.md line 39-41 + line 69 say outputs: is "purely documentary; executor does not enforce", and unknown fields are WARNINGs, not failures. But execute-plan.md worked example (lines 248-272) and the templates rely on the executor binding pharaoh-output-validate.parsed to the declared outputs.<key> names (e.g. "Parsed `feats:` list cached to store"). This contract is load-bearing for every plan — but is undocumented. Either document it in schema.md (§"Ref resolution" and §"Task object") or the worked example is wrong.

4. grounding_check_comp_reqs missing a required input

pharaoh-req-code-grounding-check requires {target, source_doc_path, tailoring_path}. Template passes only target + tailoring_path. Per the skill's own failure modes, axis #8 source_doc_resolves fails with "source_doc missing" and every other axis records n/a — every instance of this task fails at runtime.

5. codelink_annotate.foreach: \${reqs_from_code} shape mismatch

reqs_from_code is itself a foreach task. Per schema §"Foreach" line 99, \${map_files.files} (no index) resolves to a flat list across instances. But \${reqs_from_code} (no field) has undefined semantics — is it list-of-blocks? list-of-lists-of-blocks? The annotator expects one req directive per instance.

6. papyrus_non_empty.enabled: "\${preseed_papyrus}"

gate_spec.invariants.*.enabled is bool. \${preseed_papyrus} resolves to whatever the pharaoh-decision-record foreach output is (mapping or list) — not a bool. Either use enabled: true unconditionally (the check is cheap to no-op) or add a dedicated helper.

7. Copilot fixes reference an unpushed commit

Author's responses to Copilot's inline comments ("Fixed in 136e8fe") reference a commit not present on the PR branch. git log on the PR tip shows only 0eec11f. Either force-push the fix commit or note that fixes are on a follow-up branch.

Issues — non-blocking

8. Inconsistent hardcoded needs.json paths

• id_allocate: docs/_build/needs/needs.json
• api_coverage: docs/source/_build/needs/needs.json

Should derive from {{ docs_root }}/_build/needs/needs.json. Real projects use either layout.

9. quality_gate.inputs.artefacts_dir is not a documented input

pharaoh-quality-gate/SKILL.md §Input lists artefacts_summary_path, not artefacts_dir. Template passes artefacts_dir. Either rename the template input or document artefacts_dir in the skill.

10. Jinja escape gymnastics

Template uses "{{ '\${' }}reqs_from_code.emitted_ids{{ '}' }}" to emit a \${...} literal. {% raw %}\${...}{% endraw %} or a ref(...) convention would be cleaner and less error-prone.

11. pharaoh-id-allocate: seq cap = 100 silently conflicts with :02d zero-pad

<prefix><stem>_<seq:02d> breaks at seq ≥ 100. The 100 limit is presented as a collision-safety cap but is also a format cap — worth stating explicitly so callers understand the hard stem limit is ~99 IDs.

12. PR description overstates shipping

PR body says "nine per-view drafters … all nine ship". Per the amended pharaoh-write-plan catalogue, only pharaoh-use-case-diagram-draft runs end-to-end; seven are design-only scaffolds with sentinel FAIL bodies (author already acknowledged this in the Copilot thread).

Risks

• The "end-to-end pilot" claim rides on a companion PR. This PR's own test plan is "markdown-only, no Python tests — reward fixtures enforce correctness". Fine for atomic skills, but the two plan templates have not been statically validated against schema.md in this repo (issues 1, 2, 4, 5 above would be caught by a trivial schema dry-run). Consider adding a CI job that runs pharaoh-write-plan + static-ref validation on the template fixtures.
• Large surface area, single squashed commit. Bisection on regressions will be painful. Future refactors of this size should keep multiple commits so git blame stays useful.

Recommendation

Request changes. Architectural direction is strong and the atomic-skill discipline is excellent, but issues 1-6 are concrete blockers that will break the first real execution of reverse-engineer-project (or silently produce partial plans). Underlying skill contracts look sound — fixes are mostly in the template and a few schema clarifications.

Fastest path to merge:

1. Add an emitted_ids: list structured return to pharaoh-req-from-code and pharaoh-feat-draft-from-docs (or specify how the executor derives it from rst_directive.parsed[].options.id).
2. Document the outputs-binding semantics in schema.md explicitly.
3. Fix the interpolated-string refs (issue 2) — add a path_join helper or switch to Jinja substitution.
4. Add source_doc_path: \${item.source_doc} (or equivalent) to grounding_check_comp_reqs inputs.
5. Resolve the codelink_annotate shape (issue 5) with a documented helper.
6. Push the 136e8fe fixes to the branch.

Happy to re-review once those land.

[bburda]

Thanks for the deep review - incredibly useful. Walking through your numbered points with what landed in the follow-up commit and what I pushed back on.

Issue 7 - "Copilot fixes reference an unpushed commit 136e8fe"

False alarm - 136e8fe was real and pushed; the PR was then squash-rebased onto 5917cfa (the PR #7 merge), collapsing fb916d2…65b0fd9 into the single 0eec11f you see now. The fixes themselves survived the squash (verified the four Copilot-flagged files: dispatch-signal-check accepts the full mode enum, id-allocate uses JSON array + independent counters, api-coverage-check pass fixtures all carry blockers: [], and pharaoh-write-plan/SKILL.md no longer claims all nine drafters ship). Sorry for the SHA dangling in the inline replies - I didn't think to update them after the squash.

Issues 1, 3, 4 - phantom emitted_ids / emitted_feat_ids, outputs binding under-specified, missing source_doc_path

You were right that the templates referenced fields the producer skills never emit and the executor never bound. Took the smallest-diff route that actually makes the contract real:

• pharaoh-feat-draft-from-docs and pharaoh-req-from-code ## Output sections now declare structured JSON: {feats: [{id, title, type, body, source_doc, raw_rst}, ...]} and {reqs: [{id, title, type, body, source_doc, satisfies, verification, raw_rst}, ...]}. expected_output_schema: json_obj.
• Templates now iterate over the structured lists: foreach: ${reqs_from_code.reqs | flatten} (foreach-of-foreach gives list-of-lists; flatten collapses), foreach: ${draft_feats.feats} (single-instance task gives flat list directly). Each ${item} is a mapping, so downstream tasks pick fields via ${item.raw_rst}, ${item.id}, ${item.source_doc}, etc.
• grounding_check_comp_reqs now passes source_doc_path: ${item.source_doc} + project_root: ${project_root}. pharaoh-req-code-grounding-check SKILL.md explicitly accepts relative paths resolved via project_root, and auto-derives source_doc_path from the RST block's :source_doc: option when omitted with an RST target.
• Schema.md gains an explicit ## Outputs binding section documenting how expected_output_schema parses skill output into the artefact store. The outputs: declaration is no longer sold as "purely documentary" - it's the field hint the executor uses for binding.

Issue 2 - interpolation inside larger strings (schema §47)

Three sites fixed: all three ${project_root}/... refs that were embedded in larger paths flipped to Jinja-time substitution {{ project_root }}/{{ docs_root }}/_build/needs/needs.json. Schema rule preserved.

Issue 5 - codelink_annotate.foreach: ${reqs_from_code} shape mismatch + missing inputs

Same root cause as 1 - task now passes typed inputs from the structured req mapping: req_id: ${item.id}, req_title: ${item.title}, req_type: ${item.type}, file_path: ${item.source_doc}, parent_links: ${item.satisfies}, anchor: {type: top_of_file}, project_root: ${project_root}. pharaoh-req-codelink-annotate SKILL.md updated so file_path accepts paths relative to project_root.

Issue 6 - papyrus_non_empty.enabled is a ref, must be bool

Hard-coded enabled: true. The check is cheap to no-op when preseed_papyrus produced zero entries, so unconditional enabling is fine.

Issue 7 - covered above

Issue 8 - hardcoded needs.json path inconsistency

Both templates now derive the path from the new docs_root template variable: {{ project_root }}/{{ docs_root }}/_build/needs/needs.json. The module template gained docs_root as a required_var.

Issues 9, 10, 11, 12 (non-blocking)

• 9 (artefacts_dir undocumented) - left as-is for now; will land alongside a pharaoh-quality-gate SKILL.md input-contract pass. Filing follow-up.
• 10 (Jinja escape gymnastics) - moot now that the templates no longer need the {{ '${' }}…{{ '}' }} escape (the offending refs were the phantom emitted_ids ones, all rewritten as bare ${reqs_from_code.reqs | flatten}).
• 11 (seq cap vs :02d format) - fixed: cap is now 99 everywhere in pharaoh-id-allocate/SKILL.md, with the rationale ("aligns with the 2-digit format") spelled out.
• 12 (PR description overstates shipping) - PR body rewritten to honestly mark eight drafters as design-only scaffolds; the per-skill description: frontmatter on each scaffold now also carries Status - PLANNED. Also softened the "every skill (a)-(e)" claim (composition skills are not atoms), the "stripped domain-specific identifiers from every fixture" claim (Jama persists across several fixtures as a pedagogical placeholder), and removed the orphan pilot paragraph (numbers came from a local validation run, no companion PR exists).

Bonus from a follow-up audit: pharaoh-req-codelink-annotate and pharaoh-toctree-emit were missing ## Last step sections (PR-body claim "every emission skill" was incorrect). Both now document an inline structural self-verification (idempotence read-back for codelink-annotate; entry-existence + duplicate-check for toctree-emit) and delegate set-level coverage to pharaoh-quality-gate invariants.

Re-review whenever you have a window.