From fdf7a8f0e424ba802be2eaa7292cf518b725dbca Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 14:30:18 +0200 Subject: [PATCH 01/15] fix(pharaoh-setup): infer required_links direction from edges, not link names The previous Step 2b inferred chain direction from a heuristic table mapping link option names to fixed chains (e.g., `implements -> "spec -> impl"`). The table assumed a single convention (parent references child). On projects that follow the opposite convention (child references parent via `:implements:`), every emitted chain is the inverse of the actual edge and `pharaoh:mece` reports 100% gaps for the source type. Replace the heuristic table with three sources applied in priority order: 1. Built `needs.json` when available -- emit `X -> Y` only where at least 90% of `X` instances with the link option resolve to a `Y` (and at least 3 instances exist), so the direction matches the data the project emits. 2. Declared `outgoing`/`incoming` semantics in `[needs.links.]` -- only used when an explicit type-pair hint is supplied; the description alone does not identify the type pair. 3. Refuse to guess -- emit a TODO comment instead of a chain. The type-pair declared-in-`[[needs.types]]` filter and the empty-array fallback continue to apply to every source. Closes #11 --- skills/pharaoh-setup/SKILL.md | 75 +++++++++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 17 deletions(-) diff --git a/skills/pharaoh-setup/SKILL.md b/skills/pharaoh-setup/SKILL.md index 068faa2..0647e9e 100644 --- a/skills/pharaoh-setup/SKILL.md +++ b/skills/pharaoh-setup/SKILL.md @@ -248,23 +248,64 @@ Generate the `pharaoh.toml` content using the detected project data. Use `pharao ``` **`[pharaoh.traceability]` section:** -- Build `required_links` from the detected extra link types, but **only for type pairs where BOTH types are declared in `ubproject.toml` `[[needs.types]]`.** A chain `comp_req -> test` where `test` is not a declared type is dead config — it alarms on every `comp_req` from day one. Skip it. -- For each extra link type, determine the source and target types by examining the link's usage in existing need directives. If the link name is `implements`, and it appears on `impl` directives pointing to `spec` directives, generate `"spec -> impl"` only if both `impl` and `spec` are declared. -- If usage cannot be determined from existing needs, infer from naming conventions: - - `implements` or `realizes` -> `"spec -> impl"` - - `tests` or `verifies` -> `"impl -> test"` - - `satisfies` or `fulfills` -> `"req -> spec"` - - `derives` or `derives_from` -> `"req -> req"` (parent to child) -- Also check for standard `links` usage to detect implicit traceability chains (e.g., specs linking to reqs via `:links:`). -- If the project has a clear type hierarchy (e.g., req -> spec -> impl -> test), generate the full chain — but filter out any edges whose target type is not declared: - ```toml - required_links = [ - "req -> spec", - "spec -> impl", - # "impl -> test", # SKIPPED: 'test' is not declared in [[needs.types]] - ] - ``` -- If no link types are detected, leave `required_links` as an empty array with a comment explaining how to add entries. + +`required_links` declares chains in the form `"source-type -> target-type"`. The semantics enforced by `pharaoh:mece` are: every need of `source-type` must have at least one outgoing link to a need of `target-type` (see `skills/pharaoh-mece/SKILL.md` Step 2). The chain direction is therefore the direction the link option resolves, **not** the direction of the conceptual type hierarchy. Both conventions exist in the wild — some projects put `:implements:` on the `impl` directive (child references parent, chain `impl -> spec`); others put `:specifies:` on the `spec` directive (parent references child, chain `spec -> impl`). Inferring direction from the link option name picks one convention and emits inverted chains for projects on the other; `pharaoh:mece` then reports 100% gaps for the source type. Resolve direction from ground truth instead. + +Apply the following sources in priority order. For each link option, stop at the first source that resolves a direction. + +**Source 1 — built `needs.json` (preferred, when available).** If the project has a built `needs.json` (typical paths: `/_build/needs/needs.json`, `/_build/html/needs.json`, or any `needs.json` under `_build/`), parse it and inspect the actual edges: + +For each declared link option `L` (including the standard `:links:`) and each ordered pair of declared types `(X, Y)`: + +1. Let `n_X` = count of needs of type `X` whose `:L:` value is non-empty. +2. Let `n_X_to_Y` = count of those needs whose `:L:` resolves to at least one need of type `Y`. +3. Emit `"X -> Y"` only if `n_X >= 3` and `n_X_to_Y / n_X >= 0.9`. + +The thresholds (`>= 3` instances, `>= 90%` coverage) suppress chains inferred from a single accidental edge while still emitting chains the project consistently produces. Include a comment recording the sample size: + +```toml +required_links = [ + "spec -> req", # needs.json: 18/18 spec needs link to req via :reqs: + "impl -> spec", # needs.json: 35/35 impl needs link to spec via :implements: +] +``` + +**Source 2 — declared semantics from `[needs.links.]` (greenfield, no `needs.json`).** The `outgoing` and `incoming` descriptions identify the verb and which side bears the link option, but they do not, on their own, identify the type pair: any type can carry any link option. Without empirical edges or an explicit hint, the source and target types are unknown. + +Use this source only when `ubproject.toml` carries an explicit hint (e.g., a future `[needs.links.] from = "", to = ""` extension). Do not invent the type pair from the link option name. + +**Source 3 — refuse to guess.** When neither source resolves a link option to a `(source-type, target-type)` pair, do **not** emit a chain for that link. Emit a TODO comment in its place so the user sees what was skipped and why: + +```toml +required_links = [ + "spec -> req", # needs.json: 18/18 spec needs link to req via :reqs: + # TODO: link option `implements` is declared but no `needs.json` was + # found. Build the docs once and re-run `pharaoh:setup`, or add an + # explicit chain manually in the form "source-type -> target-type". +] +``` + +The previous heuristic-name table (`implements -> "spec -> impl"`, `tests -> "impl -> test"`, etc.) is removed: it encoded one project convention as universal and produced inverted chains on every project that used the opposite convention. + +**Type-pair filter (applied to every source).** Emit a chain only when both the source type and the target type are declared in `ubproject.toml` `[[needs.types]]`. When Source 1 resolves an edge whose target type is not declared, drop it with a comment naming the dropped target — the chain is dead config that would alarm on every source need from day one: + +```toml +required_links = [ + "req -> spec", + "spec -> impl", + # "impl -> test", # SKIPPED: 'test' is not declared in [[needs.types]] +] +``` + +**Empty-array fallback.** If no link option resolves to a chain by any source, emit: + +```toml +required_links = [ + # No traceability chains inferred. Add entries of the form + # "source-type -> target-type" once the link conventions stabilise, + # or build the docs and re-run `pharaoh:setup` to infer from `needs.json`. +] +``` **`[pharaoh.codelinks]` section:** - Set `enabled = true` if sphinx-codelinks was detected in Step 1e. From fd2e9eb2a65e0cbc58bb8b38710f31cf0a3e9319 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 15:03:07 +0200 Subject: [PATCH 02/15] fix(agents): sync agent.md descriptions with SKILL.md, fix gitignore guidance (#12) The 71 .github/agents/pharaoh.*.agent.md files shipped with descriptions that diverged from their source SKILL.md. Two were catastrophically truncated at the first '.' (split caught 'e.g.' and 'index.rst'), producing unclosed parens and backticks that broke Markdown rendering in Copilot's review UI on downstream PRs (sphinx-needs-demo#51). Changes: - 61 thin-wrapper agents: regenerate description and body verbatim from SKILL.md frontmatter; preserve existing handoffs. - 8 fat agents (mece, plan, change, spec, setup, decide, release, trace): update only the frontmatter description; leave hand-tailored inline content untouched. - pharaoh.setup.agent.md Step 3: rewrite gitignore guidance to mirror SKILL.md Step 4b. Ignore only ephemeral subpaths (.pharaoh/runs/, .pharaoh/plans/, .pharaoh/session.json, .pharaoh/cache/); .pharaoh/project/ tailoring stays tracked. - ci.yaml: add a guard that fails the agent-frontmatter step when the description has unbalanced parens, brackets, or backticks. Catches the truncation class that produced the original regression. --- .../pharaoh.activity-diagram-draft.agent.md | 4 ++-- .../pharaoh.api-coverage-check.agent.md | 6 ++--- .github/agents/pharaoh.arch-draft.agent.md | 4 ++-- .github/agents/pharaoh.arch-review.agent.md | 4 ++-- .github/agents/pharaoh.audit-fanout.agent.md | 4 ++-- .../pharaoh.block-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.bootstrap.agent.md | 4 ++-- .github/agents/pharaoh.change.agent.md | 2 +- .../pharaoh.class-diagram-draft.agent.md | 4 ++-- .../pharaoh.component-diagram-draft.agent.md | 4 ++-- .../agents/pharaoh.context-gather.agent.md | 4 ++-- .github/agents/pharaoh.coverage-gap.agent.md | 4 ++-- .github/agents/pharaoh.decide.agent.md | 2 +- .../agents/pharaoh.decision-record.agent.md | 4 ++-- .../agents/pharaoh.decision-review.agent.md | 6 ++--- .../pharaoh.deployment-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.diagram-lint.agent.md | 4 ++-- .../agents/pharaoh.diagram-review.agent.md | 6 ++--- .../pharaoh.dispatch-signal-check.agent.md | 6 ++--- .github/agents/pharaoh.execute-plan.agent.md | 4 ++-- .../pharaoh.fault-tree-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.feat-balance.agent.md | 4 ++-- .../pharaoh.feat-component-extract.agent.md | 4 ++-- .../pharaoh.feat-draft-from-docs.agent.md | 4 ++-- .github/agents/pharaoh.feat-file-map.agent.md | 4 ++-- .../agents/pharaoh.feat-flow-extract.agent.md | 4 ++-- .github/agents/pharaoh.feat-review.agent.md | 6 ++--- .../agents/pharaoh.finding-record.agent.md | 4 ++-- .github/agents/pharaoh.flow.agent.md | 4 ++-- .github/agents/pharaoh.fmea-review.agent.md | 6 ++--- .github/agents/pharaoh.fmea.agent.md | 4 ++-- .github/agents/pharaoh.gate-advisor.agent.md | 6 ++--- .github/agents/pharaoh.id-allocate.agent.md | 4 ++-- .../pharaoh.id-convention-check.agent.md | 6 ++--- .../agents/pharaoh.lifecycle-check.agent.md | 4 ++-- .../pharaoh.link-completeness-check.agent.md | 6 ++--- .github/agents/pharaoh.mece.agent.md | 2 +- .../agents/pharaoh.output-validate.agent.md | 4 ++-- .../pharaoh.papyrus-non-empty-check.agent.md | 4 ++-- .github/agents/pharaoh.plan.agent.md | 2 +- .github/agents/pharaoh.process-audit.agent.md | 4 ++-- .github/agents/pharaoh.prose-migrate.agent.md | 4 ++-- .github/agents/pharaoh.quality-gate.agent.md | 4 ++-- .github/agents/pharaoh.release.agent.md | 2 +- .../pharaoh.reproducibility-check.agent.md | 6 ++--- .../pharaoh.req-code-grounding-check.agent.md | 6 ++--- .../pharaoh.req-codelink-annotate.agent.md | 4 ++-- .github/agents/pharaoh.req-draft.agent.md | 4 ++-- .github/agents/pharaoh.req-from-code.agent.md | 4 ++-- .../agents/pharaoh.req-regenerate.agent.md | 4 ++-- .github/agents/pharaoh.req-review.agent.md | 4 ++-- .../pharaoh.review-completeness.agent.md | 4 ++-- ...haraoh.self-review-coverage-check.agent.md | 6 ++--- .../pharaoh.sequence-diagram-draft.agent.md | 4 ++-- .github/agents/pharaoh.setup.agent.md | 23 +++++++++++++++++-- .github/agents/pharaoh.spec.agent.md | 2 +- .../pharaoh.sphinx-extension-add.agent.md | 4 ++-- .../pharaoh.standard-conformance.agent.md | 4 ++-- .../pharaoh.state-diagram-draft.agent.md | 4 ++-- .../pharaoh.status-lifecycle-check.agent.md | 4 ++-- .../agents/pharaoh.tailor-bootstrap.agent.md | 4 ++-- ...aoh.tailor-code-grounding-filters.agent.md | 4 ++-- .github/agents/pharaoh.tailor-detect.agent.md | 4 ++-- .github/agents/pharaoh.tailor-fill.agent.md | 4 ++-- .github/agents/pharaoh.tailor-review.agent.md | 4 ++-- .github/agents/pharaoh.toctree-emit.agent.md | 4 ++-- .github/agents/pharaoh.trace.agent.md | 2 +- .../pharaoh.use-case-diagram-draft.agent.md | 6 ++--- .github/agents/pharaoh.vplan-draft.agent.md | 4 ++-- .github/agents/pharaoh.vplan-review.agent.md | 4 ++-- .github/agents/pharaoh.write-plan.agent.md | 4 ++-- .github/workflows/ci.yaml | 22 ++++++++++++++++++ 72 files changed, 189 insertions(+), 148 deletions(-) diff --git a/.github/agents/pharaoh.activity-diagram-draft.agent.md b/.github/agents/pharaoh.activity-diagram-draft.agent.md index cb40cfe..36bba5e 100644 --- a/.github/agents/pharaoh.activity-diagram-draft.agent.md +++ b/.github/agents/pharaoh.activity-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. +description: Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. Typical ASPICE usage — SWE.3 Software Detailed Design. Renderer tailored via `pharaoh.toml`. Does NOT emit other diagram kinds. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.activity-diagram-draft -Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. +Use when drafting one activity diagram showing control flow (actions, decisions, forks/joins, swimlanes) for one procedure or algorithm. Typical ASPICE usage — SWE.3 Software Detailed Design. Renderer tailored via `pharaoh.toml`. Does NOT emit other diagram kinds. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-activity-diagram-draft/SKILL.md`](../../skills/pharaoh-activity-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.api-coverage-check.agent.md b/.github/agents/pharaoh.api-coverage-check.agent.md index f76eb9c..0fac840 100644 --- a/.github/agents/pharaoh.api-coverage-check.agent.md +++ b/.github/agents/pharaoh.api-coverage-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify that every public symbol and every raise-site exception in a source file is covered by at least one need in needs.json. Reverse direction of pharaoh-req-from-code — language-parametric via the shared regex table; emits per-symbol and per-raise-site coverage plus a ratio against a tailored threshold. +description: Use when verifying that a source file is covered by the need catalogue on two axes — (1) at least one CREQ declares the file as its `:source_doc:`, and (2) every project-defined exception class raised in the file is named by some CREQ's title or content. Exception classes not defined in the project source tree (stdlib, third-party deps) are reported as `external` and do not fail the axis. Classifies non-behavioral files (constants, type aliases, bare re-exports) as skipped. Language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md` (python / rust / typescript / go / c / cpp / java). Single mechanical structural check. handoffs: [] --- # @pharaoh.api-coverage-check -Verify that every public symbol and every raise-site exception in a source file is covered by at least one need in `needs.json`. Reverse direction of `pharaoh-req-from-code` — language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md`; emits per-symbol and per-raise-site coverage plus a ratio against a tailored threshold. +Use when verifying that a source file is covered by the need catalogue on two axes — (1) at least one CREQ declares the file as its `:source_doc:`, and (2) every project-defined exception class raised in the file is named by some CREQ's title or content. Exception classes not defined in the project source tree (stdlib, third-party deps) are reported as `external` and do not fail the axis. Classifies non-behavioral files (constants, type aliases, bare re-exports) as skipped. Language-parametric via the shared regex table in `skills/shared/public-symbol-patterns.md` (python / rust / typescript / go / c / cpp / java). Single mechanical structural check. -See [`skills/pharaoh-api-coverage-check/SKILL.md`](../../skills/pharaoh-api-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, per-step process, failure modes, and composition patterns. +See [`skills/pharaoh-api-coverage-check/SKILL.md`](../../skills/pharaoh-api-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.arch-draft.agent.md b/.github/agents/pharaoh.arch-draft.agent.md index 36d408c..3f9b5e3 100644 --- a/.github/agents/pharaoh.arch-draft.agent.md +++ b/.github/agents/pharaoh.arch-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Draft a single sphinx-needs architecture element from one parent requirement. +description: Use when drafting a single sphinx-needs architecture element (component / interface / module) from one parent requirement. Emits an RST directive block linking back to the parent via :satisfies:. handoffs: [] --- # @pharaoh.arch-draft -Draft a single sphinx-needs architecture element from one parent requirement. +Use when drafting a single sphinx-needs architecture element (component / interface / module) from one parent requirement. Emits an RST directive block linking back to the parent via :satisfies:. See [`skills/pharaoh-arch-draft/SKILL.md`](../../skills/pharaoh-arch-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.arch-review.agent.md b/.github/agents/pharaoh.arch-review.agent.md index c46b8fb..ac6afb0 100644 --- a/.github/agents/pharaoh.arch-review.agent.md +++ b/.github/agents/pharaoh.arch-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single architecture element against ISO 26262-8 §6 axes. +description: Use when auditing a single architecture element against the 10 ISO 26262-8 §6 axes plus arch-specific axes (traceability back to requirement). Emits structured findings JSON. handoffs: [] --- # @pharaoh.arch-review -Audit a single architecture element against ISO 26262-8 §6 axes. +Use when auditing a single architecture element against the 10 ISO 26262-8 §6 axes plus arch-specific axes (traceability back to requirement). Emits structured findings JSON. See [`skills/pharaoh-arch-review/SKILL.md`](../../skills/pharaoh-arch-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.audit-fanout.agent.md b/.github/agents/pharaoh.audit-fanout.agent.md index e809101..c314f96 100644 --- a/.github/agents/pharaoh.audit-fanout.agent.md +++ b/.github/agents/pharaoh.audit-fanout.agent.md @@ -1,10 +1,10 @@ --- -description: Run a full project audit in parallel across atomic audit skills, sharing findings via Papyrus. +description: Use when running a full project audit in parallel by dispatching 5 atomic audit skills, each writing findings to a shared Papyrus workspace via pharaoh-finding-record for automatic deduplication. Emits the aggregated deduplicated findings list. handoffs: [] --- # @pharaoh.audit-fanout -Run a full project audit in parallel across atomic audit skills, sharing findings via Papyrus. +Use when running a full project audit in parallel by dispatching 5 atomic audit skills, each writing findings to a shared Papyrus workspace via pharaoh-finding-record for automatic deduplication. Emits the aggregated deduplicated findings list. See [`skills/pharaoh-audit-fanout/SKILL.md`](../../skills/pharaoh-audit-fanout/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.block-diagram-draft.agent.md b/.github/agents/pharaoh.block-diagram-draft.agent.md index 0436607..99e72ac 100644 --- a/.github/agents/pharaoh.block-diagram-draft.agent.md +++ b/.github/agents/pharaoh.block-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections. +description: Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections. Typical ASPICE usage — SYS.2/SYS.3 for system-level architecture, and SWE.2 for software architecture on SysML-heavy projects. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.block-diagram-draft -Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections. +Use when drafting one SysML-style block diagram — Block Definition Diagram (BDD) showing block structure and composition, or Internal Block Diagram (IBD) showing ports, flows, and part interconnections. Typical ASPICE usage — SYS.2/SYS.3 for system-level architecture, and SWE.2 for software architecture on SysML-heavy projects. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-block-diagram-draft/SKILL.md`](../../skills/pharaoh-block-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.bootstrap.agent.md b/.github/agents/pharaoh.bootstrap.agent.md index bca421a..213249a 100644 --- a/.github/agents/pharaoh.bootstrap.agent.md +++ b/.github/agents/pharaoh.bootstrap.agent.md @@ -1,5 +1,5 @@ --- -description: Inject minimum sphinx-needs configuration into an existing Sphinx project so sphinx-build produces a valid needs.json. +description: Use when a Sphinx project has no sphinx-needs configured and you need minimum viable scaffolding — adding the extension and declaring need types — so that sphinx-build produces a valid needs.json for downstream Pharaoh skills. handoffs: - label: Detect and scaffold Pharaoh agent: pharaoh.setup @@ -8,6 +8,6 @@ handoffs: # @pharaoh.bootstrap -Inject the minimum sphinx-needs configuration — extension entry, need types, optional extra links — into an existing Sphinx project that does not yet have sphinx-needs configured. Does not seed RST content, does not build, does not write `pharaoh.toml`. +Use when a Sphinx project has no sphinx-needs configured and you need minimum viable scaffolding — adding the extension and declaring need types — so that sphinx-build produces a valid needs.json for downstream Pharaoh skills. See [`skills/pharaoh-bootstrap/SKILL.md`](../../skills/pharaoh-bootstrap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.change.agent.md b/.github/agents/pharaoh.change.agent.md index 1ed8190..df8fdf3 100644 --- a/.github/agents/pharaoh.change.agent.md +++ b/.github/agents/pharaoh.change.agent.md @@ -1,5 +1,5 @@ --- -description: Analyze the impact of changing a requirement, specification, or any sphinx-needs item. Traces through all link types and codelinks to produce a Change Document. +description: Use when analyzing the impact of changing a requirement, specification, or any sphinx-needs item, including traceability to code via codelinks handoffs: - label: MECE Check agent: pharaoh.mece diff --git a/.github/agents/pharaoh.class-diagram-draft.agent.md b/.github/agents/pharaoh.class-diagram-draft.agent.md index 7eef840..5911999 100644 --- a/.github/agents/pharaoh.class-diagram-draft.agent.md +++ b/.github/agents/pharaoh.class-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). +description: Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.class-diagram-draft -Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). +Use when drafting one class diagram showing a bounded set of types/entities with their fields, methods, and relationships (inheritance, composition, aggregation, association). Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-class-diagram-draft/SKILL.md`](../../skills/pharaoh-class-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.component-diagram-draft.agent.md b/.github/agents/pharaoh.component-diagram-draft.agent.md index b0bea11..e4bf231 100644 --- a/.github/agents/pharaoh.component-diagram-draft.agent.md +++ b/.github/agents/pharaoh.component-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view. +description: Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view. Renderer tailored via `pharaoh.toml`. Does NOT emit sequence, class, or state diagrams — those are separate skills. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.component-diagram-draft -Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view. +Use when drafting one component-relationship diagram (nodes = sphinx-needs, edges = link relations) for a bounded scope — one feature, one module, one architectural view. Renderer tailored via `pharaoh.toml`. Does NOT emit sequence, class, or state diagrams — those are separate skills. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-component-diagram-draft/SKILL.md`](../../skills/pharaoh-component-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.context-gather.agent.md b/.github/agents/pharaoh.context-gather.agent.md index 24926d3..8f21d82 100644 --- a/.github/agents/pharaoh.context-gather.agent.md +++ b/.github/agents/pharaoh.context-gather.agent.md @@ -1,10 +1,10 @@ --- -description: Retrieve rationale memories from a Papyrus workspace before authoring or review. +description: Use when retrieving rationale memories relevant to an authoring context from a Papyrus workspace, before invoking any draft or review skill. Returns a structured list of memories (memory_id, text, relevance_score). Does NOT draft, review, or modify artefacts. handoffs: [] --- # @pharaoh.context-gather -Retrieve rationale memories from a Papyrus workspace before authoring or review. +Use when retrieving rationale memories relevant to an authoring context from a Papyrus workspace, before invoking any draft or review skill. Returns a structured list of memories (memory_id, text, relevance_score). Does NOT draft, review, or modify artefacts. See [`skills/pharaoh-context-gather/SKILL.md`](../../skills/pharaoh-context-gather/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.coverage-gap.agent.md b/.github/agents/pharaoh.coverage-gap.agent.md index ef820ca..b95341d 100644 --- a/.github/agents/pharaoh.coverage-gap.agent.md +++ b/.github/agents/pharaoh.coverage-gap.agent.md @@ -1,10 +1,10 @@ --- -description: Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle) in a sphinx-needs corpus. +description: Use when detecting one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) in a sphinx-needs corpus. Returns ordered list of needs falling into that gap. handoffs: [] --- # @pharaoh.coverage-gap -Detect one gap category (orphan / unverified / duplicate / contradictory / lifecycle) in a sphinx-needs corpus. +Use when detecting one gap category (orphan / unverified / duplicate / contradictory / lifecycle / ...) in a sphinx-needs corpus. Returns ordered list of needs falling into that gap. See [`skills/pharaoh-coverage-gap/SKILL.md`](../../skills/pharaoh-coverage-gap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.decide.agent.md b/.github/agents/pharaoh.decide.agent.md index 2b6938e..4e942fb 100644 --- a/.github/agents/pharaoh.decide.agent.md +++ b/.github/agents/pharaoh.decide.agent.md @@ -1,5 +1,5 @@ --- -description: Record a design decision as a traceable sphinx-needs object with alternatives, rationale, and links to affected requirements. +description: Use when recording a design decision as a traceable sphinx-needs object with alternatives, rationale, and links to affected requirements handoffs: - label: Trace Decision agent: pharaoh.trace diff --git a/.github/agents/pharaoh.decision-record.agent.md b/.github/agents/pharaoh.decision-record.agent.md index 6b6b044..c7cccc6 100644 --- a/.github/agents/pharaoh.decision-record.agent.md +++ b/.github/agents/pharaoh.decision-record.agent.md @@ -1,10 +1,10 @@ --- -description: Record a canonical decision, fact, or preference in the shared Papyrus workspace with (type, canonical_name) dedup. +description: Use when recording a canonical decision, fact, or preference in the shared Papyrus workspace with automatic dedup on (type, canonical_name). Returns {action: wrote|duplicate, papyrus_id}. Generalizes pharaoh-finding-record beyond audit findings. handoffs: [] --- # @pharaoh.decision-record -Record a canonical decision, fact, or preference in the shared Papyrus workspace with (type, canonical_name) dedup. +Use when recording a canonical decision, fact, or preference in the shared Papyrus workspace with automatic dedup on (type, canonical_name). Returns {action: wrote|duplicate, papyrus_id}. Generalizes pharaoh-finding-record beyond audit findings. See [`skills/pharaoh-decision-record/SKILL.md`](../../skills/pharaoh-decision-record/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.decision-review.agent.md b/.github/agents/pharaoh.decision-review.agent.md index e644a61..35d3bb0 100644 --- a/.github/agents/pharaoh.decision-review.agent.md +++ b/.github/agents/pharaoh.decision-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single recorded decision against context/alternatives/consequences structure and traceability. +description: Use when auditing a single recorded decision (DR / ADR / design note) against the generic decision review axes in `shared/checklists/decision.md`. Checks context/alternatives/consequences structure, traceability to affected artefacts, rationale completeness. Emits structured findings JSON. handoffs: [] --- # @pharaoh.decision-review -Audit a single recorded decision against context/alternatives/consequences structure and traceability. +Use when auditing a single recorded decision (DR / ADR / design note) against the generic decision review axes in `shared/checklists/decision.md`. Checks context/alternatives/consequences structure, traceability to affected artefacts, rationale completeness. Emits structured findings JSON. -See [`skills/pharaoh-decision-review/SKILL.md`](../../skills/pharaoh-decision-review/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-decision-review/SKILL.md`](../../skills/pharaoh-decision-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.deployment-diagram-draft.agent.md b/.github/agents/pharaoh.deployment-diagram-draft.agent.md index 8e99724..b35581c 100644 --- a/.github/agents/pharaoh.deployment-diagram-draft.agent.md +++ b/.github/agents/pharaoh.deployment-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). +description: Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). Typical ASPICE usage — SYS.3 System Architectural Design; essential for automotive HW/SW allocation per ISO 26262 Part 5 (HW) and Part 6 (SW). Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.deployment-diagram-draft -Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). +Use when drafting one deployment diagram showing physical nodes (ECUs, servers, boards), the software artefacts deployed on each, and communication channels (buses, networks). Typical ASPICE usage — SYS.3 System Architectural Design; essential for automotive HW/SW allocation per ISO 26262 Part 5 (HW) and Part 6 (SW). Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-deployment-diagram-draft/SKILL.md`](../../skills/pharaoh-deployment-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.diagram-lint.agent.md b/.github/agents/pharaoh.diagram-lint.agent.md index 4aa99bd..45014e4 100644 --- a/.github/agents/pharaoh.diagram-lint.agent.md +++ b/.github/agents/pharaoh.diagram-lint.agent.md @@ -1,5 +1,5 @@ --- -description: Walk a directory of RST files and check every `.. mermaid::` / `.. uml::` block against the real renderer parser (mmdc, plantuml). Catches silent parse failures that sphinx-build misses. +description: Use when running a terminal validation step over a directory of RST files to catch Mermaid / PlantUML parse failures that sphinx-build cannot detect. Extracts every `.. mermaid::` and `.. uml::` block and pipes it to the real renderer parser (mmdc / plantuml -checkonly). Returns structured findings. Does NOT modify the RST files. handoffs: - label: Aggregate into quality gate agent: pharaoh.quality-gate @@ -8,6 +8,6 @@ handoffs: # @pharaoh.diagram-lint -Walk a directory of RST files, extract every Mermaid / PlantUML block, and parse each block with the real renderer CLI (`mmdc -i tmp.mmd -o /dev/null`, `plantuml -checkonly`). Emits structured findings. Read-only — does not modify RST. When a renderer CLI is unavailable, degrades gracefully with a warning and install command. +Use when running a terminal validation step over a directory of RST files to catch Mermaid / PlantUML parse failures that sphinx-build cannot detect. Extracts every `.. mermaid::` and `.. uml::` block and pipes it to the real renderer parser (mmdc / plantuml -checkonly). Returns structured findings. Does NOT modify the RST files. See [`skills/pharaoh-diagram-lint/SKILL.md`](../../skills/pharaoh-diagram-lint/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.diagram-review.agent.md b/.github/agents/pharaoh.diagram-review.agent.md index 5b7d396..deb7695 100644 --- a/.github/agents/pharaoh.diagram-review.agent.md +++ b/.github/agents/pharaoh.diagram-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single diagram block (Mermaid or PlantUML) against generic + per-type axes. +description: Use when auditing a single diagram block (Mermaid or PlantUML) emitted by any diagram-emitting skill. Single review atom covering all diagram types — trace/caption/element-count/parser/required-elements checks plus LLM-judge axes for purpose clarity and granularity consistency. Per-type required-element checks dispatched based on `diagram_type` input. handoffs: [] --- # @pharaoh.diagram-review -Audit a single diagram block (Mermaid or PlantUML) against generic + per-type axes. +Use when auditing a single diagram block (Mermaid or PlantUML) emitted by any diagram-emitting skill. Single review atom covering all diagram types — trace/caption/element-count/parser/required-elements checks plus LLM-judge axes for purpose clarity and granularity consistency. Per-type required-element checks dispatched based on `diagram_type` input. -See [`skills/pharaoh-diagram-review/SKILL.md`](../../skills/pharaoh-diagram-review/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-diagram-review/SKILL.md`](../../skills/pharaoh-diagram-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.dispatch-signal-check.agent.md b/.github/agents/pharaoh.dispatch-signal-check.agent.md index 52d8c1e..60f80e4 100644 --- a/.github/agents/pharaoh.dispatch-signal-check.agent.md +++ b/.github/agents/pharaoh.dispatch-signal-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify declared execution_mode in plan.yaml matches observed artefacts in runs/. +description: Use when verifying that a plan's declared `execution_mode` matches observed subagent artefacts in `runs/`. Detects the "LLM-executor collapsed subagents into inline" failure class observed during dogfooding. One mechanical structural check. handoffs: [] --- # @pharaoh.dispatch-signal-check -Verify declared execution_mode in plan.yaml matches observed artefacts in runs/. +Use when verifying that a plan's declared `execution_mode` matches observed subagent artefacts in `runs/`. Detects the "LLM-executor collapsed subagents into inline" failure class observed during dogfooding. One mechanical structural check. -See [`skills/pharaoh-dispatch-signal-check/SKILL.md`](../../skills/pharaoh-dispatch-signal-check/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-dispatch-signal-check/SKILL.md`](../../skills/pharaoh-dispatch-signal-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.execute-plan.agent.md b/.github/agents/pharaoh.execute-plan.agent.md index 2c1cf46..2324022 100644 --- a/.github/agents/pharaoh.execute-plan.agent.md +++ b/.github/agents/pharaoh.execute-plan.agent.md @@ -1,10 +1,10 @@ --- -description: Use when executing a plan. +description: Use when executing a plan.yaml produced by pharaoh-write-plan. Reads the plan, runs each task (inline or via subagent dispatch), threads outputs between tasks per the ref grammar, validates outputs via pharaoh-output-validate, persists artefacts and report.yaml. Generic — the plan is the orchestrator, this skill is the engine. handoffs: [] --- # @pharaoh.execute-plan -Use when executing a plan. +Use when executing a plan.yaml produced by pharaoh-write-plan. Reads the plan, runs each task (inline or via subagent dispatch), threads outputs between tasks per the ref grammar, validates outputs via pharaoh-output-validate, persists artefacts and report.yaml. Generic — the plan is the orchestrator, this skill is the engine. See [`skills/pharaoh-execute-plan/SKILL.md`](../../skills/pharaoh-execute-plan/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md b/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md index e7ad53d..044a7ad 100644 --- a/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md +++ b/.github/agents/pharaoh.fault-tree-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one fault tree for FTA (Fault Tree Analysis) — a top hazard event decomposed through AND/OR gates into basic events (component failures, random hardware faults, human errors). +description: Use when drafting one fault tree for FTA (Fault Tree Analysis) — a top hazard event decomposed through AND/OR gates into basic events (component failures, random hardware faults, human errors). Typical ISO 26262 usage — Part 3 Hazard Analysis & Risk Assessment, and Part 5 supporting hardware architectural metrics. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.fault-tree-diagram-draft -Use when drafting one fault tree for FTA (Fault Tree Analysis) — a top hazard event decomposed through AND/OR gates into basic events (component failures, random hardware faults, human errors). +Use when drafting one fault tree for FTA (Fault Tree Analysis) — a top hazard event decomposed through AND/OR gates into basic events (component failures, random hardware faults, human errors). Typical ISO 26262 usage — Part 3 Hazard Analysis & Risk Assessment, and Part 5 supporting hardware architectural metrics. Renderer tailored via `pharaoh.toml`. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-fault-tree-diagram-draft/SKILL.md`](../../skills/pharaoh-fault-tree-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.feat-balance.agent.md b/.github/agents/pharaoh.feat-balance.agent.md index 3829768..fd28551 100644 --- a/.github/agents/pharaoh.feat-balance.agent.md +++ b/.github/agents/pharaoh.feat-balance.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a plan emitted by `pharaoh-write-plan` has completed its feature + comp_req emission and you need to check for granularity skew — features with too many reqs (under-decomposed feature model), too few (over-decomposed), fused sub-features (generic names like "utilities"), or redundancy (symmetric import/export pairs). +description: Use when a plan emitted by `pharaoh-write-plan` has completed its feature + comp_req emission and you need to check for granularity skew — features with too many reqs (under-decomposed feature model), too few (over-decomposed), fused sub-features (generic names like "utilities"), or redundancy (symmetric import/export pairs). Reports health and suggestions; does not mutate. handoffs: [] --- # @pharaoh.feat-balance -Use when a plan emitted by `pharaoh-write-plan` has completed its feature + comp_req emission and you need to check for granularity skew — features with too many reqs (under-decomposed feature model), too few (over-decomposed), fused sub-features (generic names like "utilities"), or redundancy (symmetric import/export pairs). +Use when a plan emitted by `pharaoh-write-plan` has completed its feature + comp_req emission and you need to check for granularity skew — features with too many reqs (under-decomposed feature model), too few (over-decomposed), fused sub-features (generic names like "utilities"), or redundancy (symmetric import/export pairs). Reports health and suggestions; does not mutate. See [`skills/pharaoh-feat-balance/SKILL.md`](../../skills/pharaoh-feat-balance/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.feat-component-extract.agent.md b/.github/agents/pharaoh.feat-component-extract.agent.md index c29c37e..b3db215 100644 --- a/.github/agents/pharaoh.feat-component-extract.agent.md +++ b/.github/agents/pharaoh.feat-component-extract.agent.md @@ -1,10 +1,10 @@ --- -description: Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files. +description: Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files. Walks import edges between the listed files and emits a Mermaid or PlantUML diagram whose output shape is compatible with pharaoh-component-diagram-draft. Does NOT hand-author nodes or edges; extraction is rule-based. handoffs: [] --- # @pharaoh.feat-component-extract -Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files. +Use when reverse-engineering a feat and you need to derive a component composition diagram automatically from the feat + its source files. Walks import edges between the listed files and emits a Mermaid or PlantUML diagram whose output shape is compatible with pharaoh-component-diagram-draft. Does NOT hand-author nodes or edges; extraction is rule-based. See [`skills/pharaoh-feat-component-extract/SKILL.md`](../../skills/pharaoh-feat-component-extract/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.feat-draft-from-docs.agent.md b/.github/agents/pharaoh.feat-draft-from-docs.agent.md index 63216a1..d2c4477 100644 --- a/.github/agents/pharaoh.feat-draft-from-docs.agent.md +++ b/.github/agents/pharaoh.feat-draft-from-docs.agent.md @@ -1,10 +1,10 @@ --- -description: Use when reading one or more existing documentation files (unstructured prose, README, tutorial) and emitting one or more feature-level RST directives (typed by `target_level`, default `feat`) that describe the user-facing capabilities documented in those files. +description: Use when reading one or more existing documentation files (unstructured prose, README, tutorial) and emitting one or more feature-level RST directives (typed by `target_level`, default `feat`) that describe the user-facing capabilities documented in those files. Does NOT read source code. Does NOT emit component requirements. Does NOT map features to files — that is `pharaoh-feat-file-map`. handoffs: [] --- # @pharaoh.feat-draft-from-docs -Use when reading one or more existing documentation files (unstructured prose, README, tutorial) and emitting one or more feature-level RST directives (typed by `target_level`, default `feat`) that describe the user-facing capabilities documented in those files. +Use when reading one or more existing documentation files (unstructured prose, README, tutorial) and emitting one or more feature-level RST directives (typed by `target_level`, default `feat`) that describe the user-facing capabilities documented in those files. Does NOT read source code. Does NOT emit component requirements. Does NOT map features to files — that is `pharaoh-feat-file-map`. See [`skills/pharaoh-feat-draft-from-docs/SKILL.md`](../../skills/pharaoh-feat-draft-from-docs/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.feat-file-map.agent.md b/.github/agents/pharaoh.feat-file-map.agent.md index 0680f3b..5726391 100644 --- a/.github/agents/pharaoh.feat-file-map.agent.md +++ b/.github/agents/pharaoh.feat-file-map.agent.md @@ -1,10 +1,10 @@ --- -description: Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. +description: Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. Reads the source tree, returns a YAML entry `{feat_id: {files: [...], rationale: "..."}}`. Does NOT read docs. Does NOT emit reqs. Does NOT create or modify source files. handoffs: [] --- # @pharaoh.feat-file-map -Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. +Use when mapping one feature (already emitted as an RST directive) to the source files that implement it. Reads the source tree, returns a YAML entry `{feat_id: {files: [...], rationale: "..."}}`. Does NOT read docs. Does NOT emit reqs. Does NOT create or modify source files. See [`skills/pharaoh-feat-file-map/SKILL.md`](../../skills/pharaoh-feat-file-map/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.feat-flow-extract.agent.md b/.github/agents/pharaoh.feat-flow-extract.agent.md index 444be70..5d9cc2d 100644 --- a/.github/agents/pharaoh.feat-flow-extract.agent.md +++ b/.github/agents/pharaoh.feat-flow-extract.agent.md @@ -1,10 +1,10 @@ --- -description: Use when reverse-engineering a feat and you need to derive a sequence diagram showing the control flow from its entry point through its source files. +description: Use when reverse-engineering a feat and you need to derive a sequence diagram showing the control flow from its entry point through its source files. Walks the call graph up to a bounded depth and emits a Mermaid or PlantUML sequence diagram whose output shape matches pharaoh-sequence-diagram-draft. Complements pharaoh-feat-component-extract (static view); this is the dynamic view. handoffs: [] --- # @pharaoh.feat-flow-extract -Use when reverse-engineering a feat and you need to derive a sequence diagram showing the control flow from its entry point through its source files. +Use when reverse-engineering a feat and you need to derive a sequence diagram showing the control flow from its entry point through its source files. Walks the call graph up to a bounded depth and emits a Mermaid or PlantUML sequence diagram whose output shape matches pharaoh-sequence-diagram-draft. Complements pharaoh-feat-component-extract (static view); this is the dynamic view. See [`skills/pharaoh-feat-flow-extract/SKILL.md`](../../skills/pharaoh-feat-flow-extract/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.feat-review.agent.md b/.github/agents/pharaoh.feat-review.agent.md index af64186..73e9d33 100644 --- a/.github/agents/pharaoh.feat-review.agent.md +++ b/.github/agents/pharaoh.feat-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single feature-level need against the generic feat review axes plus any project-specific addenda. +description: Use when auditing a single feature-level need (feat) against the generic feat review axes in `shared/checklists/feat.md` plus any per-project addenda in `.pharaoh/project/checklists/feat.md`. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes. Mirrors `pharaoh-req-review`'s shape for feat-level artefacts. handoffs: [] --- # @pharaoh.feat-review -Audit a single feature-level need against the generic feat review axes plus any project-specific addenda. +Use when auditing a single feature-level need (feat) against the generic feat review axes in `shared/checklists/feat.md` plus any per-project addenda in `.pharaoh/project/checklists/feat.md`. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes. Mirrors `pharaoh-req-review`'s shape for feat-level artefacts. -See [`skills/pharaoh-feat-review/SKILL.md`](../../skills/pharaoh-feat-review/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-feat-review/SKILL.md`](../../skills/pharaoh-feat-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.finding-record.agent.md b/.github/agents/pharaoh.finding-record.agent.md index 4da1519..35e2162 100644 --- a/.github/agents/pharaoh.finding-record.agent.md +++ b/.github/agents/pharaoh.finding-record.agent.md @@ -1,10 +1,10 @@ --- -description: Record an audit finding in the shared Papyrus workspace with deterministic dedup across concurrent subagents. +description: Use when recording an audit finding in the shared Papyrus workspace with automatic dedup. Uses deterministic ID to ensure the same {category, subject_id} tuple never appears twice across concurrent subagents. Returns {action: wrote|duplicate, papyrus_id}. handoffs: [] --- # @pharaoh.finding-record -Record an audit finding in the shared Papyrus workspace with deterministic dedup across concurrent subagents. +Use when recording an audit finding in the shared Papyrus workspace with automatic dedup. Uses deterministic ID to ensure the same {category, subject_id} tuple never appears twice across concurrent subagents. Returns {action: wrote|duplicate, papyrus_id}. See [`skills/pharaoh-finding-record/SKILL.md`](../../skills/pharaoh-finding-record/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.flow.agent.md b/.github/agents/pharaoh.flow.agent.md index f670320..ac61e8d 100644 --- a/.github/agents/pharaoh.flow.agent.md +++ b/.github/agents/pharaoh.flow.agent.md @@ -1,10 +1,10 @@ --- -description: Orchestrate the full V-model chain — requirement, architecture, verification plan, FMEA — with review passes. +description: Use when orchestrating the full V-model chain for one feature context — requirement → architecture element → verification plan → FMEA, each with a review pass. Invokes pharaoh-req-draft, pharaoh-req-review, pharaoh-arch-draft, pharaoh-arch-review, pharaoh-vplan-draft, pharaoh-vplan-review, pharaoh-fmea in sequence. handoffs: [] --- # @pharaoh.flow -Orchestrate the full V-model chain — requirement, architecture, verification plan, FMEA — with review passes. +Use when orchestrating the full V-model chain for one feature context — requirement → architecture element → verification plan → FMEA, each with a review pass. Invokes pharaoh-req-draft, pharaoh-req-review, pharaoh-arch-draft, pharaoh-arch-review, pharaoh-vplan-draft, pharaoh-vplan-review, pharaoh-fmea in sequence. See [`skills/pharaoh-flow/SKILL.md`](../../skills/pharaoh-flow/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.fmea-review.agent.md b/.github/agents/pharaoh.fmea-review.agent.md index 6768550..9f8c623 100644 --- a/.github/agents/pharaoh.fmea-review.agent.md +++ b/.github/agents/pharaoh.fmea-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single FMEA entry against severity/occurrence/detection scales, RPN correctness, and cause/effect well-formedness. +description: Use when auditing a single FMEA entry (failure-mode row) against the generic FMEA review axes in `shared/checklists/fmea.md` plus per-project addenda. Checks severity/occurrence/detection scales, RPN computation, cause/effect well-formedness, traceability to the analyzed artefact. Emits structured findings JSON. handoffs: [] --- # @pharaoh.fmea-review -Audit a single FMEA entry against severity/occurrence/detection scales, RPN correctness, and cause/effect well-formedness. +Use when auditing a single FMEA entry (failure-mode row) against the generic FMEA review axes in `shared/checklists/fmea.md` plus per-project addenda. Checks severity/occurrence/detection scales, RPN computation, cause/effect well-formedness, traceability to the analyzed artefact. Emits structured findings JSON. -See [`skills/pharaoh-fmea-review/SKILL.md`](../../skills/pharaoh-fmea-review/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-fmea-review/SKILL.md`](../../skills/pharaoh-fmea-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.fmea.agent.md b/.github/agents/pharaoh.fmea.agent.md index f990fa0..9b3f4b4 100644 --- a/.github/agents/pharaoh.fmea.agent.md +++ b/.github/agents/pharaoh.fmea.agent.md @@ -1,10 +1,10 @@ --- -description: Derive a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. +description: Use when deriving a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. Emits structured JSON with cause, effect, severity (1-10), occurrence (1-10), detection (1-10), and RPN. handoffs: [] --- # @pharaoh.fmea -Derive a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. +Use when deriving a single failure-mode entry (FMEA / DFA row) from one requirement or architecture element. Emits structured JSON with cause, effect, severity (1-10), occurrence (1-10), detection (1-10), and RPN. See [`skills/pharaoh-fmea/SKILL.md`](../../skills/pharaoh-fmea/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.gate-advisor.agent.md b/.github/agents/pharaoh.gate-advisor.agent.md index 4c9c63b..0991f5c 100644 --- a/.github/agents/pharaoh.gate-advisor.agent.md +++ b/.github/agents/pharaoh.gate-advisor.agent.md @@ -1,10 +1,10 @@ --- -description: Read a project's `pharaoh.toml` and report which phased-enablement ladder step is the recommended next gate to switch on. Advisory, read-only — walks the fixed 5-step ladder in order (`require_verification` → `require_change_analysis` → `require_mece_on_release` → `codelinks.enabled` → `strictness = "enforcing"`) and names the first unmet step plus its blocker. +description: Use when reading a project's `pharaoh.toml` to report which phased-enablement ladder step is the recommended next gate to switch on. Single mechanical advisory check — parses five flags (`strictness`, `require_verification`, `require_change_analysis`, `require_mece_on_release`, `codelinks.enabled`), walks the fixed ladder in order, and emits the first unmet step plus its blocker note. Read-only; never edits `pharaoh.toml`. handoffs: [] --- # @pharaoh.gate-advisor -Read the project's `pharaoh.toml`, parse the five ladder flags, and emit a findings JSON naming the next recommended gate to enable, the blocker that must be cleared first, and the full fixed ladder. Read-only; never edits `pharaoh.toml`. The ladder rationale lives in [`skills/shared/gate-enablement.md`](../../skills/shared/gate-enablement.md) — this atom is the tool that walks it, not the authority that defines it. +Use when reading a project's `pharaoh.toml` to report which phased-enablement ladder step is the recommended next gate to switch on. Single mechanical advisory check — parses five flags (`strictness`, `require_verification`, `require_change_analysis`, `require_mece_on_release`, `codelinks.enabled`), walks the fixed ladder in order, and emits the first unmet step plus its blocker note. Read-only; never edits `pharaoh.toml`. -See [`skills/pharaoh-gate-advisor/SKILL.md`](../../skills/pharaoh-gate-advisor/SKILL.md) for the full atomic specification — inputs, outputs, per-step process, ladder table, rationale map, tailoring extension point, and composition patterns. +See [`skills/pharaoh-gate-advisor/SKILL.md`](../../skills/pharaoh-gate-advisor/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.id-allocate.agent.md b/.github/agents/pharaoh.id-allocate.agent.md index c2d23d7..bb80390 100644 --- a/.github/agents/pharaoh.id-allocate.agent.md +++ b/.github/agents/pharaoh.id-allocate.agent.md @@ -1,10 +1,10 @@ --- -description: Use when about to dispatch a fan-out of emission subagents (pharaoh-req-from-code, pharaoh-feat-draft-from-docs) and you need to pre-allocate globally-unique sphinx-needs IDs. +description: Use when about to dispatch a fan-out of emission subagents (pharaoh-req-from-code, pharaoh-feat-draft-from-docs) and you need to pre-allocate globally-unique sphinx-needs IDs. Each subagent receives its pre-allocated pool and emits only from that pool, so parallel agents cannot collide on stem choice. Does NOT invoke emitters, does NOT write RST. handoffs: [] --- # @pharaoh.id-allocate -Use when about to dispatch a fan-out of emission subagents (pharaoh-req-from-code, pharaoh-feat-draft-from-docs) and you need to pre-allocate globally-unique sphinx-needs IDs. +Use when about to dispatch a fan-out of emission subagents (pharaoh-req-from-code, pharaoh-feat-draft-from-docs) and you need to pre-allocate globally-unique sphinx-needs IDs. Each subagent receives its pre-allocated pool and emits only from that pool, so parallel agents cannot collide on stem choice. Does NOT invoke emitters, does NOT write RST. See [`skills/pharaoh-id-allocate/SKILL.md`](../../skills/pharaoh-id-allocate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.id-convention-check.agent.md b/.github/agents/pharaoh.id-convention-check.agent.md index d2af8bf..f8e2ff2 100644 --- a/.github/agents/pharaoh.id-convention-check.agent.md +++ b/.github/agents/pharaoh.id-convention-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify that every need id in a sphinx-needs corpus matches the regex declared for its type in .pharaoh/project/id-conventions.yaml. Emits a list of violations. +description: Use when verifying that every need id in a sphinx-needs corpus matches the regex declared for its type in `.pharaoh/project/id-conventions.yaml`. Single mechanical structural check — applies the tailored per-type regex, emits a list of violations. Does NOT auto-detect how many schemes coexist — scheme policy is the tailoring author's responsibility (declare an alternation to allow multiple forms). handoffs: [] --- # @pharaoh.id-convention-check -Verify that every need id in a sphinx-needs corpus matches the regex declared for its type in `.pharaoh/project/id-conventions.yaml`. Emits a list of violations. +Use when verifying that every need id in a sphinx-needs corpus matches the regex declared for its type in `.pharaoh/project/id-conventions.yaml`. Single mechanical structural check — applies the tailored per-type regex, emits a list of violations. Does NOT auto-detect how many schemes coexist — scheme policy is the tailoring author's responsibility (declare an alternation to allow multiple forms). -See [`skills/pharaoh-id-convention-check/SKILL.md`](../../skills/pharaoh-id-convention-check/SKILL.md) for the full atomic specification — inputs, outputs, detection rule, and composition patterns. +See [`skills/pharaoh-id-convention-check/SKILL.md`](../../skills/pharaoh-id-convention-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.lifecycle-check.agent.md b/.github/agents/pharaoh.lifecycle-check.agent.md index 9122660..b7474ef 100644 --- a/.github/agents/pharaoh.lifecycle-check.agent.md +++ b/.github/agents/pharaoh.lifecycle-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify a sphinx-needs artefact's lifecycle state and the legality of a requested state transition. +description: Use when verifying a sphinx-needs artefact's current lifecycle state and the legality of a requested state transition per the project's workflows.yaml state machine. handoffs: [] --- # @pharaoh.lifecycle-check -Verify a sphinx-needs artefact's lifecycle state and the legality of a requested state transition. +Use when verifying a sphinx-needs artefact's current lifecycle state and the legality of a requested state transition per the project's workflows.yaml state machine. See [`skills/pharaoh-lifecycle-check/SKILL.md`](../../skills/pharaoh-lifecycle-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.link-completeness-check.agent.md b/.github/agents/pharaoh.link-completeness-check.agent.md index e067e80..6d91804 100644 --- a/.github/agents/pharaoh.link-completeness-check.agent.md +++ b/.github/agents/pharaoh.link-completeness-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify outgoing-link coverage across a full needs.json graph against required/optional link types declared per artefact type in artefact-catalog.yaml — missing required links, unresolved target ids, per-type policy enforcement. +description: Use when verifying outgoing-link coverage across a full needs.json graph. For each declared link type in `artefact-catalog.yaml`, confirms every need of the governed type carries a non-empty value AND every target id resolves to an existing need. Closes the "catalogue declares `verifies` required but half the reqs ship without it" failure class. handoffs: [] --- # @pharaoh.link-completeness-check -Verify outgoing-link coverage across a full needs.json graph against required/optional link types declared per artefact type in `artefact-catalog.yaml` — missing required links, unresolved target ids, per-type policy enforcement. +Use when verifying outgoing-link coverage across a full needs.json graph. For each declared link type in `artefact-catalog.yaml`, confirms every need of the governed type carries a non-empty value AND every target id resolves to an existing need. Closes the "catalogue declares `verifies` required but half the reqs ship without it" failure class. -See [`skills/pharaoh-link-completeness-check/SKILL.md`](../../skills/pharaoh-link-completeness-check/SKILL.md) for the full atomic specification — inputs, outputs, per-pass detection rules, and composition patterns. +See [`skills/pharaoh-link-completeness-check/SKILL.md`](../../skills/pharaoh-link-completeness-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.mece.agent.md b/.github/agents/pharaoh.mece.agent.md index 1c5e41c..ec4d116 100644 --- a/.github/agents/pharaoh.mece.agent.md +++ b/.github/agents/pharaoh.mece.agent.md @@ -1,5 +1,5 @@ --- -description: Check for gaps, redundancies, and inconsistencies in sphinx-needs requirements. Validates traceability completeness. +description: Use when checking for gaps, redundancies, and inconsistencies in sphinx-needs requirements, or validating traceability completeness handoffs: - label: Trace a Need agent: pharaoh.trace diff --git a/.github/agents/pharaoh.output-validate.agent.md b/.github/agents/pharaoh.output-validate.agent.md index 331ad1f..bfa1914 100644 --- a/.github/agents/pharaoh.output-validate.agent.md +++ b/.github/agents/pharaoh.output-validate.agent.md @@ -1,10 +1,10 @@ --- -description: Use when `pharaoh-execute-plan` (or any caller) has dispatched a subagent whose output must match one of the documented schemas (RST directive, sphinx-codelinks one-line comment, YAML mapping, JSON object). +description: Use when `pharaoh-execute-plan` (or any caller) has dispatched a subagent whose output must match one of the documented schemas (RST directive, sphinx-codelinks one-line comment, YAML mapping, JSON object). Returns {valid, errors, parsed, recovery}. Callers gate subagent output through this before writing anything to disk. handoffs: [] --- # @pharaoh.output-validate -Use when `pharaoh-execute-plan` (or any caller) has dispatched a subagent whose output must match one of the documented schemas (RST directive, sphinx-codelinks one-line comment, YAML mapping, JSON object). +Use when `pharaoh-execute-plan` (or any caller) has dispatched a subagent whose output must match one of the documented schemas (RST directive, sphinx-codelinks one-line comment, YAML mapping, JSON object). Returns {valid, errors, parsed, recovery}. Callers gate subagent output through this before writing anything to disk. See [`skills/pharaoh-output-validate/SKILL.md`](../../skills/pharaoh-output-validate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.papyrus-non-empty-check.agent.md b/.github/agents/pharaoh.papyrus-non-empty-check.agent.md index 4e02bf7..712d563 100644 --- a/.github/agents/pharaoh.papyrus-non-empty-check.agent.md +++ b/.github/agents/pharaoh.papyrus-non-empty-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify that a Papyrus workspace received at least N writes during a plan run. +description: Use when verifying that a Papyrus workspace actually received writes during a plan run. Single mechanical check — counts directives across `.papyrus/memory/*.rst` and returns pass/fail against a configured minimum. Wired into `pharaoh-quality-gate` to detect the "LLM-executor skipped the atomic Papyrus writes" failure class observed in prior dogfooding. handoffs: [] --- # @pharaoh.papyrus-non-empty-check -Verify that a Papyrus workspace received at least N writes during a plan run. +Use when verifying that a Papyrus workspace actually received writes during a plan run. Single mechanical check — counts directives across `.papyrus/memory/*.rst` and returns pass/fail against a configured minimum. Wired into `pharaoh-quality-gate` to detect the "LLM-executor skipped the atomic Papyrus writes" failure class observed in prior dogfooding. See [`skills/pharaoh-papyrus-non-empty-check/SKILL.md`](../../skills/pharaoh-papyrus-non-empty-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.plan.agent.md b/.github/agents/pharaoh.plan.agent.md index 8ec0bb7..db2b52f 100644 --- a/.github/agents/pharaoh.plan.agent.md +++ b/.github/agents/pharaoh.plan.agent.md @@ -1,5 +1,5 @@ --- -description: Break requirement changes into structured implementation tasks with workflow enforcement and dependency ordering. +description: Use when breaking requirement changes into structured implementation tasks with workflow enforcement and dependency ordering handoffs: - label: Start Change Analysis agent: pharaoh.change diff --git a/.github/agents/pharaoh.process-audit.agent.md b/.github/agents/pharaoh.process-audit.agent.md index 69e01de..3911cc0 100644 --- a/.github/agents/pharaoh.process-audit.agent.md +++ b/.github/agents/pharaoh.process-audit.agent.md @@ -1,10 +1,10 @@ --- -description: Run a full-corpus audit across all gap categories plus cross-artefact consistency checks. +description: Use when running a full-corpus audit against a sphinx-needs project. Orchestrates pharaoh-coverage-gap across all gap categories plus cross-artefact consistency checks. Emits a prioritised gap report. handoffs: [] --- # @pharaoh.process-audit -Run a full-corpus audit across all gap categories plus cross-artefact consistency checks. +Use when running a full-corpus audit against a sphinx-needs project. Orchestrates pharaoh-coverage-gap across all gap categories plus cross-artefact consistency checks. Emits a prioritised gap report. See [`skills/pharaoh-process-audit/SKILL.md`](../../skills/pharaoh-process-audit/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.prose-migrate.agent.md b/.github/agents/pharaoh.prose-migrate.agent.md index db1ab43..de450d1 100644 --- a/.github/agents/pharaoh.prose-migrate.agent.md +++ b/.github/agents/pharaoh.prose-migrate.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a reverse-engineering run (a plan emitted by pharaoh-write-plan) finds pre-existing prose documentation files in the target output directory that would collide with generated feat RST files. +description: Use when a reverse-engineering run (a plan emitted by pharaoh-write-plan) finds pre-existing prose documentation files in the target output directory that would collide with generated feat RST files. Produces a sentence-by-sentence migration proposal — keep-as-user-guide, merge-into-feat-body, discard. Does NOT overwrite anything; the caller applies the proposal manually. handoffs: [] --- # @pharaoh.prose-migrate -Use when a reverse-engineering run (a plan emitted by pharaoh-write-plan) finds pre-existing prose documentation files in the target output directory that would collide with generated feat RST files. +Use when a reverse-engineering run (a plan emitted by pharaoh-write-plan) finds pre-existing prose documentation files in the target output directory that would collide with generated feat RST files. Produces a sentence-by-sentence migration proposal — keep-as-user-guide, merge-into-feat-body, discard. Does NOT overwrite anything; the caller applies the proposal manually. See [`skills/pharaoh-prose-migrate/SKILL.md`](../../skills/pharaoh-prose-migrate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.quality-gate.agent.md b/.github/agents/pharaoh.quality-gate.agent.md index 95a52fc..d500423 100644 --- a/.github/agents/pharaoh.quality-gate.agent.md +++ b/.github/agents/pharaoh.quality-gate.agent.md @@ -1,10 +1,10 @@ --- -description: Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). +description: Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). Consumes an aggregated review+mece+coverage summary plus a gate spec; returns pass/fail with named breaches. Never produces summaries itself — thin gate layer over upstream atomic checkers. handoffs: [] --- # @pharaoh.quality-gate -Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). +Use when running the final validation step of any Pharaoh composition that emits artefacts (reqs, features, architecture elements). Consumes an aggregated review+mece+coverage summary plus a gate spec; returns pass/fail with named breaches. Never produces summaries itself — thin gate layer over upstream atomic checkers. See [`skills/pharaoh-quality-gate/SKILL.md`](../../skills/pharaoh-quality-gate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.release.agent.md b/.github/agents/pharaoh.release.agent.md index 03d131c..089e004 100644 --- a/.github/agents/pharaoh.release.agent.md +++ b/.github/agents/pharaoh.release.agent.md @@ -1,5 +1,5 @@ --- -description: Prepare a release by generating changelogs from requirements, release summaries, and traceability coverage metrics. +description: Use when preparing a release, generating changelogs from requirements, or summarizing requirement changes for version management handoffs: - label: MECE Check agent: pharaoh.mece diff --git a/.github/agents/pharaoh.reproducibility-check.agent.md b/.github/agents/pharaoh.reproducibility-check.agent.md index ee77bd2..a42da34 100644 --- a/.github/agents/pharaoh.reproducibility-check.agent.md +++ b/.github/agents/pharaoh.reproducibility-check.agent.md @@ -1,10 +1,10 @@ --- -description: Diff two output directories produced by two runs of the same plan to confirm the build is reproducible. Consumes baseline dir, rerun dir, and optional mask rules for non-deterministic fields (timestamps, random ids); emits drifted-file list with per-file changed-field summaries. Does NOT run the plan — that is the caller's responsibility (`pharaoh-execute-plan`). +description: Use when diffing two output directories produced by running the same plan twice to confirm the build is reproducible. Consumes a baseline directory, a rerun directory, and an optional list of mask rules for known-non-deterministic fields (timestamps, randomly-generated ids); emits a list of drifted files with per-file changed-field summaries. Does NOT run the plan — running is the caller's responsibility (`pharaoh-execute-plan`). handoffs: [] --- # @pharaoh.reproducibility-check -Diff two output directories produced by running the same plan twice to confirm the build is reproducible. Consumes a baseline directory, a rerun directory, and an optional list of mask rules for known-non-deterministic fields (timestamps, randomly-generated ids); emits a list of drifted files with per-file changed-field summaries. Does NOT run the plan — running twice is the caller's responsibility (`pharaoh-execute-plan`). +Use when diffing two output directories produced by running the same plan twice to confirm the build is reproducible. Consumes a baseline directory, a rerun directory, and an optional list of mask rules for known-non-deterministic fields (timestamps, randomly-generated ids); emits a list of drifted files with per-file changed-field summaries. Does NOT run the plan — running is the caller's responsibility (`pharaoh-execute-plan`). -See [`skills/pharaoh-reproducibility-check/SKILL.md`](../../skills/pharaoh-reproducibility-check/SKILL.md) for the full atomic specification — inputs, outputs, per-step process, failure modes, and composition patterns. +See [`skills/pharaoh-reproducibility-check/SKILL.md`](../../skills/pharaoh-reproducibility-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-code-grounding-check.agent.md b/.github/agents/pharaoh.req-code-grounding-check.agent.md index f188291..c8d4075 100644 --- a/.github/agents/pharaoh.req-code-grounding-check.agent.md +++ b/.github/agents/pharaoh.req-code-grounding-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify a drafted requirement's claims against the source file it cites via :source_doc: — exception raise sites, trigger conditions, type-framework imports, named symbols, weasel adjectives, quantifier enumeration, branch count. +description: Use when verifying a single drafted requirement against the source file it cites via `:source_doc:`. Single mechanical fidelity check — compares the CREQ's claims about exceptions, triggers, types, structural symbols, backtick-quoted identifiers, grounding density, adjectives, quantifiers, and branch count against the cited source, returning per-axis findings JSON. Complements `pharaoh-req-review` (which grades prose quality) with code-grounded axes. handoffs: [] --- # @pharaoh.req-code-grounding-check -Verify a drafted requirement's claims against the source file it cites via `:source_doc:` — exception raise sites, trigger conditions, type-framework imports, named symbols, weasel adjectives, quantifier enumeration, branch count. +Use when verifying a single drafted requirement against the source file it cites via `:source_doc:`. Single mechanical fidelity check — compares the CREQ's claims about exceptions, triggers, types, structural symbols, backtick-quoted identifiers, grounding density, adjectives, quantifiers, and branch count against the cited source, returning per-axis findings JSON. Complements `pharaoh-req-review` (which grades prose quality) with code-grounded axes. -See [`skills/pharaoh-req-code-grounding-check/SKILL.md`](../../skills/pharaoh-req-code-grounding-check/SKILL.md) for the full atomic specification — inputs, outputs, per-axis detection rules, and composition patterns. +See [`skills/pharaoh-req-code-grounding-check/SKILL.md`](../../skills/pharaoh-req-code-grounding-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-codelink-annotate.agent.md b/.github/agents/pharaoh.req-codelink-annotate.agent.md index 004eb8c..c4f79b1 100644 --- a/.github/agents/pharaoh.req-codelink-annotate.agent.md +++ b/.github/agents/pharaoh.req-codelink-annotate.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. +description: Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. Two modes — `codelinks` (sphinx-codelinks-compatible multi-field `@ title, id, type, [links]` form; the comment IS the need) and `backref` (minimal `@req ID: title` pointer back to an RST-hosted need). Mode is tailored via `ubproject.toml` / `pharaoh.toml`, not hardcoded. handoffs: [] --- # @pharaoh.req-codelink-annotate -Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. +Use when a requirement has been drafted (either as an RST block by `pharaoh-req-from-code` or implicitly) and you need to insert a one-line comment into the source file that carries the trace. Two modes — `codelinks` (sphinx-codelinks-compatible multi-field `@ title, id, type, [links]` form; the comment IS the need) and `backref` (minimal `@req ID: title` pointer back to an RST-hosted need). Mode is tailored via `ubproject.toml` / `pharaoh.toml`, not hardcoded. See [`skills/pharaoh-req-codelink-annotate/SKILL.md`](../../skills/pharaoh-req-codelink-annotate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-draft.agent.md b/.github/agents/pharaoh.req-draft.agent.md index 0c56ffd..1e34763 100644 --- a/.github/agents/pharaoh.req-draft.agent.md +++ b/.github/agents/pharaoh.req-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Draft a single sphinx-needs requirement from a feature description. +description: Use when drafting a single sphinx-needs requirement from a feature description. Produces a new RST directive block with ID, status=draft, and a single shall-clause body, linking to a parent requirement or workflow per the project's artefact-catalog. handoffs: [] --- # @pharaoh.req-draft -Draft a single sphinx-needs requirement from a feature description. +Use when drafting a single sphinx-needs requirement from a feature description. Produces a new RST directive block with ID, status=draft, and a single shall-clause body, linking to a parent requirement or workflow per the project's artefact-catalog. See [`skills/pharaoh-req-draft/SKILL.md`](../../skills/pharaoh-req-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-from-code.agent.md b/.github/agents/pharaoh.req-from-code.agent.md index 848345a..9e7bb93 100644 --- a/.github/agents/pharaoh.req-from-code.agent.md +++ b/.github/agents/pharaoh.req-from-code.agent.md @@ -1,10 +1,10 @@ --- -description: Read one source file and emit comp_req directives describing its observable behavior, coordinating canonical names via Papyrus. +description: Use when reading one source file and emitting one or more requirement RST directives (typed by `target_level`) describing the observable behavior in that file. Queries shared Papyrus for canonical terms before naming concepts; writes newly surfaced concepts back. Does not draft architecture, plans, or FMEA. handoffs: [] --- # @pharaoh.req-from-code -Read one source file and emit comp_req directives describing its observable behavior, coordinating canonical names via Papyrus. +Use when reading one source file and emitting one or more requirement RST directives (typed by `target_level`) describing the observable behavior in that file. Queries shared Papyrus for canonical terms before naming concepts; writes newly surfaced concepts back. Does not draft architecture, plans, or FMEA. See [`skills/pharaoh-req-from-code/SKILL.md`](../../skills/pharaoh-req-from-code/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-regenerate.agent.md b/.github/agents/pharaoh.req-regenerate.agent.md index e0d48e9..28f7407 100644 --- a/.github/agents/pharaoh.req-regenerate.agent.md +++ b/.github/agents/pharaoh.req-regenerate.agent.md @@ -1,10 +1,10 @@ --- -description: Regenerate a single sphinx-needs requirement to address findings from a prior review. +description: Use when regenerating a single sphinx-needs requirement to address findings from pharaoh-req-review. Consumes the original RST + findings JSON, emits a revised RST directive that passes the flagged axes. handoffs: [] --- # @pharaoh.req-regenerate -Regenerate a single sphinx-needs requirement to address findings from a prior review. +Use when regenerating a single sphinx-needs requirement to address findings from pharaoh-req-review. Consumes the original RST + findings JSON, emits a revised RST directive that passes the flagged axes. See [`skills/pharaoh-req-regenerate/SKILL.md`](../../skills/pharaoh-req-regenerate/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.req-review.agent.md b/.github/agents/pharaoh.req-review.agent.md index f33ff28..dabf554 100644 --- a/.github/agents/pharaoh.req-review.agent.md +++ b/.github/agents/pharaoh.req-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single sphinx-needs requirement against the ISO 26262 Part 8 §6 axes. +description: Use when auditing a single sphinx-needs requirement against the 11 ISO 26262 Part 8 §6 axes. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes, with action items for any failure. handoffs: [] --- # @pharaoh.req-review -Audit a single sphinx-needs requirement against the ISO 26262 Part 8 §6 axes. +Use when auditing a single sphinx-needs requirement against the 11 ISO 26262 Part 8 §6 axes. Emits structured findings JSON — per-axis pass/fail for mechanized axes, 0-3 score for subjective axes, with action items for any failure. See [`skills/pharaoh-req-review/SKILL.md`](../../skills/pharaoh-req-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.review-completeness.agent.md b/.github/agents/pharaoh.review-completeness.agent.md index 2873634..df8be0e 100644 --- a/.github/agents/pharaoh.review-completeness.agent.md +++ b/.github/agents/pharaoh.review-completeness.agent.md @@ -1,10 +1,10 @@ --- -description: Inspect needs for review / approval-chain completeness; flag missing reviewer / approved_by fields. +description: Use when inspecting one or more needs for review / approval-chain completeness. Flags needs missing required :reviewer: or :approved_by: fields per the project's artefact catalog. Emits one finding per incomplete need via pharaoh-finding-record. handoffs: [] --- # @pharaoh.review-completeness -Inspect needs for review / approval-chain completeness; flag missing reviewer / approved_by fields. +Use when inspecting one or more needs for review / approval-chain completeness. Flags needs missing required :reviewer: or :approved_by: fields per the project's artefact catalog. Emits one finding per incomplete need via pharaoh-finding-record. See [`skills/pharaoh-review-completeness/SKILL.md`](../../skills/pharaoh-review-completeness/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.self-review-coverage-check.agent.md b/.github/agents/pharaoh.self-review-coverage-check.agent.md index 92beffa..e93ca48 100644 --- a/.github/agents/pharaoh.self-review-coverage-check.agent.md +++ b/.github/agents/pharaoh.self-review-coverage-check.agent.md @@ -1,10 +1,10 @@ --- -description: Verify every drafted artefact in runs/ has a matching review JSON. +description: Use when verifying that every artefact emitted during a plan run received a matching review. For every drafted artefact in `runs/`, confirms a matching `_review.json` exists and is non-empty. Closes the "draft emitted but review was skipped" failure class. handoffs: [] --- # @pharaoh.self-review-coverage-check -Verify every drafted artefact in runs/ has a matching review JSON. +Use when verifying that every artefact emitted during a plan run received a matching review. For every drafted artefact in `runs/`, confirms a matching `_review.json` exists and is non-empty. Closes the "draft emitted but review was skipped" failure class. -See [`skills/pharaoh-self-review-coverage-check/SKILL.md`](../../skills/pharaoh-self-review-coverage-check/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-self-review-coverage-check/SKILL.md`](../../skills/pharaoh-self-review-coverage-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.sequence-diagram-draft.agent.md b/.github/agents/pharaoh.sequence-diagram-draft.agent.md index 6fd0ae8..666e39c 100644 --- a/.github/agents/pharaoh.sequence-diagram-draft.agent.md +++ b/.github/agents/pharaoh.sequence-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. +description: Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. Renderer tailored via `pharaoh.toml`. Does NOT emit component, class, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.sequence-diagram-draft -Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. +Use when drafting one sequence diagram showing ordered interactions between participants (components, actors, external systems) over time. Renderer tailored via `pharaoh.toml`. Does NOT emit component, class, or state diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-sequence-diagram-draft/SKILL.md`](../../skills/pharaoh-sequence-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.setup.agent.md b/.github/agents/pharaoh.setup.agent.md index 9ff2517..e72a89e 100644 --- a/.github/agents/pharaoh.setup.agent.md +++ b/.github/agents/pharaoh.setup.agent.md @@ -1,5 +1,5 @@ --- -description: Scaffold Pharaoh into a sphinx-needs project. Detects project structure, generates pharaoh.toml, installs Copilot agents, and recommends tooling. +description: Use when setting up Pharaoh in a sphinx-needs project for the first time, scaffolding Copilot agents, or reconfiguring project detection handoffs: - label: Run MECE Check agent: pharaoh.mece @@ -67,7 +67,26 @@ Data access: ### Step 3: Configure .gitignore -Add `.pharaoh/` to `.gitignore` if not already present. Create `.gitignore` if needed. +`.pharaoh/` contains a mix of committed tailoring and ephemeral run state. Ignoring the whole tree is wrong — it hides `.pharaoh/project/` tailoring which IS shared across the team. Ignore only the ephemeral subpaths: + +| Path | Purpose | Commit? | +| ----------------------- | -------------------------------------------------------- | ------- | +| `.pharaoh/project/` | Tailoring: workflows, id-conventions, artefact-catalog, checklists | **yes** | +| `.pharaoh/runs/` | `pharaoh-execute-plan` run artefacts (report.yaml, staged RST) | no | +| `.pharaoh/plans/` | plan.yaml files emitted by `pharaoh-write-plan` | no | +| `.pharaoh/session.json` | Session / gate state | no | +| `.pharaoh/cache/` | Derived caches | no | + +Entries to add (create `.gitignore` if missing): + +``` +.pharaoh/runs/ +.pharaoh/plans/ +.pharaoh/session.json +.pharaoh/cache/ +``` + +If `.gitignore` already contains a bare `.pharaoh/` (or `.pharaoh`) line, leave it alone and warn the user that the wide form hides `.pharaoh/project/` tailoring which should be committed; recommend narrowing to the four ephemeral entries above. Do not auto-migrate — respect user control. ### Step 4: Recommend Tooling diff --git a/.github/agents/pharaoh.spec.agent.md b/.github/agents/pharaoh.spec.agent.md index 13e89a8..a3b87b5 100644 --- a/.github/agents/pharaoh.spec.agent.md +++ b/.github/agents/pharaoh.spec.agent.md @@ -1,5 +1,5 @@ --- -description: Generate a Superpowers-compatible spec and plan document from sphinx-needs requirements, bridging requirements to implementation. +description: Use when generating a Superpowers-compatible spec and plan document from sphinx-needs requirements, bridging requirements to implementation handoffs: - label: Execute Plan agent: pharaoh.plan diff --git a/.github/agents/pharaoh.sphinx-extension-add.agent.md b/.github/agents/pharaoh.sphinx-extension-add.agent.md index 67ceb53..9f9e20c 100644 --- a/.github/agents/pharaoh.sphinx-extension-add.agent.md +++ b/.github/agents/pharaoh.sphinx-extension-add.agent.md @@ -1,10 +1,10 @@ --- -description: Idempotently add one or more sphinx extension modules to a project's `conf.py` extensions list, optionally installing the corresponding pypi packages via the detected package manager. +description: Use when you need to idempotently add one or more sphinx extension modules to a project's `conf.py` extensions list, optionally installing the corresponding pypi packages via the detected package manager. Invoked by plans produced by pharaoh-write-plan when a diagram-emitting task requires a renderer extension that `conf.py` does not yet load. Does NOT emit RST. Does NOT build. handoffs: [] --- # @pharaoh.sphinx-extension-add -Add sphinx extensions (e.g. `sphinxcontrib.mermaid`, `sphinxcontrib.plantuml`, `myst_parser`) to a project's `conf.py` extensions list. Idempotent: noop when all requested extensions are already loaded. Optionally installs the corresponding pypi packages via the detected package manager (rye / uv / poetry / pdm / pip-venv). Typically inserted into a plan by `pharaoh.write-plan` as a prerequisite to diagram-emitting tasks when `conf.py` lacks the required renderer extension. +Use when you need to idempotently add one or more sphinx extension modules to a project's `conf.py` extensions list, optionally installing the corresponding pypi packages via the detected package manager. Invoked by plans produced by pharaoh-write-plan when a diagram-emitting task requires a renderer extension that `conf.py` does not yet load. Does NOT emit RST. Does NOT build. See [`skills/pharaoh-sphinx-extension-add/SKILL.md`](../../skills/pharaoh-sphinx-extension-add/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.standard-conformance.agent.md b/.github/agents/pharaoh.standard-conformance.agent.md index 17ea5f7..ae0163c 100644 --- a/.github/agents/pharaoh.standard-conformance.agent.md +++ b/.github/agents/pharaoh.standard-conformance.agent.md @@ -1,10 +1,10 @@ --- -description: Evaluate a single artefact against one regulatory standard (ISO 26262, ASPICE, ISO/SAE 21434). +description: Use when evaluating a single sphinx-needs artefact against one regulatory standard (ISO 26262-8 §6, ASPICE 4.0, ISO/SAE 21434). Emits per-indicator findings JSON with pass/fail on mechanizable indicators and 0-3 scores on subjective ones. handoffs: [] --- # @pharaoh.standard-conformance -Evaluate a single artefact against one regulatory standard (ISO 26262, ASPICE, ISO/SAE 21434). +Use when evaluating a single sphinx-needs artefact against one regulatory standard (ISO 26262-8 §6, ASPICE 4.0, ISO/SAE 21434). Emits per-indicator findings JSON with pass/fail on mechanizable indicators and 0-3 scores on subjective ones. See [`skills/pharaoh-standard-conformance/SKILL.md`](../../skills/pharaoh-standard-conformance/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.state-diagram-draft.agent.md b/.github/agents/pharaoh.state-diagram-draft.agent.md index 652dc24..ec261c4 100644 --- a/.github/agents/pharaoh.state-diagram-draft.agent.md +++ b/.github/agents/pharaoh.state-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. +description: Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or class diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). handoffs: [] --- # @pharaoh.state-diagram-draft -Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. +Use when drafting one state-machine diagram showing lifecycle or behavioral states of a component/entity, with labeled transitions. Renderer tailored via `pharaoh.toml`. Does NOT emit component, sequence, or class diagrams. Status — PLANNED (design-only scaffold; invoking returns sentinel FAIL until implemented). See [`skills/pharaoh-state-diagram-draft/SKILL.md`](../../skills/pharaoh-state-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.status-lifecycle-check.agent.md b/.github/agents/pharaoh.status-lifecycle-check.agent.md index 935ba38..f04f403 100644 --- a/.github/agents/pharaoh.status-lifecycle-check.agent.md +++ b/.github/agents/pharaoh.status-lifecycle-check.agent.md @@ -1,5 +1,5 @@ --- -description: Release-gate check over a sphinx-needs corpus — counts needs still in the `draft` bucket (per workflows.yaml) and returns binary pass/fail when `enforce=true`. Advisory mode reports counts without failing. +description: Use when running a release-gate check over a full sphinx-needs corpus to confirm that zero needs remain in the initial `draft` status. Single mechanical binary gate — aggregates `status` across every need in `needs.json`, compares against the initial-state declaration in `workflows.yaml`, and returns pass/fail plus per-status counts. Advisory by default (pre-release development passes); release pipelines override `enforce=true` so any draft blocks the gate. handoffs: - label: Aggregate into quality gate agent: pharaoh.quality-gate @@ -8,6 +8,6 @@ handoffs: # @pharaoh.status-lifecycle-check -Aggregate `status` across every need in `needs.json` against the `initial_state` declared in `workflows.yaml`. Binary release gate — under `enforce=true`, zero drafts pass, one draft fails. Under `enforce=false` (default), the findings are reported without failing so pre-release development is unblocked. Distinct from `pharaoh-lifecycle-check`, which evaluates per-need transition legality against `requires:` prerequisites. +Use when running a release-gate check over a full sphinx-needs corpus to confirm that zero needs remain in the initial `draft` status. Single mechanical binary gate — aggregates `status` across every need in `needs.json`, compares against the initial-state declaration in `workflows.yaml`, and returns pass/fail plus per-status counts. Advisory by default (pre-release development passes); release pipelines override `enforce=true` so any draft blocks the gate. See [`skills/pharaoh-status-lifecycle-check/SKILL.md`](../../skills/pharaoh-status-lifecycle-check/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-bootstrap.agent.md b/.github/agents/pharaoh.tailor-bootstrap.agent.md index fc6465e..2e37a48 100644 --- a/.github/agents/pharaoh.tailor-bootstrap.agent.md +++ b/.github/agents/pharaoh.tailor-bootstrap.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows. +description: Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows.yaml, id-conventions.yaml, artefact-catalog.yaml, and per-type checklists — without requiring any needs to exist. Complements pharaoh-tailor-detect which requires ≥10 needs. handoffs: [] --- # @pharaoh.tailor-bootstrap -Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows. +Use when a sphinx-needs project has just been bootstrapped (post pharaoh-bootstrap, pre any needs authoring) and you need to generate minimal tailoring files from declared types — workflows.yaml, id-conventions.yaml, artefact-catalog.yaml, and per-type checklists — without requiring any needs to exist. Complements pharaoh-tailor-detect which requires ≥10 needs. See [`skills/pharaoh-tailor-bootstrap/SKILL.md`](../../skills/pharaoh-tailor-bootstrap/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md b/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md index b17d90c..f2f5bb6 100644 --- a/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md +++ b/.github/agents/pharaoh.tailor-code-grounding-filters.agent.md @@ -1,10 +1,10 @@ --- -description: Detect language + CLI framework + config-default idiom in a project source tree and emit a code-grounding-filters.yaml wiring the four parameterised filter strategies to the detected stack. +description: Use when authoring a project's `code-grounding-filters.yaml` from observed stack conventions. Detects language + CLI framework + config-object style in the project source tree and emits a tailoring YAML populated with the four parameterised filter strategies. Does not invoke `pharaoh-req-code-grounding-check`; purely produces tailoring. handoffs: [] --- # @pharaoh.tailor-code-grounding-filters -Detect language + CLI framework + config-default idiom in a project source tree and emit a code-grounding-filters.yaml wiring the four parameterised filter strategies to the detected stack. +Use when authoring a project's `code-grounding-filters.yaml` from observed stack conventions. Detects language + CLI framework + config-object style in the project source tree and emits a tailoring YAML populated with the four parameterised filter strategies. Does not invoke `pharaoh-req-code-grounding-check`; purely produces tailoring. See [`skills/pharaoh-tailor-code-grounding-filters/SKILL.md`](../../skills/pharaoh-tailor-code-grounding-filters/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-detect.agent.md b/.github/agents/pharaoh.tailor-detect.agent.md index 233a42d..680f063 100644 --- a/.github/agents/pharaoh.tailor-detect.agent.md +++ b/.github/agents/pharaoh.tailor-detect.agent.md @@ -1,10 +1,10 @@ --- -description: Inspect a sphinx-needs project and emit a structured report of detected conventions. +description: Use when inspecting a sphinx-needs project to emit a structured report of detected conventions — prefixes, ID regex candidates, separator, lifecycle states, artefact types with observed required/optional fields. Does NOT author tailoring files (see pharaoh-tailor-fill). handoffs: [] --- # @pharaoh.tailor-detect -Inspect a sphinx-needs project and emit a structured report of detected conventions. +Use when inspecting a sphinx-needs project to emit a structured report of detected conventions — prefixes, ID regex candidates, separator, lifecycle states, artefact types with observed required/optional fields. Does NOT author tailoring files (see pharaoh-tailor-fill). See [`skills/pharaoh-tailor-detect/SKILL.md`](../../skills/pharaoh-tailor-detect/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-fill.agent.md b/.github/agents/pharaoh.tailor-fill.agent.md index 92f35f3..11afcd1 100644 --- a/.github/agents/pharaoh.tailor-fill.agent.md +++ b/.github/agents/pharaoh.tailor-fill.agent.md @@ -1,10 +1,10 @@ --- -description: Author .pharaoh/project/ tailoring files from a detected-conventions report. +description: Use when authoring the .pharaoh/project/ tailoring files (id-conventions.yaml, workflows.yaml, artefact-catalog.yaml, checklists/requirement.md) from detected-conventions JSON produced by pharaoh-tailor-detect. handoffs: [] --- # @pharaoh.tailor-fill -Author .pharaoh/project/ tailoring files from a detected-conventions report. +Use when authoring the .pharaoh/project/ tailoring files (id-conventions.yaml, workflows.yaml, artefact-catalog.yaml, checklists/requirement.md) from detected-conventions JSON produced by pharaoh-tailor-detect. See [`skills/pharaoh-tailor-fill/SKILL.md`](../../skills/pharaoh-tailor-fill/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.tailor-review.agent.md b/.github/agents/pharaoh.tailor-review.agent.md index 2a2abff..30a5d4e 100644 --- a/.github/agents/pharaoh.tailor-review.agent.md +++ b/.github/agents/pharaoh.tailor-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit .pharaoh/project/ tailoring files against JSON schemas and cross-file consistency. +description: Use when auditing .pharaoh/project/ tailoring files against JSON schemas (id-conventions, workflows, artefact-catalog, checklists frontmatter) plus cross-file consistency checks (every lifecycle state referenced in artefact-catalog exists in workflows.yaml, every prefix in artefact-catalog is declared in id-conventions, etc.). handoffs: [] --- # @pharaoh.tailor-review -Audit .pharaoh/project/ tailoring files against JSON schemas and cross-file consistency. +Use when auditing .pharaoh/project/ tailoring files against JSON schemas (id-conventions, workflows, artefact-catalog, checklists frontmatter) plus cross-file consistency checks (every lifecycle state referenced in artefact-catalog exists in workflows.yaml, every prefix in artefact-catalog is declared in id-conventions, etc.). See [`skills/pharaoh-tailor-review/SKILL.md`](../../skills/pharaoh-tailor-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.toctree-emit.agent.md b/.github/agents/pharaoh.toctree-emit.agent.md index 3aa35f5..1532bdb 100644 --- a/.github/agents/pharaoh.toctree-emit.agent.md +++ b/.github/agents/pharaoh.toctree-emit.agent.md @@ -1,10 +1,10 @@ --- -description: Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index. +description: Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index.rst` with a Sphinx toctree over them. Prevents orphan-file warnings under `sphinx-build -W`. Does NOT modify the emitted RST files. Does NOT wire the emitted directory into any parent toctree — that is a caller concern. handoffs: [] --- # @pharaoh.toctree-emit -Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index. +Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index.rst` with a Sphinx toctree over them. Prevents orphan-file warnings under `sphinx-build -W`. Does NOT modify the emitted RST files. Does NOT wire the emitted directory into any parent toctree — that is a caller concern. See [`skills/pharaoh-toctree-emit/SKILL.md`](../../skills/pharaoh-toctree-emit/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.trace.agent.md b/.github/agents/pharaoh.trace.agent.md index b6c4ba8..095c023 100644 --- a/.github/agents/pharaoh.trace.agent.md +++ b/.github/agents/pharaoh.trace.agent.md @@ -1,5 +1,5 @@ --- -description: Navigate traceability links between requirements, specifications, implementations, tests, and code in any direction. +description: Use when navigating traceability links between requirements, specifications, implementations, tests, and code in a sphinx-needs project handoffs: - label: Analyze Impact agent: pharaoh.change diff --git a/.github/agents/pharaoh.use-case-diagram-draft.agent.md b/.github/agents/pharaoh.use-case-diagram-draft.agent.md index 59255eb..a32fd11 100644 --- a/.github/agents/pharaoh.use-case-diagram-draft.agent.md +++ b/.github/agents/pharaoh.use-case-diagram-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Draft a single use-case diagram for one feat — actors, use cases, system boundary. +description: Use when drafting one use-case diagram for a single feat — actors (primary, secondary, external systems), use cases (one per user-facing capability), and system boundary. Renderer-aware (mermaid or plantuml per `.pharaoh/project/diagram-conventions.yaml`). First concrete `*-diagram-draft` skill — others follow the same shape. handoffs: [pharaoh.diagram-review] --- # @pharaoh.use-case-diagram-draft -Draft a single use-case diagram for one feat — actors, use cases, system boundary. +Use when drafting one use-case diagram for a single feat — actors (primary, secondary, external systems), use cases (one per user-facing capability), and system boundary. Renderer-aware (mermaid or plantuml per `.pharaoh/project/diagram-conventions.yaml`). First concrete `*-diagram-draft` skill — others follow the same shape. -See [`skills/pharaoh-use-case-diagram-draft/SKILL.md`](../../skills/pharaoh-use-case-diagram-draft/SKILL.md) for the full atomic specification. +See [`skills/pharaoh-use-case-diagram-draft/SKILL.md`](../../skills/pharaoh-use-case-diagram-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.vplan-draft.agent.md b/.github/agents/pharaoh.vplan-draft.agent.md index 2b1b828..037c33c 100644 --- a/.github/agents/pharaoh.vplan-draft.agent.md +++ b/.github/agents/pharaoh.vplan-draft.agent.md @@ -1,10 +1,10 @@ --- -description: Draft a single sphinx-needs test-case (verification plan item) for one requirement. +description: Use when drafting a single sphinx-needs test-case (verification plan item) for one requirement. Emits an RST tc__ directive with inputs, steps, and expected outcome, linking to the parent req via :verifies:. handoffs: [] --- # @pharaoh.vplan-draft -Draft a single sphinx-needs test-case (verification plan item) for one requirement. +Use when drafting a single sphinx-needs test-case (verification plan item) for one requirement. Emits an RST tc__ directive with inputs, steps, and expected outcome, linking to the parent req via :verifies:. See [`skills/pharaoh-vplan-draft/SKILL.md`](../../skills/pharaoh-vplan-draft/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.vplan-review.agent.md b/.github/agents/pharaoh.vplan-review.agent.md index af3d327..e01ddbf 100644 --- a/.github/agents/pharaoh.vplan-review.agent.md +++ b/.github/agents/pharaoh.vplan-review.agent.md @@ -1,10 +1,10 @@ --- -description: Audit a single test case against ISO 26262-8 §6 axes plus vplan-specific axes. +description: Use when auditing a single test case against ISO 26262-8 §6 axes plus vplan-specific axes (coverage of parent req, completeness of steps, clarity of expected outcome). Emits structured findings JSON. handoffs: [] --- # @pharaoh.vplan-review -Audit a single test case against ISO 26262-8 §6 axes plus vplan-specific axes. +Use when auditing a single test case against ISO 26262-8 §6 axes plus vplan-specific axes (coverage of parent req, completeness of steps, clarity of expected outcome). Emits structured findings JSON. See [`skills/pharaoh-vplan-review/SKILL.md`](../../skills/pharaoh-vplan-review/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/agents/pharaoh.write-plan.agent.md b/.github/agents/pharaoh.write-plan.agent.md index 934c18d..a9584a4 100644 --- a/.github/agents/pharaoh.write-plan.agent.md +++ b/.github/agents/pharaoh.write-plan.agent.md @@ -1,10 +1,10 @@ --- -description: Use when you have an intent (e. +description: Use when you have an intent (e.g. "reverse-engineer features and reqs from this module") and need a concrete plan.yaml that pharaoh-execute-plan can run. Picks a plan template by intent, fills project-specific values, emits a plan that validates against schema.md. Does NOT execute anything. handoffs: [] --- # @pharaoh.write-plan -Use when you have an intent (e. +Use when you have an intent (e.g. "reverse-engineer features and reqs from this module") and need a concrete plan.yaml that pharaoh-execute-plan can run. Picks a plan template by intent, fills project-specific values, emits a plan that validates against schema.md. Does NOT execute anything. See [`skills/pharaoh-write-plan/SKILL.md`](../../skills/pharaoh-write-plan/SKILL.md) for the full atomic specification — inputs, outputs, atomicity contract, and composition patterns. diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 5eca926..fd61e50 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -85,6 +85,28 @@ jobs: status=1 fi + # Detect truncation artefacts in description: unbalanced parens, + # brackets, or backticks render as broken Markdown in Copilot UIs + # (see issue #12 — pharaoh.write-plan and pharaoh.toctree-emit). + description=$(echo "$frontmatter" | sed -n 's/^description:[[:space:]]*//p') + opens=$(echo -n "$description" | tr -cd '(' | wc -c) + closes=$(echo -n "$description" | tr -cd ')' | wc -c) + if [ "$opens" -ne "$closes" ]; then + echo "ERROR: $agent_file 'description' has unbalanced parentheses ($opens '(' vs $closes ')')" + status=1 + fi + obrack=$(echo -n "$description" | tr -cd '[' | wc -c) + cbrack=$(echo -n "$description" | tr -cd ']' | wc -c) + if [ "$obrack" -ne "$cbrack" ]; then + echo "ERROR: $agent_file 'description' has unbalanced brackets ($obrack '[' vs $cbrack ']')" + status=1 + fi + ticks=$(echo -n "$description" | tr -cd '`' | wc -c) + if [ $((ticks % 2)) -ne 0 ]; then + echo "ERROR: $agent_file 'description' has unbalanced backticks ($ticks total)" + status=1 + fi + echo "OK: $agent_file" done exit $status From 5baab70e1e37c3ae0eab5c0c26fc9ea003664bb7 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 16:12:37 +0200 Subject: [PATCH 03/15] cleanup: drop dangling pharaoh-arch-regenerate references Removes six references in pharaoh-arch-review/SKILL.md and one in pharaoh-arch-draft/SKILL.md to a planned-but-never-implemented pharaoh-arch-regenerate skill: chains_from list, prose handoff hints, and three deferred rubric axes. Re-authoring after review is a follow-up step outside the review skill's scope. If we later want regenerate symmetry between req and arch (i.e. ship pharaoh-arch-regenerate as a sibling to pharaoh-req-regenerate), that is a separate PR. Closes part of #13 (section 6). --- skills/pharaoh-arch-draft/SKILL.md | 2 +- skills/pharaoh-arch-review/SKILL.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/skills/pharaoh-arch-draft/SKILL.md b/skills/pharaoh-arch-draft/SKILL.md index cc7c4fe..22520d2 100644 --- a/skills/pharaoh-arch-draft/SKILL.md +++ b/skills/pharaoh-arch-draft/SKILL.md @@ -294,6 +294,6 @@ Consider running `pharaoh-arch-review arch__abs_pump_driver` to audit against IS ## Last step -After emitting the artefact, invoke `pharaoh-arch-review` on it. Pass the emitted artefact (or its `need_id`) as `target`. Attach the returned review JSON to the skill's output under the key `review`. If the review emits any axis with `score: 0` or `severity: critical`, return a non-success status with the review findings verbatim and do NOT finalize the artefact — the caller must regenerate (via `pharaoh-arch-regenerate` if available, or by re-invoking this skill with the findings as input). +After emitting the artefact, invoke `pharaoh-arch-review` on it. Pass the emitted artefact (or its `need_id`) as `target`. Attach the returned review JSON to the skill's output under the key `review`. If the review emits any axis with `score: 0` or `severity: critical`, return a non-success status with the review findings verbatim and do NOT finalize the artefact — the caller must address the action items and re-invoke this skill with the revised target as input. See [`shared/self-review-invariant.md`](../shared/self-review-invariant.md) for the rationale and enforcement mechanism. Coverage is mechanically enforced by `pharaoh-self-review-coverage-check` in `pharaoh-quality-gate`. diff --git a/skills/pharaoh-arch-review/SKILL.md b/skills/pharaoh-arch-review/SKILL.md index 6b3f3cd..f2ca681 100644 --- a/skills/pharaoh-arch-review/SKILL.md +++ b/skills/pharaoh-arch-review/SKILL.md @@ -1,7 +1,7 @@ --- name: pharaoh-arch-review description: Use when auditing a single architecture element against the 10 ISO 26262-8 §6 axes plus arch-specific axes (traceability back to requirement). Emits structured findings JSON. -chains_from: [pharaoh-arch-draft, pharaoh-arch-regenerate] +chains_from: [pharaoh-arch-draft] chains_to: [pharaoh-req-regenerate] --- @@ -13,7 +13,7 @@ Invoke when the user has a single architecture element (either just drafted by ` or retrieved from needs.json by ID) and wants per-axis inspection against ISO 26262-8 §6. Do NOT review sets of arch elements — each invocation audits exactly one element. -Do NOT re-author or fix — invoke `pharaoh-arch-regenerate` (planned) after reviewing if needed. +Do NOT re-author or fix — emit findings only. Re-authoring is a follow-up step outside this skill's scope. Do NOT audit requirements — use `pharaoh-req-review` for those. --- @@ -89,7 +89,7 @@ In the output JSON, record each as ### Chain-level axis `maintainability` requires observing convergence across regeneration iterations. Record as -`{"score": null, "reason": "chain-level axis — assess after pharaoh-arch-regenerate runs"}`. +`{"score": null, "reason": "chain-level axis — assess after the parent requirement and architecture revisions land"}`. ### `overall` field @@ -199,7 +199,7 @@ elements (score 1), normal engineering effort (score 2), or tightly and clearly Set `completeness`, `external_consistency`, `no_duplication` to `{"score": "deferred", "reason": "set-level axis — assess with pharaoh-arch-set-review"}` and `maintainability` to -`{"score": null, "reason": "chain-level axis — assess after pharaoh-arch-regenerate runs"}`. +`{"score": null, "reason": "chain-level axis — assess after the parent requirement and architecture revisions land"}`. --- @@ -257,7 +257,7 @@ Continue evaluating remaining axes. If `overall` is `"needs_work"` or `"fail"`, append — after the JSON — a single line: ``` -Consider `pharaoh-arch-regenerate ` after addressing action items. +Re-run this review after action items are addressed to confirm the findings clear. ``` This is the only prose permitted after the JSON. @@ -310,7 +310,7 @@ This is the only prose permitted after the JSON. "completeness": {"score": "deferred", "reason": "set-level axis — assess with pharaoh-arch-set-review"}, "external_consistency": {"score": "deferred", "reason": "set-level axis — assess with pharaoh-arch-set-review"}, "no_duplication": {"score": "deferred", "reason": "set-level axis — assess with pharaoh-arch-set-review"}, - "maintainability": {"score": null, "reason": "chain-level axis — assess after pharaoh-arch-regenerate runs"}, + "maintainability": {"score": null, "reason": "chain-level axis — assess after the parent requirement and architecture revisions land"}, "unambiguity_prose": {"score": 3, "reason": "single clear interpretation: manages pump drive circuit"}, "comprehensibility": {"score": 3, "reason": "subject, responsibility, and constraints all explicit"}, "feasibility": {"score": 3, "reason": "standard automotive power electronics function; well-constrained"} From 2b04defd2c379b4be38c50ba0b1f0ff837e20529 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 16:17:29 +0200 Subject: [PATCH 04/15] arch-review: fix grammar in advisory-chain reminder "Confirm the findings clear" parses as a sentence missing a verb; "confirm the findings are resolved" reads cleanly. Caught in PR review. --- skills/pharaoh-arch-review/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/pharaoh-arch-review/SKILL.md b/skills/pharaoh-arch-review/SKILL.md index f2ca681..3561758 100644 --- a/skills/pharaoh-arch-review/SKILL.md +++ b/skills/pharaoh-arch-review/SKILL.md @@ -257,7 +257,7 @@ Continue evaluating remaining axes. If `overall` is `"needs_work"` or `"fail"`, append — after the JSON — a single line: ``` -Re-run this review after action items are addressed to confirm the findings clear. +Re-run this review after action items are addressed to confirm the findings are resolved. ``` This is the only prose permitted after the JSON. From df64b7c7a35e9ff90da8b651b7e3de9e0689437a Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 16:28:16 +0200 Subject: [PATCH 05/15] feat(skills): add pharaoh-author and pharaoh-verify user-entry skills Implements the two user-entry slash commands @pharaoh.author and @pharaoh.verify that copilot-instructions.md documents as canonical steps in the workflow chain (@pharaoh.plan -> @pharaoh.change -> @pharaoh.author -> @pharaoh.verify -> @pharaoh.release). Both were dead before: prompt files only carried agent-frontmatter pointing at agent files that did not exist, while ~26 live references in 6 sibling agent.md files plus copilot-instructions.md called into them. pharaoh-author is a type-routing orchestrator over the existing atomic drafting skills (pharaoh-req-draft, pharaoh-arch-draft, pharaoh-vplan- draft, pharaoh-decide). Dispatch entries for pharaoh-arch-draft and pharaoh-vplan-draft are deliberately thin passthroughs -- a follow-up in this PR will update them once those skills' interfaces are parameterized. pharaoh-verify is a content-level satisfaction checker -- given a need-id, walks the :satisfies: chain and evaluates whether the child addresses the parent's substance. Distinct from pharaoh-mece (structural), pharaoh-req-review (per-axis rubric), and pharaoh-tailor-review (schema-level). Closes part of #13 (section 5). --- .github/agents/pharaoh.author.agent.md | 19 ++ .github/agents/pharaoh.verify.agent.md | 19 ++ .github/prompts/pharaoh.author.prompt.md | 20 ++ .github/prompts/pharaoh.verify.prompt.md | 19 ++ skills/pharaoh-author/SKILL.md | 291 ++++++++++++++++++++ skills/pharaoh-verify/SKILL.md | 330 +++++++++++++++++++++++ 6 files changed, 698 insertions(+) create mode 100644 .github/agents/pharaoh.author.agent.md create mode 100644 .github/agents/pharaoh.verify.agent.md create mode 100644 skills/pharaoh-author/SKILL.md create mode 100644 skills/pharaoh-verify/SKILL.md diff --git a/.github/agents/pharaoh.author.agent.md b/.github/agents/pharaoh.author.agent.md new file mode 100644 index 0000000..e1a8e7c --- /dev/null +++ b/.github/agents/pharaoh.author.agent.md @@ -0,0 +1,19 @@ +--- +description: Use when authoring or modifying a single sphinx-needs artefact (requirement, architecture element, test case, decision) by routing to the matching atomic drafting skill based on the project's artefact catalog. Returns the drafted RST directive with an ID, file placement suggestion, and parent link. +handoffs: + - label: Verify Authored Need + agent: pharaoh.verify + prompt: Check that the authored artefact addresses the substance of its parent + - label: Review Drafted Requirement + agent: pharaoh.req-review + prompt: Audit the drafted requirement against the ISO 26262 §6 axes + - label: Trace the Authored Need + agent: pharaoh.trace + prompt: Trace the new artefact through all link types +--- + +# @pharaoh.author + +Use when authoring or modifying a single sphinx-needs artefact (requirement, architecture element, test case, decision) by routing to the matching atomic drafting skill based on the project's artefact catalog. Returns the drafted RST directive with an ID, file placement suggestion, and parent link. + +See [`skills/pharaoh-author/SKILL.md`](../../skills/pharaoh-author/SKILL.md) for the full atomic specification — inputs, dispatch table, and composition patterns. diff --git a/.github/agents/pharaoh.verify.agent.md b/.github/agents/pharaoh.verify.agent.md new file mode 100644 index 0000000..f02b890 --- /dev/null +++ b/.github/agents/pharaoh.verify.agent.md @@ -0,0 +1,19 @@ +--- +description: Use when checking whether one sphinx-needs artefact actually addresses the substance of every parent it links to via :satisfies: or :verifies:. Cross-need content check — distinct from structural MECE, schema-level tailor-review, and per-axis req-review/arch-review. +handoffs: + - label: MECE Check + agent: pharaoh.mece + prompt: Run a structural gap-and-orphan analysis around the verified need + - label: Trace the Need + agent: pharaoh.trace + prompt: Trace the verified need through every link type + - label: Re-author the Need + agent: pharaoh.author + prompt: Revise the body to address the missing parent claims +--- + +# @pharaoh.verify + +Use when checking whether one sphinx-needs artefact actually addresses the substance of every parent it links to via :satisfies: or :verifies:. Cross-need content check — distinct from structural MECE, schema-level tailor-review, and per-axis req-review/arch-review. + +See [`skills/pharaoh-verify/SKILL.md`](../../skills/pharaoh-verify/SKILL.md) for the full atomic specification — inputs, scoring scale, and composition patterns. diff --git a/.github/prompts/pharaoh.author.prompt.md b/.github/prompts/pharaoh.author.prompt.md index f8a06dd..1234b39 100644 --- a/.github/prompts/pharaoh.author.prompt.md +++ b/.github/prompts/pharaoh.author.prompt.md @@ -1,3 +1,23 @@ --- agent: pharaoh.author --- + +# /pharaoh.author + +Author or modify one sphinx-needs artefact — a requirement, an architecture element, a test +case, or a decision — by routing to the right atomic drafting skill based on the project's +artefact catalog. One invocation produces one drafted RST directive with an ID, a parent link, +and a suggested file placement. + +Hand the agent: + +- the **target type** (e.g. `req`, `arch`, `tc`, `decision`), +- a short **draft seed** describing what to author, +- the **parent link** the new artefact will trace to (need-id), and +- any type-specific extras the dispatched drafter needs (e.g. `arch_type`, + `verification_level`). + +The agent picks the matching atomic drafter (`pharaoh-req-draft`, `pharaoh-arch-draft`, +`pharaoh-vplan-draft`, or `pharaoh-decide`), forwards the inputs, and returns the drafted RST +directive plus an authoring summary. Run `@pharaoh.verify` next to check the new artefact +against the substance of its parent. diff --git a/.github/prompts/pharaoh.verify.prompt.md b/.github/prompts/pharaoh.verify.prompt.md index 1726175..57d5ee9 100644 --- a/.github/prompts/pharaoh.verify.prompt.md +++ b/.github/prompts/pharaoh.verify.prompt.md @@ -1,3 +1,22 @@ --- agent: pharaoh.verify --- + +# /pharaoh.verify + +Check whether one sphinx-needs artefact actually addresses the substance of every parent it +links to via `:satisfies:` or `:verifies:`. This is a cross-need content check — distinct from +structural MECE (`@pharaoh.mece`), schema-level tailoring review (`@pharaoh.tailor-review`), +and per-axis prose review (`@pharaoh.req-review`, `@pharaoh.arch-review`, +`@pharaoh.vplan-review`). + +Hand the agent: + +- the **need-id** to verify, and +- optionally `transitive: true` to walk the full parent chain rather than just direct parents. + +The agent reads `needs.json`, walks the parent links, scores each (child, parent) pair on a +0-3 ordinal for substantive coverage, and returns a JSON document with per-pair verdicts and +concrete missing aspects. Use the result to decide whether to re-author the body via +`@pharaoh.author`, regenerate it per-axis via `@pharaoh.req-regenerate`, or move on to a +corpus-wide check with `@pharaoh.mece`. diff --git a/skills/pharaoh-author/SKILL.md b/skills/pharaoh-author/SKILL.md new file mode 100644 index 0000000..d4f906b --- /dev/null +++ b/skills/pharaoh-author/SKILL.md @@ -0,0 +1,291 @@ +--- +name: pharaoh-author +description: Use when authoring or modifying a single sphinx-needs artefact (requirement, architecture element, test case, decision) by routing to the matching atomic drafting skill based on the project's artefact catalog. Returns the drafted RST directive with an ID, file placement suggestion, and parent link. +chains_from: [pharaoh-change, pharaoh-plan, pharaoh-spec] +chains_to: [pharaoh-verify] +--- + +# pharaoh-author + +## When to use + +Invoke when the user wants to create or modify one sphinx-needs artefact (one need per call) +and needs the right atomic drafting skill picked for them based on the artefact type. + +This skill is a thin type-router. It does not author content itself — it dispatches to one of +the atomic drafting skills (`pharaoh-req-draft`, `pharaoh-arch-draft`, `pharaoh-vplan-draft`, +`pharaoh-decide`) and forwards their RST output verbatim, plus a file-placement hint and the +parent link. + +Do NOT use when: + +- The user wants the full V-model chain in one call — use `pharaoh-flow`. +- The user wants to draft multiple artefacts at once — invoke this skill once per artefact. +- The user wants to review or verify content — use `pharaoh-req-review`, `pharaoh-arch-review`, + or `pharaoh-verify` instead. + +> This is a compositional orchestrator. The atomicity criterion (a) does not apply: by design +> it dispatches to one atomic skill. Scope is bounded to "one artefact → one drafted directive". + +--- + +## Inputs + +- **target_type** (from user or inferred): the artefact type to draft. Recognised values come + from `.pharaoh/project/artefact-catalog.yaml`. Common values: `req`, `gd_req`, `arch`, + `tc`, `decision`. Synonyms are tolerated — e.g. `requirement` → `req`/`gd_req`, + `architecture` / `spec` → `arch`, `test_case` / `verification` → `tc`. +- **target_id** (optional): if the user is modifying an existing need, the need-id to update. + When absent, the dispatched drafter generates a fresh ID. +- **draft_seed** (from user): short prose describing what to author. Forwarded as + `feature_context` / `element_description` / parent claim depending on the dispatch target. +- **parent_link** (from user, required for everything except top-level requirements and + decisions): the need-id this artefact will trace to via `:satisfies:` or `:verifies:`. +- **tailoring** (from `.pharaoh/project/`): + - `artefact-catalog.yaml` — used to resolve `target_type` to a known prefix and confirm a + drafter is available + - `id-conventions.yaml` — read by the dispatched drafter (not by this skill directly) +- **needs.json**: required by every dispatched drafter for parent resolution and ID uniqueness + +--- + +## Outputs + +The drafted RST directive block exactly as produced by the dispatched skill, plus a thin +authoring-summary block: + +``` +=== [ARTEFACT] : === + + +=== [AUTHORING SUMMARY] === +{ + "need_id": "", + "type": "", + "dispatched_skill": "pharaoh-req-draft|pharaoh-arch-draft|pharaoh-vplan-draft|pharaoh-decide", + "parent_link": "", + "file_placement": "", + "stop_reason": null +} +``` + +If the dispatched drafter returns a hard FAIL or `[DIAGNOSTIC]`, forward it verbatim and set +`stop_reason` in the summary. + +--- + +## Process + +### Step 0: Resolve target_type + +Normalise the user-supplied type to a catalog key: + +| User input (any case) | Resolves to | +|---|---| +| `req`, `requirement`, `gd_req`, `comp_req`, `feat` | first matching key in artefact-catalog whose suffix is `req` (or `feat` for feature-level) | +| `arch`, `architecture`, `spec`, `specification`, `module`, `component`, `interface` | `arch` | +| `tc`, `test_case`, `test`, `verification_plan`, `vplan` | `tc` | +| `decision`, `dec`, `adr` | `decision` | + +If the user's input does not map to a key present in `.pharaoh/project/artefact-catalog.yaml`, +emit: + +``` +FAIL: target_type "" is not in the project's artefact catalog. +Catalog keys available: . +``` + +Read `.pharaoh/project/artefact-catalog.yaml` to confirm the resolved key exists. If the +catalog file is missing, fall back to the bundled defaults — `gd_req`, `arch`, `tc` — and note +the fallback in the authoring summary. + +--- + +### Step 1: Select the dispatch skill + +Apply the routing table: + +| Resolved key | Dispatched skill | +|---|---| +| `req`, `gd_req`, `comp_req`, `feat`, or any key whose suffix is `req` | `pharaoh-req-draft` | +| `arch` | `pharaoh-arch-draft` | +| `tc` | `pharaoh-vplan-draft` | +| `decision` | `pharaoh-decide` | + +If the resolved key matches none of the above (typical for safety-V types like `hazard`, +`safety_goal`, `fsr`, `tsr`), emit a clear pointer to the future safety-V drafting work and +stop: + +``` +FAIL: no atomic drafter is registered for target_type "" yet. +The author router covers req, arch, tc, decision today. Safety-V drafters +(hazard, safety_goal, fsr, tsr) are tracked under issue #13 §9c. Until they +land, draft this artefact manually or extend pharaoh-author with a new +dispatch entry once the drafter exists. +``` + +The dispatch entries for `pharaoh-arch-draft` and `pharaoh-vplan-draft` are deliberately thin +single-call passthroughs. Their interfaces will be parameterised in a follow-up phase +(removing the hardcoded `arch_type` allow-list and the `tc__` prefix), at which point the +routing arguments below will be revisited. + +--- + +### Step 2: Forward inputs to the dispatched skill + +Pack a minimal input set per skill and invoke it. Pass through any field the user supplied; +let the dispatched skill apply its own defaults and FAIL when its inputs are insufficient. + +**`pharaoh-req-draft`** + +- `feature_context` ← `draft_seed` +- `parent_link` ← `parent_link` (may be a workflow-id when drafting a top-level requirement) + +**`pharaoh-arch-draft`** *(thin passthrough — interface to be parameterised in a follow-up)* + +- `parent_req_id` ← `parent_link` +- `arch_type` ← user-supplied if present; otherwise pass through and let the drafter FAIL + with its own `arch_type "" is not recognised` diagnostic +- `element_description` ← `draft_seed` + +**`pharaoh-vplan-draft`** *(thin passthrough — interface to be parameterised in a follow-up)* + +- `parent_id` ← `parent_link` +- `verification_level` ← user-supplied if present (`unit` / `integration` / `system`); the + drafter will FAIL on a missing or unrecognised value + +**`pharaoh-decide`** + +- forward `draft_seed`, the `:decides:` link list (parsed from `parent_link` — comma-separated + is supported), and any `decided_by` / `alternatives` / `rationale` provided by the caller + +If the caller provides additional fields (e.g. `safety_context`, `tags`, `level`), forward +them as-is. The dispatched skill ignores keys it does not recognise. + +--- + +### Step 3: Capture the drafter output + +Capture the full output of the dispatched skill — the RST directive block plus any +`[NOTE]` / `[DIAGNOSTIC]` annotations. + +If the dispatched skill returned a hard FAIL, propagate it verbatim and set +`stop_reason = " FAIL"` in the authoring summary. Do not attempt to fix +the inputs and retry — the caller decides. + +--- + +### Step 4: File placement + +Suggest where to write the new RST directive. The author router does not write files — it +only suggests a path that the caller can use. + +Default placement rules: + +| Dispatched skill | Suggested file | +|---|---| +| `pharaoh-req-draft` | same directory as `parent_link`'s source file; filename matching the project's existing convention (e.g. `requirements.rst`) | +| `pharaoh-arch-draft` | sibling `architecture.rst` in the same directory as `parent_link`'s source | +| `pharaoh-vplan-draft` | `tests/` subdirectory if one exists, else sibling `tests.rst` | +| `pharaoh-decide` | `decisions.rst` next to the first `:decides:` target | + +If `parent_link` is empty or its source location cannot be resolved from `needs.json`, emit +`file_placement: null` and let the caller decide. + +--- + +### Step 5: Emit the authoring summary + +Emit the `=== [ARTEFACT] ===` block followed by the `=== [AUTHORING SUMMARY] ===` JSON. No +prose wrapper. + +If the dispatched drafter advised a follow-up (e.g. `pharaoh-arch-review`), preserve that +line below the summary so callers can chain. + +--- + +## Guardrails + +**G1 — Unknown target_type** + +If the resolved key is not in the artefact catalog, FAIL (Step 0). Do not invent a new +artefact type at runtime. + +**G2 — No drafter for known type** + +If the resolved key is in the catalog but the routing table has no entry, FAIL with a pointer +to the future safety-V drafting work (Step 1). Do not silently fall back to `pharaoh-req-draft`. + +**G3 — Dispatched drafter failed** + +Forward FAIL / `[DIAGNOSTIC]` verbatim. Record `stop_reason` in the summary. Do not retry. + +**G4 — Tailoring missing** + +If `.pharaoh/project/artefact-catalog.yaml` is absent, the dispatched drafter will operate on +its built-in defaults. Note the fallback in the authoring summary so the caller knows the +output is not catalog-validated. + +--- + +## Advisory chain + +After a successful authoring summary, advise the caller: + +``` +Consider running `pharaoh-verify ` to confirm the drafted artefact +addresses the substance of its parent. For a per-axis review of the prose itself, +use `pharaoh-req-review` / `pharaoh-arch-review` / `pharaoh-vplan-review`. +``` + +--- + +## Worked example + +**User input:** + +> target_type: `arch` +> draft_seed: "Manages the ABS pump drive circuit, including PWM duty-cycle control and +> over-current protection." +> parent_link: `gd_req__abs_pump_activation` +> arch_type: `component` + +**Step 0:** `arch` resolves directly to catalog key `arch`. + +**Step 1:** routing table → `pharaoh-arch-draft`. + +**Step 2:** forward `parent_req_id`, `arch_type`, `element_description`. + +**Step 3:** `pharaoh-arch-draft` returns its RST block for `arch__abs_pump_driver`. + +**Step 4:** `gd_req__abs_pump_activation` lives in `docs/requirements/braking.rst`. +Suggested placement: `docs/requirements/architecture.rst`. + +**Step 5 output (condensed):** + +``` +=== [ARTEFACT] arch: arch__abs_pump_driver === +.. arch:: ABS pump driver component + :id: arch__abs_pump_driver + :status: draft + :satisfies: gd_req__abs_pump_activation + :type: component + + The ABS pump driver component manages the pump drive circuit, controlling + output PWM duty cycle and providing over-current protection for the pump motor. + +=== [AUTHORING SUMMARY] === +{ + "need_id": "arch__abs_pump_driver", + "type": "arch", + "dispatched_skill": "pharaoh-arch-draft", + "parent_link": "gd_req__abs_pump_activation", + "file_placement": "docs/requirements/architecture.rst", + "stop_reason": null +} +``` + +``` +Consider running `pharaoh-verify arch__abs_pump_driver` to confirm the drafted +artefact addresses the substance of its parent. +``` diff --git a/skills/pharaoh-verify/SKILL.md b/skills/pharaoh-verify/SKILL.md new file mode 100644 index 0000000..250d4dd --- /dev/null +++ b/skills/pharaoh-verify/SKILL.md @@ -0,0 +1,330 @@ +--- +name: pharaoh-verify +description: Use when checking whether one sphinx-needs artefact actually addresses the substance of every parent it links to via :satisfies: or :verifies:. Cross-need content check — distinct from structural MECE, schema-level tailor-review, and per-axis req-review/arch-review. +chains_from: [pharaoh-author, pharaoh-req-draft, pharaoh-arch-draft, pharaoh-vplan-draft] +chains_to: [pharaoh-mece] +--- + +# pharaoh-verify + +## When to use + +Invoke when the user has one need-id (drafted, modified, or already-published) and wants to +know whether its body actually addresses the substance of its parent — does the architecture +element discharge the requirement, does the test case exercise the requirement's claim, does +the decision close the question its `:decides:` target raised. + +This is a **cross-need content check**. It is the only Pharaoh skill that compares two needs' +bodies for substantive coverage. + +How it differs from the neighbouring review skills: + +| Skill | Scope | Question answered | +|---|---|---| +| `pharaoh-mece` | full corpus | Are required links present? Are there orphans / gaps? (structural) | +| `pharaoh-tailor-review` | tailoring files | Does `.pharaoh/project/` validate against the schemas? (schema-level) | +| `pharaoh-req-review` | one requirement | Does this requirement pass the 11 ISO 26262 §6 axes? (per-axis prose rubric) | +| `pharaoh-arch-review` | one architecture element | Same axes plus arch-specific axes (per-axis prose rubric) | +| `pharaoh-vplan-review` | one test case | Same axes plus vplan-specific axes (per-axis prose rubric) | +| **`pharaoh-verify`** | one child + its parents | Does the child's body actually address the parent's substance? (content-level satisfaction) | + +Do NOT use when: + +- The user wants per-axis prose grading — use `pharaoh-req-review` / `pharaoh-arch-review` / + `pharaoh-vplan-review`. +- The user wants gap or orphan analysis across the corpus — use `pharaoh-mece`. +- The user wants to know if the tailoring files are well-formed — use `pharaoh-tailor-review`. + +--- + +## Inputs + +- **need_id** (from user): the child need-id to verify. Must exist in `needs.json`. +- **transitive** (from user, optional, default `false`): if `true`, walk every `:satisfies:` + / `:verifies:` link transitively and verify each ancestor pair (child↔direct-parent, + direct-parent↔grandparent, …). If `false`, verify only the direct parents. +- **tailoring** (from `.pharaoh/project/`): + - `artefact-catalog.yaml` — read the link-relationship map: which link types carry the + "satisfies its parent" semantics for each artefact type. Defaults: `:satisfies:` for + requirements and architecture; `:verifies:` for test cases; `:decides:` for decisions. + - `id-conventions.yaml` — only used when reporting parent IDs that fail the regex +- **needs.json**: required for body lookup on both child and every parent + +--- + +## Outputs + +A single JSON document. Shape: + +```json +{ + "need_id": "", + "child_type": "", + "parents": [ + { + "parent_id": "", + "parent_type": "", + "link_field": "satisfies|verifies|decides", + "verdict": "addresses|partial|absent|unresolved", + "score": 3, + "reason": "one-sentence justification", + "missing_aspects": ["..."] + } + ], + "overall": "addresses|partial|absent", + "action_items": ["..."] +} +``` + +### Verdict scale + +Per parent, score the child body on a 0-3 ordinal: + +| Score | Verdict | Definition | +|---|---|---| +| 3 | `addresses` | Child body explicitly covers every claim, condition, or actor named in the parent. No substantive aspect of the parent is missing. | +| 2 | `addresses` | Child covers all major claims; minor wording or a marginal sub-claim is paraphrased rather than restated. | +| 1 | `partial` | Child covers some but not all of the parent's substantive claims. Concrete missing aspects are listed in `missing_aspects`. | +| 0 | `absent` | Child body is generic, off-topic, or names the parent ID without substantively addressing the parent's claim. | +| n/a | `unresolved` | Parent ID does not resolve in `needs.json` — record as `unresolved` and skip scoring this pair. | + +### Overall + +Computed across all parent pairs (excluding `unresolved`): + +- `addresses` — every pair scores ≥ 2 +- `partial` — at least one pair scores 1, no pair scores 0 +- `absent` — at least one pair scores 0 + +If every parent is `unresolved`, set `overall` to `"absent"` and add an action item naming the +unresolved parents. + +--- + +## Process + +### Step 1: Resolve child + +Find `needs.json` (check `docs/_build/needs/needs.json`, then `_build/needs/needs.json`, then +any `needs.json` under a `_build` directory). If not found, FAIL: + +``` +FAIL: needs.json not found. Build the Sphinx project first +(`sphinx-build docs/ docs/_build/`), then re-run this skill. +``` + +Look up `need_id`. If not present, FAIL: + +``` +FAIL: need_id "" not found in needs.json. +Verify the ID or build the project. +``` + +Extract the child's type, body, and the values of every parent-link field that applies to its +type per `artefact-catalog.yaml` (default mapping: requirements → `:satisfies:`; architecture +→ `:satisfies:`; test cases → `:verifies:`; decisions → `:decides:`). + +If the child has no parent-link values at all, emit: + +```json +{ + "need_id": "", + "child_type": "", + "parents": [], + "overall": "absent", + "action_items": [ + "Child has no :satisfies:/:verifies:/:decides: link. Add a parent before verifying." + ] +} +``` + +and stop. + +--- + +### Step 2: Resolve parents + +For each parent ID listed in the child's link fields, look it up in `needs.json`: + +- If found, capture the parent's type and body. +- If not found, mark the pair `verdict: "unresolved"` and continue. + +If `transitive = true`, push each resolved parent onto a queue and repeat Step 2 for its own +parents. Maintain a visited set to avoid cycles. The output `parents` list is flattened — +each parent appears once with its direct child noted in `link_field`. + +--- + +### Step 3: Score each pair + +For each (child, parent) pair, read both bodies and answer the satisfaction question for the +relevant link semantics: + +| Link field | Question to answer | +|---|---| +| `satisfies` | Does the child's prose discharge the parent requirement's claim — i.e. would building only what the child describes satisfy what the parent demands? | +| `verifies` | Does the test case's inputs / steps / expected outcome exercise the specific behaviour the parent requires? Would a passing run of this test give evidence the parent is met? | +| `decides` | Does the decision body resolve the design question that the affected need raises — alternatives weighed, choice stated, rationale matches the parent's concern? | + +Score on the 0-3 scale above. Be concrete in `reason` — name the parent claim that is or is +not covered. When `score < 2`, populate `missing_aspects` with the specific claims, actors, +or conditions from the parent that the child fails to address. + +For test cases, also flag `partial` when the test only exercises a happy path while the +parent requires negative or boundary cases. + +--- + +### Step 4: Compute overall and action items + +Compute `overall` per the table above. For every pair with `score < 2` or +`verdict == "unresolved"`, add a concrete action item naming the parent and the missing +aspect: + +``` +"satisfies : child does not cover ; rewrite the body to address it" +``` + +If every pair scores ≥ 2, `action_items` is an empty array. + +--- + +### Step 5: Emit JSON + +Emit the JSON document only. No prose wrapper. + +If `overall != "addresses"`, append below the JSON a single advisory line: + +``` +Consider `pharaoh-author ` to revise the body, or `pharaoh-req-regenerate ` +for a per-axis driven rewrite. Re-run `pharaoh-verify ` after the edit. +``` + +This is the only prose permitted after the JSON. + +--- + +## Guardrails + +**G1 — Child not found** + +`need_id` absent from `needs.json` → FAIL (Step 1). + +**G2 — Child has no parent links** + +Emit a JSON document with empty `parents` and a clear action item, then stop (Step 1). Do not +guess a parent. + +**G3 — All parents unresolved** + +Set `overall = "absent"`; do not crash. Action items must list every unresolved parent ID so +the user can fix the link or build the project first. + +**G4 — Empty bodies** + +If either the child's body or a parent's body is empty (only the title is set), score that +pair `0` with `reason: " body is empty — substantive verification not possible"` and +add an action item to populate the body before re-running. + +--- + +## Advisory chain + +This skill has `chains_to: [pharaoh-mece]` because content satisfaction is the natural sibling +of structural MECE. After verifying one need, the user often wants the corpus-wide structural +view next: + +``` +Consider running `pharaoh-mece` to confirm the surrounding link structure +(orphans, gaps, status inconsistencies) is also healthy. +``` + +Show this line only when `overall == "addresses"`. + +--- + +## Worked example + +**User input:** + +> need_id: `arch__abs_pump_driver` +> transitive: false + +**Step 1:** child resolves; type `arch`. Parent-link field for `arch` is `:satisfies:`. Value: +`gd_req__abs_pump_activation`. + +**Step 2:** parent resolves. Body: "The brake controller shall engage the ABS pump when +measured wheel slip exceeds the calibrated activation threshold." + +**Step 3:** child body: "The ABS pump driver component manages the pump drive circuit, +controlling output PWM duty cycle and providing over-current protection for the pump motor." + +The child names the pump drive circuit and the actuation mechanism (PWM, over-current) but +does not state how the wheel-slip-threshold trigger reaches the driver. Score 2 — addresses +the actuation claim but the trigger linkage is implicit. + +**Step 4:** `overall = "addresses"`; one minor `missing_aspect` recorded. + +**Step 5 output:** + +```json +{ + "need_id": "arch__abs_pump_driver", + "child_type": "arch", + "parents": [ + { + "parent_id": "gd_req__abs_pump_activation", + "parent_type": "gd_req", + "link_field": "satisfies", + "verdict": "addresses", + "score": 2, + "reason": "child covers pump actuation and protection; the wheel-slip trigger linkage is implicit, not restated", + "missing_aspects": ["wheel-slip-threshold trigger pathway from sensor to driver"] + } + ], + "overall": "addresses", + "action_items": [] +} +``` + +``` +Consider running `pharaoh-mece` to confirm the surrounding link structure is also healthy. +``` + +--- + +**Variant: child does not address the parent** + +Same parent, but the child body reads: "The ABS pump driver component logs telemetry every +100 ms to the CAN bus." Logging is unrelated to the parent's actuation claim. + +```json +{ + "need_id": "arch__abs_pump_driver", + "child_type": "arch", + "parents": [ + { + "parent_id": "gd_req__abs_pump_activation", + "parent_type": "gd_req", + "link_field": "satisfies", + "verdict": "absent", + "score": 0, + "reason": "child describes telemetry logging only; does not address pump engagement on slip threshold", + "missing_aspects": [ + "ABS pump engagement actuation", + "wheel-slip-threshold trigger pathway" + ] + } + ], + "overall": "absent", + "action_items": [ + "satisfies gd_req__abs_pump_activation: child does not cover pump engagement; rewrite the body to describe the actuation pathway and the slip-threshold trigger" + ] +} +``` + +``` +Consider `pharaoh-author arch__abs_pump_driver` to revise the body, or `pharaoh-req-regenerate +arch__abs_pump_driver` for a per-axis driven rewrite. Re-run `pharaoh-verify +arch__abs_pump_driver` after the edit. +``` From 39d76b645e6fdab9323cd902ff31c9708fab5e78 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 16:33:14 +0200 Subject: [PATCH 06/15] schemas: promote tailoring schemas to canonical install path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves the four JSON Schemas from examples/score/.pharaoh/project/schemas/ to schemas/ at the package root so every Pharaoh-tailored project shares the same authoritative validation rules. Adds schemas/README.md documenting the resolution order and per-file responsibilities. Updates pharaoh-tailor-review to resolve schemas in priority order: (1) explicit schemas_dir argument, (2) per-project /schemas/, (3) the shipped schemas/ folder, (4) fallback to built-in structural rules with degraded_mode flag. Fixes pharaoh-tailor-bootstrap output to validate against the canonical artefact-catalog schema by dropping the unused child_of and lifecycle_ref keys (both rejected by additionalProperties: false). The information child_of carried is recoverable from artefact-type link declarations; lifecycle_ref was decorative. Updates skills/shared/tailoring-access.md to document only the schema-allowed fields (required_fields, optional_fields, lifecycle, required_body_sections) — the prior child_of and lifecycle_ref entries were inconsistent with the canonical schema. Closes part of #13: section 1 sub-bullets (a) artefact-catalog additionalProperties violations and (d) schemas at canonical install path. Sub-bullets (b) and (c) are addressed by the next commit on this branch. --- schemas/README.md | 22 ++++++++++++ .../artefact-catalog.schema.json | 0 .../checklists-frontmatter.schema.json | 0 .../id-conventions.schema.json | 0 .../schemas => schemas}/workflows.schema.json | 0 skills/pharaoh-tailor-bootstrap/SKILL.md | 9 +++-- skills/pharaoh-tailor-review/SKILL.md | 35 ++++++++++++------- skills/shared/tailoring-access.md | 2 +- 8 files changed, 53 insertions(+), 15 deletions(-) create mode 100644 schemas/README.md rename {examples/score/.pharaoh/project/schemas => schemas}/artefact-catalog.schema.json (100%) rename {examples/score/.pharaoh/project/schemas => schemas}/checklists-frontmatter.schema.json (100%) rename {examples/score/.pharaoh/project/schemas => schemas}/id-conventions.schema.json (100%) rename {examples/score/.pharaoh/project/schemas => schemas}/workflows.schema.json (100%) diff --git a/schemas/README.md b/schemas/README.md new file mode 100644 index 0000000..3da1912 --- /dev/null +++ b/schemas/README.md @@ -0,0 +1,22 @@ +# Pharaoh tailoring schemas + +JSON Schemas (Draft 2020-12) for the four tailoring files Pharaoh +authors and consumes: + +| File | Validates | Authored by | Consumed by | +|---------------------------------------|--------------------------------------------|---------------------------------------|------------------------------------------------| +| `artefact-catalog.schema.json` | `.pharaoh/project/artefact-catalog.yaml` | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review`, `pharaoh-link-completeness-check`, `pharaoh-output-validate`, `pharaoh-review-completeness` | +| `workflows.schema.json` | `.pharaoh/project/workflows.yaml` | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review`, `pharaoh-lifecycle-check`, `pharaoh-status-lifecycle-check` | +| `id-conventions.schema.json` | `.pharaoh/project/id-conventions.yaml` | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review`, `pharaoh-id-convention-check`, `pharaoh-id-allocate` | +| `checklists-frontmatter.schema.json` | `.pharaoh/project/checklists/*.md` (frontmatter only) | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review` | + +`pharaoh-tailor-review` resolves the schema set in this order: + +1. Explicit `schemas_dir` argument from the caller. +2. `/schemas/` if present in the project (per-project overrides). +3. The Pharaoh-shipped `schemas/` directory (this folder). +4. Built-in structural rules (degraded mode — emits a warning). + +Per-project overrides may add fields, never remove required ones. + +To extend: add a property to the schema, then update the matching emitter (`pharaoh-tailor-bootstrap` or `pharaoh-tailor-fill`) to populate it. Cross-file referential checks (every lifecycle state in artefact-catalog must appear in workflows; every prefix in artefact-catalog must appear in id-conventions) are enforced by `pharaoh-tailor-review` as cross-file rules C1-C5, not by JSON Schema. diff --git a/examples/score/.pharaoh/project/schemas/artefact-catalog.schema.json b/schemas/artefact-catalog.schema.json similarity index 100% rename from examples/score/.pharaoh/project/schemas/artefact-catalog.schema.json rename to schemas/artefact-catalog.schema.json diff --git a/examples/score/.pharaoh/project/schemas/checklists-frontmatter.schema.json b/schemas/checklists-frontmatter.schema.json similarity index 100% rename from examples/score/.pharaoh/project/schemas/checklists-frontmatter.schema.json rename to schemas/checklists-frontmatter.schema.json diff --git a/examples/score/.pharaoh/project/schemas/id-conventions.schema.json b/schemas/id-conventions.schema.json similarity index 100% rename from examples/score/.pharaoh/project/schemas/id-conventions.schema.json rename to schemas/id-conventions.schema.json diff --git a/examples/score/.pharaoh/project/schemas/workflows.schema.json b/schemas/workflows.schema.json similarity index 100% rename from examples/score/.pharaoh/project/schemas/workflows.schema.json rename to schemas/workflows.schema.json diff --git a/skills/pharaoh-tailor-bootstrap/SKILL.md b/skills/pharaoh-tailor-bootstrap/SKILL.md index 7163540..d470fd9 100644 --- a/skills/pharaoh-tailor-bootstrap/SKILL.md +++ b/skills/pharaoh-tailor-bootstrap/SKILL.md @@ -79,8 +79,13 @@ See fixture for exact format. For each declared type, emit: - `required_fields`: at minimum `id`, `status`. - `optional_fields`: `reviewer`, `approved_by`, plus `source_doc` for types that typically carry provenance (heuristic: top-level types like `feat`, `story`, `use_case` — if unsure, include it). -- `child_of`: list of parent types inferred from extra_links. Rule: if `satisfies` link exists, types that commonly use it (`comp_req`, `spec`, `impl`) list their parent (`feat`, `story`, etc.). If no clear inference, `child_of: []` — caller tunes later. -- `lifecycle_ref`: `workflows.yaml#`. +- `lifecycle`: list of states from `workflows.yaml` that apply to this type (typically the full state list). +- `required_body_sections`: optional list of body-prose section headings (e.g. `Inputs`, `Steps`, `Expected` for `tc`); omit when no body sections are required. + +The emitted `artefact-catalog.yaml` validates against +`schemas/artefact-catalog.schema.json` shipped at the Pharaoh package root +(see `schemas/README.md`). `pharaoh-tailor-review` enforces this on the +output of every bootstrap run. ### Step 5: Emit per-type checklists diff --git a/skills/pharaoh-tailor-review/SKILL.md b/skills/pharaoh-tailor-review/SKILL.md index 7eb8aca..9a967d9 100644 --- a/skills/pharaoh-tailor-review/SKILL.md +++ b/skills/pharaoh-tailor-review/SKILL.md @@ -23,9 +23,16 @@ Do NOT invoke to author or repair tailoring files — use `pharaoh-tailor-fill` - **tailoring_dir** (from user): path to `.pharaoh/project/` containing the four tailoring files -- **schemas_dir** (from user, optional): path to JSON schema files. Defaults to - `/schemas/` if that directory exists; otherwise applies built-in structural - checks (see Step 2). +- **schemas_dir** (from user, optional): path to JSON schema files. Resolved in + this order: + 1. The explicit value if provided. + 2. `/schemas/` if that directory exists (per-project overrides). + 3. The Pharaoh-shipped `schemas/` directory at the package root + (`/schemas/`). This is the default and ships with the four + canonical schemas (`artefact-catalog.schema.json`, `workflows.schema.json`, + `id-conventions.schema.json`, `checklists-frontmatter.schema.json`). + 4. If none of the above resolve, falls back to built-in structural rules and + emits a `degraded_mode: true` flag in the output. The four expected files: - `/id-conventions.yaml` @@ -119,7 +126,7 @@ but do not replace them. For each entry in `prefixes`, the key must be a non-empty string and the value must be a non-empty string (the description). See -`examples/my-project/.pharaoh/project/schemas/id-conventions.schema.json` for the authoritative +`/schemas/id-conventions.schema.json` for the authoritative JSON Schema. **workflows.yaml required keys:** @@ -134,7 +141,7 @@ For each transition in `transitions`: - `from` and `to` must be non-empty strings. - `requires` must be a list (may be empty). -See `examples/my-project/.pharaoh/project/schemas/workflows.schema.json` for the authoritative +See `/schemas/workflows.schema.json` for the authoritative JSON Schema. **artefact-catalog.yaml required structure:** @@ -148,14 +155,14 @@ Top level must be a map of artefact-type keys. For each artefact type: | `required_body_sections` | list | Optional; entries are top-level heading names that must appear inside the directive body prose (e.g. `Inputs`, `Steps`, `Expected` for `tc`). Validated as body prose, not as `:key:` options. | | `lifecycle` | list | Optional; if present must be non-empty | -See `examples/my-project/.pharaoh/project/schemas/artefact-catalog.schema.json` for the +See `/schemas/artefact-catalog.schema.json` for the authoritative JSON Schema. **checklists/*.md frontmatter:** YAML frontmatter (delimited by `---`) at the top of a checklist file is **optional**. When present, it is validated against -`examples/my-project/.pharaoh/project/schemas/checklists-frontmatter.schema.json`: +`/schemas/checklists-frontmatter.schema.json`: | Key | Rule | |---|---| @@ -239,15 +246,19 @@ Emit the JSON document. No prose before or after. ## Schema validation -Four JSON Schema (draft 2020-12) files live alongside the tailoring files and make structural +Four JSON Schema (draft 2020-12) files ship with Pharaoh and make structural validation deterministic: | Tailoring file | Schema | |---|---| -| `id-conventions.yaml` | `/schemas/id-conventions.schema.json` | -| `workflows.yaml` | `/schemas/workflows.schema.json` | -| `artefact-catalog.yaml` | `/schemas/artefact-catalog.schema.json` | -| `checklists/*.md` (frontmatter) | `/schemas/checklists-frontmatter.schema.json` | +| `id-conventions.yaml` | `/id-conventions.schema.json` | +| `workflows.yaml` | `/workflows.schema.json` | +| `artefact-catalog.yaml` | `/artefact-catalog.schema.json` | +| `checklists/*.md` (frontmatter) | `/checklists-frontmatter.schema.json` | + +`` is resolved per the order documented in Inputs above; the +default is the Pharaoh-shipped `schemas/` directory at the package root. See +`schemas/README.md` for the full resolution order and per-file responsibilities. Schema `$id` values are anchored under `https://pharaoh.useblocks.com/schemas/` and do not need to resolve at runtime. diff --git a/skills/shared/tailoring-access.md b/skills/shared/tailoring-access.md index 4a683e9..4c38636 100644 --- a/skills/shared/tailoring-access.md +++ b/skills/shared/tailoring-access.md @@ -6,7 +6,7 @@ Shared helper module documenting how Pharaoh skills resolve project tailoring pa Given a `tailoring_path` input (typically the absolute path to `.pharaoh/project/`): -1. **Artefact catalogue**: read `/artefact-catalog.yaml`. Contains `required_fields`, `optional_fields`, `child_of`, and `lifecycle_ref` per declared type. Produced by `pharaoh-tailor-bootstrap` or hand-authored. +1. **Artefact catalogue**: read `/artefact-catalog.yaml`. Contains `required_fields`, `optional_fields`, `lifecycle`, and `required_body_sections` per declared type. Validates against `schemas/artefact-catalog.schema.json`. Produced by `pharaoh-tailor-bootstrap` or hand-authored. 2. **ID conventions**: read `/id-conventions.yaml`. Contains `prefixes` (directive → prefix map), `id_regex` (validation regex), `separator`. Produced by `pharaoh-tailor-bootstrap`. 3. **Workflows**: read `/workflows.yaml`. Per-type state machine (`states`, `transitions`, `initial`, `final`). Produced by `pharaoh-tailor-bootstrap`. 4. **Checklists**: read `/checklists/.md` for per-type checklists. Use `/checklists/requirement.md` as the canonical-alias filename when the caller wants "the" requirement checklist without knowing the project's directive name (alias is emitted by `pharaoh-tailor-bootstrap`). From ec43f69c06476b7c3eab62434931edce464751b7 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 16:38:35 +0200 Subject: [PATCH 07/15] tailor: reconcile bootstrap/fill output shapes against canonical schemas Aligns pharaoh-tailor-bootstrap and pharaoh-tailor-fill so the same tailoring file gets the same shape regardless of which authoring path ran. Resolves divergences caught when validating real-world projects: workflows.yaml: bootstrap rewrites its per-type {from, to, gate} map output to the schema-shaped flat lifecycle_states + transitions[*] {from, to, requires}. fill already emits this shape on the transitions side but printed lifecycle_states as a description map; corrected to a flat list per the schema. bootstrap was the outlier on transitions. id-conventions.yaml id_regex_*: pharaoh-id-convention-check now reads id_regex_exceptions (the schema key) instead of id_regex_by_type. The three fixture files in skills/pharaoh-id-convention-check/fixtures/ move to the same key. id-conventions.yaml prefixes: canonical value form is the identifier prefix string (e.g. REQ_, gd_req), not a human description. Tightens the prefixes additionalProperties regex in schemas/id-conventions.schema.json to enforce identifier-prefix shape and updates pharaoh-tailor-fill plus the score example tailoring to emit prefix strings instead of prose descriptions. pharaoh-lifecycle-check: documentation note tying the workflows.yaml shape it consumes to schemas/workflows.schema.json; no behavioural change. Closes #13 sections 2 (bootstrap/fill incompatibility) and 1 sub-bullets (b) workflows shape mismatch and (c) id-conventions value-form ambiguity. --- .../.pharaoh/project/id-conventions.yaml | 17 ++++++---- schemas/id-conventions.schema.json | 3 +- skills/pharaoh-id-convention-check/SKILL.md | 12 +++---- .../all-conform/input-id-conventions.yaml | 2 +- .../input-id-conventions.yaml | 2 +- .../some-violate/input-id-conventions.yaml | 2 +- skills/pharaoh-lifecycle-check/SKILL.md | 9 +++-- skills/pharaoh-tailor-bootstrap/SKILL.md | 28 +++++++++++++++- skills/pharaoh-tailor-fill/SKILL.md | 33 ++++++++++--------- 9 files changed, 71 insertions(+), 37 deletions(-) diff --git a/examples/score/.pharaoh/project/id-conventions.yaml b/examples/score/.pharaoh/project/id-conventions.yaml index 328b13a..a411c01 100644 --- a/examples/score/.pharaoh/project/id-conventions.yaml +++ b/examples/score/.pharaoh/project/id-conventions.yaml @@ -1,12 +1,15 @@ # examples/score/.pharaoh/project/id-conventions.yaml +# Values are the literal identifier-prefix strings prepended to the local-part +# to form an id (e.g. gd_req__abs_pump_activation). Human descriptions of each +# prefix live in artefact-catalog.yaml entries, not here. prefixes: - gd_req: requirement (guide-level) - wp: work product - wf: workflow - std_req: external standard requirement (ISO/ASPICE) - gd_chklst: checklist - arch: architecture - tc: test case + gd_req: gd_req + wp: wp + wf: wf + std_req: std_req + gd_chklst: gd_chklst + arch: arch + tc: tc # NOTE: std_req IDs embed source-standard codes that may contain uppercase and hyphens, # e.g. std_req__aspice_40__MAN-3-BP1. The regex below applies to all other prefixes; # std_req is intentionally exempt because the local-part mirrors upstream identifier diff --git a/schemas/id-conventions.schema.json b/schemas/id-conventions.schema.json index c303ac9..df6c441 100644 --- a/schemas/id-conventions.schema.json +++ b/schemas/id-conventions.schema.json @@ -8,10 +8,11 @@ "properties": { "prefixes": { "type": "object", - "description": "Map of prefix token (e.g. gd_req) to human-readable description.", + "description": "Map from prefix key (e.g. feat, gd_req) to the literal identifier-prefix string that is prepended to the local-part to form an id (e.g. FEAT_, gd_req). Values must be identifier-shaped tokens, not human descriptions — they are consumed by pharaoh-id-allocate and pharaoh-id-convention-check.", "minProperties": 1, "additionalProperties": { "type": "string", + "pattern": "^[A-Za-z][A-Za-z0-9_]*$", "minLength": 1 } }, diff --git a/skills/pharaoh-id-convention-check/SKILL.md b/skills/pharaoh-id-convention-check/SKILL.md index 30427d9..ae2a571 100644 --- a/skills/pharaoh-id-convention-check/SKILL.md +++ b/skills/pharaoh-id-convention-check/SKILL.md @@ -33,20 +33,20 @@ Do NOT use to discover or count id schemes — the tailoring author declares ONE id_regex: "^[a-z][a-z_]*__[a-z0-9_]+$" # per-type overrides — the regex applied to needs of that type - id_regex_by_type: + id_regex_exceptions: comp_req: "^CREQ_[a-z]+_[a-z]+_[a-z]+$" gd_req: "^CREQ_.+$|^gd_req__.+$" ``` - Resolution order for a need of type `T`: `id_regex_by_type[T]` if declared, else `id_regex` (top-level default), else fail the whole check with `reason: "no regex declared for type "` on every need of that type. + Resolution order for a need of type `T`: `id_regex_exceptions[T]` if declared, else `id_regex` (top-level default), else fail the whole check with `reason: "no regex declared for type "` on every need of that type. - `needs_json_path`: absolute path to the built sphinx-needs corpus `needs.json`. Accepts either the flat `{"needs": {: {id, type, ...}, ...}}` shape or the versioned `{"versions": {"": {"needs": {...}}}}` shape (uses `current_version` if declared, else the latest key). Each need object must carry at least `id` and `type`; needs missing either field are reported as violations with `reason: "missing id or type field"`. Edge cases: - Empty corpus (`needs` is `{}`) → `needs_checked: 0, violations: [], overall: "pass"` (vacuously true). -- `id-conventions.yaml` has neither `id_regex` nor `id_regex_by_type` → every need is a violation with `reason: "no regex declared for type "`. +- `id-conventions.yaml` has neither `id_regex` nor `id_regex_exceptions` → every need is a violation with `reason: "no regex declared for type "`. - Regex compilation error (invalid Python regex syntax in the tailoring) → `overall: "fail"` with a single violation `{need_id: "*", type: "", expected_regex: "", reason: "regex compile error: "}` and `needs_checked: 0`. -- Need `type` not mentioned in `id_regex_by_type` and no top-level default → violation with `reason: "no regex declared for type "`. +- Need `type` not mentioned in `id_regex_exceptions` and no top-level default → violation with `reason: "no regex declared for type "`. ## Output @@ -78,7 +78,7 @@ Edge cases: For every need `N` in the flattened needs map: 1. Read `N.id` and `N.type`. If either is absent, emit violation `{need_id: ">, type: ">, expected_regex: null, reason: "missing id or type field"}` and continue. -2. Resolve the regex for `N.type`: first `id_regex_by_type[N.type]`, else top-level `id_regex`. If neither is declared, emit violation `{need_id: N.id, type: N.type, expected_regex: null, reason: "no regex declared for type "}` and continue. +2. Resolve the regex for `N.type`: first `id_regex_exceptions[N.type]`, else top-level `id_regex`. If neither is declared, emit violation `{need_id: N.id, type: N.type, expected_regex: null, reason: "no regex declared for type "}` and continue. 3. Compile the regex with Python `re.compile(pattern)`. On `re.error`, emit a single synthetic violation (see Edge cases above) and abort. 4. Apply `re.fullmatch(pattern, N.id)`. If `None`, emit violation `{need_id: N.id, type: N.type, expected_regex: , reason: "does not match"}`. @@ -94,7 +94,7 @@ nj = json.load(open(needs_json_path)) needs = nj.get("needs") or next(iter(nj.get("versions", {}).values()), {}).get("needs", {}) default = conv.get("id_regex") -by_type = conv.get("id_regex_by_type", {}) or {} +by_type = conv.get("id_regex_exceptions", {}) or {} violations = [] for nid, n in needs.items(): diff --git a/skills/pharaoh-id-convention-check/fixtures/all-conform/input-id-conventions.yaml b/skills/pharaoh-id-convention-check/fixtures/all-conform/input-id-conventions.yaml index dfa6dcb..ffba0db 100644 --- a/skills/pharaoh-id-convention-check/fixtures/all-conform/input-id-conventions.yaml +++ b/skills/pharaoh-id-convention-check/fixtures/all-conform/input-id-conventions.yaml @@ -3,6 +3,6 @@ id_regex: "^[a-z][a-z_]*__[a-z0-9_]+$" -id_regex_by_type: +id_regex_exceptions: comp_req: "^CREQ_[a-z]+_[a-z]+_[a-z]+$" test_case: "^tc__[a-z0-9_]+$" diff --git a/skills/pharaoh-id-convention-check/fixtures/alternation-regex/input-id-conventions.yaml b/skills/pharaoh-id-convention-check/fixtures/alternation-regex/input-id-conventions.yaml index 9b6ab57..64c268b 100644 --- a/skills/pharaoh-id-convention-check/fixtures/alternation-regex/input-id-conventions.yaml +++ b/skills/pharaoh-id-convention-check/fixtures/alternation-regex/input-id-conventions.yaml @@ -3,5 +3,5 @@ id_regex: "^[a-z][a-z_]*__[a-z0-9_]+$" -id_regex_by_type: +id_regex_exceptions: comp_req: "^CREQ_.+$|^gd_req__.+$" diff --git a/skills/pharaoh-id-convention-check/fixtures/some-violate/input-id-conventions.yaml b/skills/pharaoh-id-convention-check/fixtures/some-violate/input-id-conventions.yaml index 14b360d..5b76b39 100644 --- a/skills/pharaoh-id-convention-check/fixtures/some-violate/input-id-conventions.yaml +++ b/skills/pharaoh-id-convention-check/fixtures/some-violate/input-id-conventions.yaml @@ -2,6 +2,6 @@ id_regex: "^[a-z][a-z_]*__[a-z0-9_]+$" -id_regex_by_type: +id_regex_exceptions: comp_req: "^CREQ_[a-z]+_[a-z]+_[a-z]+$" test_case: "^tc__[a-z0-9_]+$" diff --git a/skills/pharaoh-lifecycle-check/SKILL.md b/skills/pharaoh-lifecycle-check/SKILL.md index ac21236..99f8c9b 100644 --- a/skills/pharaoh-lifecycle-check/SKILL.md +++ b/skills/pharaoh-lifecycle-check/SKILL.md @@ -66,9 +66,12 @@ current state is a valid declared state for this artefact type. ### Step 1: Load tailoring and needs.json -**1a.** Read `workflows.yaml` from `.pharaoh/project/`. Extract: -- `lifecycle_states` map (keys are valid state names) -- `transitions` list: each entry has `from`, `to`, `requires` +**1a.** Read `workflows.yaml` from `.pharaoh/project/`. The file shape is fixed by +`schemas/workflows.schema.json` (flat `lifecycle_states` array, `transitions` array of +`{from, to, requires}`). Extract: +- `lifecycle_states` — flat list of declared state-name strings +- `transitions` list: each entry has `from`, `to`, and a `requires` list of gate-name + strings (always a list per the schema, never a scalar) **1b.** Read `artefact-catalog.yaml`. Find the entry for the artefact type of `need_id`. Record the `lifecycle` list for that type (if present). diff --git a/skills/pharaoh-tailor-bootstrap/SKILL.md b/skills/pharaoh-tailor-bootstrap/SKILL.md index d470fd9..0dfb930 100644 --- a/skills/pharaoh-tailor-bootstrap/SKILL.md +++ b/skills/pharaoh-tailor-bootstrap/SKILL.md @@ -64,7 +64,33 @@ If zero types declared, FAIL: `"no [[needs.types]] in ubproject.toml; run pharao ### Step 2: Emit workflows.yaml -For each declared type, emit a block with states `draft`, `reviewed`, `approved`, transitions `draft→reviewed` (gate `reviewer_present`), `reviewed→approved` (gate `approver_present`), `reviewed→draft` (gate `reviewer_rejected`), initial `draft`, final `approved`. +Emit a single project-wide state machine matching `schemas/workflows.schema.json`: a flat `lifecycle_states` list and a `transitions` array where each entry has `from`, `to`, and a `requires` list (always a list, never a scalar `gate` field). + +Default content for a greenfield bootstrap: + +```yaml +# workflows.yaml — generated by pharaoh-tailor-bootstrap +# Validates against schemas/workflows.schema.json. +# Edit transitions[*].requires to declare per-transition prerequisites. + +lifecycle_states: + - draft + - reviewed + - approved + +transitions: + - from: draft + to: reviewed + requires: [] + - from: reviewed + to: approved + requires: [] + - from: reviewed + to: draft + requires: [] +``` + +The state machine is project-wide, not per-type — `artefact-catalog.yaml` declares which subset of `lifecycle_states` applies to each type via its own `lifecycle` field (Step 4). `requires` is always a list of gate-name strings (empty list permitted); it replaces any older single-string `gate:` field. See `expected_output/workflows.yaml` in the fixture for exact format. diff --git a/skills/pharaoh-tailor-fill/SKILL.md b/skills/pharaoh-tailor-fill/SKILL.md index ae94cce..6e2aefd 100644 --- a/skills/pharaoh-tailor-fill/SKILL.md +++ b/skills/pharaoh-tailor-fill/SKILL.md @@ -118,10 +118,10 @@ id_regex: "^[a-z][a-z_]*__[a-z0-9_]+$" id_regex_exceptions: {} prefixes: - gd_req: "requirement (guide-level)" - wp: "work product" - wf: "workflow" - tc: "test case" + gd_req: GD_REQ_ + wp: WP_ + wf: WF_ + tc: TC_ # ... one entry per detected prefix ``` @@ -129,14 +129,13 @@ Rules: - `separator`: value from detect report; if `null`, write `separator: null # WARNING: not detected` - `id_regex`: value from `id_regex_candidate`; if `null`, write placeholder with warning comment - `id_regex_exceptions`: map from detect report `id_regex_exceptions`; empty map if none -- `prefixes`: one key per detected prefix from `detected_conventions.prefixes`; derive a - short human description from the prefix name using common conventions: - - suffix `_req` → "requirement ()" - - `wp` → "work product" - - `wf` → "workflow" - - `tc` → "test case" - - `chklst` → "checklist" - - otherwise → `" artefact"` (placeholder) +- `prefixes`: one key per detected prefix from `detected_conventions.prefixes`. The value is the + identifier-prefix string that gets prepended to the local-part to form an id (e.g. `REQ_`, + `FEAT_`, `BRAKE_CTRL_`, or just `tc` if the project uses the directive name itself as the + prefix). Take the value from the detect report's `prefixes[]`; if the detect report + reports the prefix as the directive name itself (e.g. `tc__`), use the directive name as + the value. Do not author human descriptions in the value position — `prefixes` is consumed + by `pharaoh-id-allocate` and must be a literal prefix token, not prose. --- @@ -181,12 +180,13 @@ Format: ```yaml # workflows.yaml — generated by pharaoh-tailor-fill +# Validates against schemas/workflows.schema.json. # Review default transitions before committing. lifecycle_states: - draft: "Initial authoring state — not yet reviewed" - valid: "Review completed — approved for use" - inspected: "Independent inspection passed" + - draft + - valid + - inspected transitions: - from: draft @@ -198,9 +198,10 @@ transitions: - from: inspected to: draft requires: [] - note: "regression path — allowed without prerequisite" ``` +State descriptions live in code review notes or per-project docs, not in `workflows.yaml` — `lifecycle_states` is a flat list of state-name strings per the schema. The optional `note:` field is not part of the schema and must be dropped from emitted output. + --- ### Step 5: Write artefact-catalog.yaml From 31efc5b140d84d33b1a0d23aaf4bb1820d643140 Mon Sep 17 00:00:00 2001 From: Bartosz Burda Date: Tue, 5 May 2026 16:44:29 +0200 Subject: [PATCH 08/15] release-gate: emit and validate required_links/metadata_fields/roles Closes the silent no-op where four release-gate fields were consumed but never emitted by any tailoring author: required_links / optional_links read by pharaoh-link-completeness-check required_metadata_fields read by pharaoh-output-validate required_roles read by pharaoh-review-completeness Adds all four as optional per-type properties to schemas/artefact-catalog.schema.json. Documents inference rules in pharaoh-tailor-bootstrap and emission defaults in pharaoh-tailor-fill. Adds cross-file rule C6 in pharaoh-tailor-review that surfaces a finding when any of the three required-* fields is absent (empty arrays are valid -- they declare an explicit choice; missing keys are not). Closes #13 (section 3). --- schemas/README.md | 6 ++-- schemas/artefact-catalog.schema.json | 36 +++++++++++++++++++ skills/pharaoh-quality-gate/SKILL.md | 2 ++ skills/pharaoh-tailor-bootstrap/SKILL.md | 36 +++++++++++++++++++ skills/pharaoh-tailor-fill/SKILL.md | 46 +++++++++++++++++++++++- skills/pharaoh-tailor-review/SKILL.md | 42 +++++++++++++++++++++- 6 files changed, 164 insertions(+), 4 deletions(-) diff --git a/schemas/README.md b/schemas/README.md index 3da1912..1ebfe70 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -5,7 +5,7 @@ authors and consumes: | File | Validates | Authored by | Consumed by | |---------------------------------------|--------------------------------------------|---------------------------------------|------------------------------------------------| -| `artefact-catalog.schema.json` | `.pharaoh/project/artefact-catalog.yaml` | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review`, `pharaoh-link-completeness-check`, `pharaoh-output-validate`, `pharaoh-review-completeness` | +| `artefact-catalog.schema.json` | `.pharaoh/project/artefact-catalog.yaml` | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review`, `pharaoh-link-completeness-check`, `pharaoh-output-validate`, `pharaoh-review-completeness`, `pharaoh-quality-gate` | | `workflows.schema.json` | `.pharaoh/project/workflows.yaml` | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review`, `pharaoh-lifecycle-check`, `pharaoh-status-lifecycle-check` | | `id-conventions.schema.json` | `.pharaoh/project/id-conventions.yaml` | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review`, `pharaoh-id-convention-check`, `pharaoh-id-allocate` | | `checklists-frontmatter.schema.json` | `.pharaoh/project/checklists/*.md` (frontmatter only) | `pharaoh-tailor-bootstrap`, `pharaoh-tailor-fill` | `pharaoh-tailor-review` | @@ -19,4 +19,6 @@ authors and consumes: Per-project overrides may add fields, never remove required ones. -To extend: add a property to the schema, then update the matching emitter (`pharaoh-tailor-bootstrap` or `pharaoh-tailor-fill`) to populate it. Cross-file referential checks (every lifecycle state in artefact-catalog must appear in workflows; every prefix in artefact-catalog must appear in id-conventions) are enforced by `pharaoh-tailor-review` as cross-file rules C1-C5, not by JSON Schema. +To extend: add a property to the schema, then update the matching emitter (`pharaoh-tailor-bootstrap` or `pharaoh-tailor-fill`) to populate it. Cross-file referential checks (every lifecycle state in artefact-catalog must appear in workflows; every prefix in artefact-catalog must appear in id-conventions) are enforced by `pharaoh-tailor-review` as cross-file rules C1-C6, not by JSON Schema. + +The four release-gate fields on each per-type entry of `artefact-catalog.yaml` (`required_links`, `optional_links`, `required_metadata_fields`, `required_roles`) are all optional in the schema but their absence is surfaced as a finding by `pharaoh-tailor-review` rule C6 — empty arrays declare an explicit "no requirement" choice, missing keys mean the project never decided. Consumers (`pharaoh-link-completeness-check`, `pharaoh-output-validate`, `pharaoh-review-completeness`) treat absent keys as empty so a project with none of these fields ships a silent no-op release gate; rule C6 is what makes the choice explicit. diff --git a/schemas/artefact-catalog.schema.json b/schemas/artefact-catalog.schema.json index a8a07f0..3cd8ef2 100644 --- a/schemas/artefact-catalog.schema.json +++ b/schemas/artefact-catalog.schema.json @@ -47,6 +47,42 @@ "minLength": 1 }, "uniqueItems": true + }, + "required_links": { + "type": "array", + "description": "Link-relation names that every need of this type must declare with a non-empty target list. Enforced at release by pharaoh-link-completeness-check (and aggregated by pharaoh-quality-gate via the link_types_covered invariant). Empty array explicitly disables the check for this type; absent key is treated as empty.", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + }, + "optional_links": { + "type": "array", + "description": "Link-relation names that may be declared on a need of this type. Read by pharaoh-link-completeness-check for completeness reporting. Must not overlap with required_links (enforced by pharaoh-tailor-review).", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + }, + "required_metadata_fields": { + "type": "array", + "description": "sphinx-needs option keys that must be set with non-empty values before release. Enforced by pharaoh-output-validate in graph mode (delegated by pharaoh-quality-gate via the metadata_fields_present invariant). Empty array explicitly disables the check for this type; absent key is treated as empty.", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + }, + "required_roles": { + "type": "array", + "description": "Role-bearing option keys that must be set with non-empty values before release (e.g. reviewer, approved_by). Enforced by pharaoh-review-completeness. Empty array explicitly disables the check for this type; absent key is treated as no review/approval requirement.", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true } }, "additionalProperties": false diff --git a/skills/pharaoh-quality-gate/SKILL.md b/skills/pharaoh-quality-gate/SKILL.md index c02a6c3..fb7f289 100644 --- a/skills/pharaoh-quality-gate/SKILL.md +++ b/skills/pharaoh-quality-gate/SKILL.md @@ -121,6 +121,8 @@ Each delegated check returns either `{passed: bool, ...}` or the atom's native ` `metadata_fields_present` delegates to the existing `pharaoh-output-validate` atom invoked in `mode: "graph"` (see that skill's `## Graph mode`). The tailored `required_metadata_fields` list is declared per-type in `artefact-catalog.yaml`; empty list disables the check for that type, absent key is treated as empty. No new atom is introduced for this invariant — graph mode is a second input-shape on the existing block-validator. +The four release-gate fields backing `link_types_covered`, `metadata_fields_present`, and the `pharaoh-review-completeness` invariant (`required_links`, `optional_links`, `required_metadata_fields`, `required_roles`) are declared per-type in `artefact-catalog.yaml`. Their canonical schema lives at `schemas/artefact-catalog.schema.json` (see `schemas/README.md`); the absence of any of the three required-* keys is surfaced as a finding by `pharaoh-tailor-review` rule C6, so a project running the gate after a clean `pharaoh-tailor-review` has explicitly declared (possibly as empty arrays) what every consumer reads. + If a delegated check is not yet implemented in the skill tree, the gate records a warning in the report but does not fail — so that adding new invariants in future is a config-only change. ## Output diff --git a/skills/pharaoh-tailor-bootstrap/SKILL.md b/skills/pharaoh-tailor-bootstrap/SKILL.md index 0dfb930..b7f4d94 100644 --- a/skills/pharaoh-tailor-bootstrap/SKILL.md +++ b/skills/pharaoh-tailor-bootstrap/SKILL.md @@ -107,6 +107,42 @@ For each declared type, emit: - `optional_fields`: `reviewer`, `approved_by`, plus `source_doc` for types that typically carry provenance (heuristic: top-level types like `feat`, `story`, `use_case` — if unsure, include it). - `lifecycle`: list of states from `workflows.yaml` that apply to this type (typically the full state list). - `required_body_sections`: optional list of body-prose section headings (e.g. `Inputs`, `Steps`, `Expected` for `tc`); omit when no body sections are required. +- `required_links`, `optional_links`, `required_metadata_fields`, `required_roles`: release-gate fields read by `pharaoh-link-completeness-check`, `pharaoh-output-validate`, and `pharaoh-review-completeness` (and aggregated by `pharaoh-quality-gate`). Emit all four as arrays of strings — empty arrays are valid and declare an explicit "no requirement" choice; absent keys are flagged by `pharaoh-tailor-review` rule C6 as an unmade decision. + +Inference rules for the four release-gate fields: + +- `required_links`: include the `option` of every `[[needs.extra_links]]` entry that resolves to this type as the source side of the link. Concretely: for an extra_link with `outgoing: ` (the link is declared on directives of this type), include its `option`. If the project does not declare the direction explicitly, default to including link options whose semantic name implies a parent reference (`satisfies`, `verifies`, `refines`, `derives_from`) for downstream artefact types (anything with `_req`, `arch`, `tc`, `impl`, `spec` in its directive). Other types default to `[]`. +- `optional_links`: any other extra_link `option` that may legally appear on this type but is not in `required_links`. Default to `[]` when no other links are declared. +- `required_metadata_fields`: include `status` always (every governed type has a lifecycle). Add any field that the project's `[needs.fields.X]` table declares as required for this directive. If `ubproject.toml` carries no such hints, emit `[status]`. +- `required_roles`: emit `[]` by default — bootstrap runs on greenfield projects with no observed review process. Tailoring authors are expected to fill in `[reviewer]` (or `[reviewer, approved_by]`) once a review gate is established. `pharaoh-tailor-review` rule C6 surfaces a finding if the key is absent so the project explicitly declares the choice. + +Worked example for a `comp_req` directive with `[[needs.extra_links]] option = "satisfies", outgoing = "comp_req"`: + +```yaml +comp_req: + required_fields: [id, status, title, satisfies] + optional_fields: [reviewer, approved_by, source_doc] + lifecycle: [draft, reviewed, approved] + required_links: [satisfies] + optional_links: [] + required_metadata_fields: [status] + required_roles: [] +``` + +A type with no observed link declarations emits empty arrays: + +```yaml +feat: + required_fields: [id, status, title] + optional_fields: [reviewer, approved_by, source_doc] + lifecycle: [draft, reviewed, approved] + required_links: [] + optional_links: [] + required_metadata_fields: [status] + required_roles: [] +``` + +Empty arrays are deliberate: they say "the project considered this and chose no requirement". Omitting the key entirely is what `pharaoh-tailor-review` flags as an unmade decision (rule C6). The emitted `artefact-catalog.yaml` validates against `schemas/artefact-catalog.schema.json` shipped at the Pharaoh package root diff --git a/skills/pharaoh-tailor-fill/SKILL.md b/skills/pharaoh-tailor-fill/SKILL.md index 6e2aefd..1a31b2c 100644 --- a/skills/pharaoh-tailor-fill/SKILL.md +++ b/skills/pharaoh-tailor-fill/SKILL.md @@ -215,9 +215,13 @@ For each artefact type, emit a YAML block: required_fields: [] optional_fields: [] lifecycle: [] # omit if prefix has no status field + required_links: [] + optional_links: [] + required_metadata_fields: [