Add Pharaoh setup#51
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Bootstraps the Pharaoh authoring/review layer on top of the existing Sphinx-Needs setup by adding Pharaoh configuration, project tailoring files, Copilot agents/prompts, and end-user documentation describing how to run and verify the setup.
Changes:
- Add a root
pharaoh.tomldefining advisory-mode workflow gates, an ID scheme, traceability chains, and codelinks integration. - Add
.pharaoh/project/tailoring (workflows, artefact catalog, ID conventions) plus per-need-type review checklists. - Add GitHub Copilot integration (
.github/agents/,.github/prompts/,.github/copilot-instructions.md) and a newdocs/pharaoh.rstpage linked from the docs index; ignore Pharaoh ephemeral state in.gitignore.
Reviewed changes
Copilot reviewed 105 out of 106 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| pharaoh.toml | Pharaoh root configuration (workflow/traceability/codelinks). |
| .gitignore | Ignore Pharaoh ephemeral state while keeping tailoring tracked. |
| docs/index.rst | Add the Pharaoh page to the docs toctree. |
| docs/pharaoh.rst | Document Pharaoh setup, files created, and verification steps. |
| .pharaoh/project/workflows.yaml | Per-type lifecycle states and transitions. |
| .pharaoh/project/artefact-catalog.yaml | Per-type required/optional fields and parent relations. |
| .pharaoh/project/id-conventions.yaml | Per-type prefixes + project ID regex/separator. |
| .pharaoh/project/checklists/arch.md | Review checklist for arch. |
| .pharaoh/project/checklists/component.md | Review checklist for component. |
| .pharaoh/project/checklists/fsr.md | Review checklist for fsr. |
| .pharaoh/project/checklists/hazard.md | Review checklist for hazard. |
| .pharaoh/project/checklists/impl.md | Review checklist for impl. |
| .pharaoh/project/checklists/interface.md | Review checklist for interface. |
| .pharaoh/project/checklists/need.md | Review checklist for need. |
| .pharaoh/project/checklists/person.md | Review checklist for person. |
| .pharaoh/project/checklists/release.md | Review checklist for release. |
| .pharaoh/project/checklists/req.md | Review checklist for req. |
| .pharaoh/project/checklists/requirement.md | Alias checklist for req. |
| .pharaoh/project/checklists/safety_goal.md | Review checklist for safety_goal. |
| .pharaoh/project/checklists/seq_msg.md | Review checklist for seq_msg. |
| .pharaoh/project/checklists/spec.md | Review checklist for spec. |
| .pharaoh/project/checklists/swarch.md | Review checklist for swarch. |
| .pharaoh/project/checklists/swreq.md | Review checklist for swreq. |
| .pharaoh/project/checklists/sys-arch.md | Review checklist for sys-arch. |
| .pharaoh/project/checklists/sysreq.md | Review checklist for sysreq. |
| .pharaoh/project/checklists/team.md | Review checklist for team. |
| .pharaoh/project/checklists/test.md | Review checklist for test. |
| .github/copilot-instructions.md | Repo-wide Copilot preamble with Pharaoh context. |
| .github/prompts/pharaoh.author.prompt.md | Copilot prompt routing to pharaoh.author. |
| .github/prompts/pharaoh.change.prompt.md | Copilot prompt routing to pharaoh.change. |
| .github/prompts/pharaoh.mece.prompt.md | Copilot prompt routing to pharaoh.mece. |
| .github/prompts/pharaoh.plan.prompt.md | Copilot prompt routing to pharaoh.plan. |
| .github/prompts/pharaoh.release.prompt.md | Copilot prompt routing to pharaoh.release. |
| .github/prompts/pharaoh.trace.prompt.md | Copilot prompt routing to pharaoh.trace. |
| .github/prompts/pharaoh.verify.prompt.md | Copilot prompt routing to pharaoh.verify. |
| .github/agents/pharaoh.activity-diagram-draft.agent.md | Copilot agent definition (activity diagram drafting). |
| .github/agents/pharaoh.api-coverage-check.agent.md | Copilot agent definition (API coverage check). |
| .github/agents/pharaoh.arch-draft.agent.md | Copilot agent definition (arch drafting). |
| .github/agents/pharaoh.arch-review.agent.md | Copilot agent definition (arch review). |
| .github/agents/pharaoh.audit-fanout.agent.md | Copilot agent definition (parallel audit orchestration). |
| .github/agents/pharaoh.block-diagram-draft.agent.md | Copilot agent definition (block diagram drafting). |
| .github/agents/pharaoh.bootstrap.agent.md | Copilot agent definition (sphinx-needs bootstrap). |
| .github/agents/pharaoh.change.agent.md | Copilot agent definition (change impact analysis). |
| .github/agents/pharaoh.class-diagram-draft.agent.md | Copilot agent definition (class diagram drafting). |
| .github/agents/pharaoh.component-diagram-draft.agent.md | Copilot agent definition (component diagram drafting). |
| .github/agents/pharaoh.context-gather.agent.md | Copilot agent definition (context gathering). |
| .github/agents/pharaoh.coverage-gap.agent.md | Copilot agent definition (gap detection). |
| .github/agents/pharaoh.decide.agent.md | Copilot agent definition (decision recording). |
| .github/agents/pharaoh.decision-record.agent.md | Copilot agent definition (decision memo record). |
| .github/agents/pharaoh.decision-review.agent.md | Copilot agent definition (decision review). |
| .github/agents/pharaoh.deployment-diagram-draft.agent.md | Copilot agent definition (deployment diagram drafting). |
| .github/agents/pharaoh.diagram-lint.agent.md | Copilot agent definition (diagram linting). |
| .github/agents/pharaoh.diagram-review.agent.md | Copilot agent definition (diagram review). |
| .github/agents/pharaoh.dispatch-signal-check.agent.md | Copilot agent definition (dispatch signal check). |
| .github/agents/pharaoh.execute-plan.agent.md | Copilot agent definition (plan execution). |
| .github/agents/pharaoh.fault-tree-diagram-draft.agent.md | Copilot agent definition (fault tree drafting). |
| .github/agents/pharaoh.feat-balance.agent.md | Copilot agent definition (feature balance check). |
| .github/agents/pharaoh.feat-component-extract.agent.md | Copilot agent definition (feat → components extraction). |
| .github/agents/pharaoh.feat-draft-from-docs.agent.md | Copilot agent definition (feat drafting from docs). |
| .github/agents/pharaoh.feat-file-map.agent.md | Copilot agent definition (feature → file mapping). |
| .github/agents/pharaoh.feat-flow-extract.agent.md | Copilot agent definition (flow extraction). |
| .github/agents/pharaoh.feat-review.agent.md | Copilot agent definition (feature review). |
| .github/agents/pharaoh.finding-record.agent.md | Copilot agent definition (finding record). |
| .github/agents/pharaoh.flow.agent.md | Copilot agent definition (V-model orchestration). |
| .github/agents/pharaoh.fmea-review.agent.md | Copilot agent definition (FMEA review). |
| .github/agents/pharaoh.fmea.agent.md | Copilot agent definition (FMEA derivation). |
| .github/agents/pharaoh.gate-advisor.agent.md | Copilot agent definition (gate enablement advisor). |
| .github/agents/pharaoh.id-allocate.agent.md | Copilot agent definition (ID allocation). |
| .github/agents/pharaoh.id-convention-check.agent.md | Copilot agent definition (ID convention checks). |
| .github/agents/pharaoh.lifecycle-check.agent.md | Copilot agent definition (lifecycle check). |
| .github/agents/pharaoh.link-completeness-check.agent.md | Copilot agent definition (link completeness check). |
| .github/agents/pharaoh.mece.agent.md | Copilot agent definition (MECE analysis). |
| .github/agents/pharaoh.output-validate.agent.md | Copilot agent definition (output schema validation). |
| .github/agents/pharaoh.papyrus-non-empty-check.agent.md | Copilot agent definition (Papyrus writes check). |
| .github/agents/pharaoh.plan.agent.md | Copilot agent definition (planning). |
| .github/agents/pharaoh.process-audit.agent.md | Copilot agent definition (full-corpus audit). |
| .github/agents/pharaoh.prose-migrate.agent.md | Copilot agent definition (prose migration). |
| .github/agents/pharaoh.quality-gate.agent.md | Copilot agent definition (quality gate). |
| .github/agents/pharaoh.release.agent.md | Copilot agent definition (release prep). |
| .github/agents/pharaoh.reproducibility-check.agent.md | Copilot agent definition (reproducibility check). |
| .github/agents/pharaoh.req-code-grounding-check.agent.md | Copilot agent definition (req grounding check). |
| .github/agents/pharaoh.req-codelink-annotate.agent.md | Copilot agent definition (codelink annotation). |
| .github/agents/pharaoh.req-draft.agent.md | Copilot agent definition (req drafting). |
| .github/agents/pharaoh.req-from-code.agent.md | Copilot agent definition (req extraction from code). |
| .github/agents/pharaoh.req-regenerate.agent.md | Copilot agent definition (req regeneration). |
| .github/agents/pharaoh.req-review.agent.md | Copilot agent definition (req review). |
| .github/agents/pharaoh.review-completeness.agent.md | Copilot agent definition (review-chain completeness). |
| .github/agents/pharaoh.self-review-coverage-check.agent.md | Copilot agent definition (self-review coverage). |
| .github/agents/pharaoh.sequence-diagram-draft.agent.md | Copilot agent definition (sequence diagram drafting). |
| .github/agents/pharaoh.setup.agent.md | Copilot agent definition (project setup/scaffold). |
| .github/agents/pharaoh.spec.agent.md | Copilot agent definition (spec generation). |
| .github/agents/pharaoh.sphinx-extension-add.agent.md | Copilot agent definition (add Sphinx extensions). |
| .github/agents/pharaoh.standard-conformance.agent.md | Copilot agent definition (standard conformance checks). |
| .github/agents/pharaoh.state-diagram-draft.agent.md | Copilot agent definition (state diagram drafting). |
| .github/agents/pharaoh.status-lifecycle-check.agent.md | Copilot agent definition (status lifecycle gate). |
| .github/agents/pharaoh.tailor-bootstrap.agent.md | Copilot agent definition (tailoring bootstrap). |
| .github/agents/pharaoh.tailor-code-grounding-filters.agent.md | Copilot agent definition (code-grounding filters tailoring). |
| .github/agents/pharaoh.tailor-detect.agent.md | Copilot agent definition (tailoring detection). |
| .github/agents/pharaoh.tailor-fill.agent.md | Copilot agent definition (tailoring fill). |
| .github/agents/pharaoh.tailor-review.agent.md | Copilot agent definition (tailoring review). |
| .github/agents/pharaoh.toctree-emit.agent.md | Copilot agent definition (toctree emission). |
| .github/agents/pharaoh.trace.agent.md | Copilot agent definition (trace navigation). |
| .github/agents/pharaoh.use-case-diagram-draft.agent.md | Copilot agent definition (use-case diagram drafting). |
| .github/agents/pharaoh.vplan-draft.agent.md | Copilot agent definition (verification plan drafting). |
| .github/agents/pharaoh.vplan-review.agent.md | Copilot agent definition (verification plan review). |
| .github/agents/pharaoh.write-plan.agent.md | Copilot agent definition (plan writing). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1
to
+4
| --- | ||
| description: Use when you have an intent (e. | ||
| handoffs: [] | ||
| --- |
Comment on lines
+1
to
+4
| --- | ||
| 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. | ||
| handoffs: [] | ||
| --- |
Comment on lines
+68
to
+71
| ### Step 3: Configure .gitignore | ||
|
|
||
| Add `.pharaoh/` to `.gitignore` if not already present. Create `.gitignore` if needed. | ||
|
|
Comment on lines
+22
to
+26
| # Project id_regex from docs/ubproject.toml [needs] id_regex (preserved verbatim). | ||
| # Note: the strict OR-of-prefixes form would collide for R_ (req/release), T_ (test/team) | ||
| # and the bare _ (arch/need); the project intentionally uses a permissive regex instead. | ||
| id_regex: "^[A-Z_]{3,10}(_[0-9]{1,3})*$" | ||
| separator: "_" |
Comment on lines
+74
to
+76
| The setup is performed by the ``pharaoh:pharaoh-setup`` skill. It is | ||
| idempotent: re-running it on an already-configured project shows a | ||
| diff and asks before overwriting any file. |
Comment on lines
+155
to
+159
|
|
||
| .. code-block:: text | ||
|
|
||
| /pharaoh:pharaoh-mece | ||
|
|
Comment on lines
+96
to
+100
|
|
||
| .. code-block:: text | ||
|
|
||
| /pharaoh:pharaoh-setup | ||
|
|
Bootstrap pharaoh.toml, .pharaoh/project/ tailoring, .github/ Copilot agents, and a setup documentation page on top of the existing Sphinx-Needs configuration. Required link chains in pharaoh.toml reflect the 100%-coverage policy observed in needs.json (spec->req, arch->req, safety_goal->hazard, fsr->safety_goal). Mode is reverse-eng with advisory strictness, so workflow gates start permissive over the existing 268-need catalogue. The .gitignore entries are narrow: only .pharaoh/runs, .pharaoh/plans, .pharaoh/session.json, and .pharaoh/cache are ignored. The tailoring under .pharaoh/project/ is tracked.
* docs/pharaoh.rst: use @pharaoh.setup / @pharaoh.mece for the Copilot Chat examples (these match the agents installed under .github/agents/), and reference /pharaoh.mece + the Claude Code /pharaoh:pharaoh-mece form as alternates. Drop the inaccurate /pharaoh:pharaoh-setup example since this repo does not install a matching prompt. * .pharaoh/project/id-conventions.yaml: clarify that id_regex is the anchored, ASCII-digit normalised form of the regex declared in docs/ubproject.toml, not a verbatim copy.
Five agent files copied from the Pharaoh plugin had content issues that GitHub Copilot review flagged on this PR. Restoring the full source descriptions locally so this repo's .github/agents/ renders cleanly and matches the upstream skill specs. Tracked upstream as useblocks/pharaoh#12. * pharaoh.write-plan, pharaoh.toctree-emit, pharaoh.execute-plan, pharaoh.feat-file-map: descriptions were truncated mid-sentence at the first '.' character (e.g. "Use when you have an intent (e."), in some cases leaving unmatched parentheses or unclosed backticks. Restored from skills/pharaoh-*/SKILL.md description fields verbatim. * pharaoh.setup: Step 3 instructed to add a wholesale .pharaoh/ rule to .gitignore, contradicting the skill's own SKILL.md Step 4b which requires narrow ignores so .pharaoh/project/ tailoring stays tracked. Rewrote the step to match the skill's policy.
Cover Claude Code (/plugin marketplace add useblocks/pharaoh, /plugin install pharaoh@pharaoh-dev, /reload-plugins) and Copilot CLI (copilot plugin marketplace add / install). Mention pinning to a tag via /plugin marketplace add useblocks/pharaoh#v1.0.0.
The original catalog placed V-model textbook parent relations under child_of (e.g. impl.child_of: [spec], test.child_of: [spec]). The existing 268-need corpus does not honour those: impls link mostly to swreq/swarch/interface/component, tests link mostly to swreq, swreqs link to req. Pharaoh review skills consuming the catalog would have flagged 100+ false-positive missing-parent findings. Rewrote child_of using a conservative empirical rule: include a parent type only when (a) the corpus shows >=90% coverage and (b) the link semantics are child-to-parent (reqs, implements, specs, mitigates, derives_from, provided_by, generic links, parent_needs). Owner-style links (author, persons), planning links (release), and parent-to-child links (provides, startup_calls, shutdown_calls) are excluded even at high coverage. Types whose corpus parents are below the threshold or use ambiguous link semantics get child_of: []. Also tightened optional_fields per type to project-declared [needs.fields.X] entries plus the Pharaoh-internal reviewer / approved_by / source_doc trio. Project-specific fields (asil, severity, exposure, controllability, scenario, safe_state, customer, date, role, contact, image, jira, github, effort, approved) now sit on the type that actually carries them.
Pulls the agent and prompt template state from the upstream PR that addresses my consolidated feedback (useblocks/pharaoh#13). Adds the two missing user-entry agents (@pharaoh.author, @pharaoh.verify) so the matching slash commands stop dispatching to nothing, and picks up the description and gitignore-guidance fixes from the same upstream branch (covers useblocks/pharaoh#11 and useblocks#12 in one shot). Replaces the local hand-edits applied earlier in this PR for the five agent files I had patched (pharaoh.write-plan, pharaoh.toctree-emit, pharaoh.execute-plan, pharaoh.feat-file-map, pharaoh.setup) with the upstream versions, so the templates stay in sync with the plugin.
Rewrites workflows.yaml and artefact-catalog.yaml to validate against
the canonical JSON schemas shipped at
pharaoh/examples/score/.pharaoh/project/schemas/.
* workflows.yaml: flat top-level lifecycle_states + flat transitions
with requires lists, replacing the per-type maps and {from, to, gate}
inline form. Single Pharaoh review-workflow lifecycle, distinct from
the sphinx-needs :status: field which carries authoring state.
* artefact-catalog.yaml: drops child_of and lifecycle_ref keys
(additionalProperties: false in the canonical schema). Adds per-type
lifecycle arrays for review-eligible types and omits lifecycle for
meta types (person, team, release, seq_msg, need).
Both files now pass jsonschema validation against the canonical schemas.
Verification flagged that req.md and sysreq.md checklists reference :source_doc: in their bullets, but source_doc was not listed in those types' optional_fields. The other top-level types (arch, swarch, sys-arch, swreq) already carried source_doc as an optional Pharaoh provenance field. Adding it for req and sysreq aligns the catalog with the checklist content and with the convention used by sibling top-level types.
Without child_of (which the canonical schema rejects), the only way to tell an authoring agent what to link is to list the link-option name in the type's required_fields. Score example does this: gd_req's required fields include satisfies, which means every gd_req must have a non-empty :satisfies: link. Aligns spec and fsr with the same convention already used by safety_goal: * spec: required_fields includes reqs (every spec must link to a req via :reqs:, matching pharaoh.toml [pharaoh.traceability].required_links spec -> req chain). * fsr: required_fields includes derives_from (every fsr must link to a safety_goal via :derives_from:, matching the fsr -> safety_goal chain). * safety_goal already had mitigates in required_fields. arch -> req also exists in required_links but is omitted here because the project uses generic :links: for that hop, and listing :links: as required would be too broad.
Four-step demo flow on the existing Lane Detection corpus that a regular user can paste verbatim into Copilot Chat or Claude Code: * Step 1 (`@pharaoh.mece`): gap analysis against the configured traceability chains plus consistency / ID-regex / undeclared-type checks. * Step 2 (`@pharaoh.req-from-code`): reverse-engineer a focused API-encapsulation requirement from `src/automotive_adas.py` as a child of REQ_001. * Step 3 (`@pharaoh.vplan-draft`): write the missing system test that verifies the lane-detection requirement. * Step 4 (`@pharaoh.change`): change-impact analysis for a revision to REQ_001, scoped to outgoing and incoming :links: edges so the blast radius stays in the lane-detection domain. Each step lists the prompt body, the constraints that match the project's declared types/links/status conventions, and the expected output shape. A trailing sanity-check block re-runs sphinx-build -W and ubc check after the new needs are pasted. Also tightens the existing Tailoring layer section to reference real entry points (workflows.yaml, id-conventions.yaml) instead of the deprecated `child_of` field that the canonical schema does not allow.
The previous walkthrough hand-fed the agent a paragraph of constraints per step (ID regex bounds, declared field set, status enum, link options). That made every prompt longer than the artefact it produced and missed the point: the agent is supposed to read the project's tailoring (.pharaoh/project/) and ubproject.toml itself. Each step now ships a one-line prompt plus a "Why so short" note that points the missing-skill-grounding back to upstream Pharaoh, not to the user. If a skill needs hand-fed constraints to produce build-clean output, that is a Pharaoh-skill gap, not a property of this walkthrough. Word counts before / after, per step: * Step 1: ~70 -> 0 (just the agent invocation) * Step 2: ~120 -> ~15 * Step 3: ~85 -> ~10 * Step 4: ~110 -> ~15
End-to-end claude -p sonnet validation surfaced two atomicity drifts in the canonical Pharaoh skills under live invocation: * pharaoh-req-from-code happily emits 3 SW-level requirements when 1 feature-level requirement was asked for. One-line nudge: "Emit a single req directive using only declared fields and link options." * pharaoh-vplan-draft happily follows its own draft with a self-review pass and returns only the review. One-line nudge: "Emit only the RST .. test:: directive ready to paste, no review and no self-evaluation." The Why-so-short section now names both behaviours and notes they are tracked upstream rather than papering over them with longer prompts. Steps 1 (mece) and 4 (change) remain one-line invocations — both pass clean against the corpus when run with --permission-mode bypassPermissions to skip session-state write prompts.
Pharaoh PR useblocks#16 (Fix useblocks#13: tailoring, atomic-skill, and setup gaps) merged to upstream main and tagged v1.2.0. Pulls the seven agent files that received refinements during that PR's review: * pharaoh.arch-draft, pharaoh.change, pharaoh.flow, pharaoh.plan, pharaoh.req-draft, pharaoh.setup, pharaoh.vplan-draft. The other 64 agent files are byte-equal to what this PR was already shipping from the PR-16 head sync.
End-to-end claude -p sonnet retest against pharaoh@v1.2.0 surfaced two new behaviours and confirmed one prior workaround still needed: * Step 2 (req-from-code): one-req guard now works — single req emitted instead of three swreqs. Skill still emits Pharaoh-internal :source_doc: and :verification: placeholders even though the demo project does not declare them. Tighten the prompt to forbid those placeholders explicitly and document the strip-before-paste fallback. * Step 4 (change): pharaoh-change in v1.2 writes a session-state acknowledgement gate and stops at "acknowledge this change?" instead of emitting the impact report. Add "emit directly; do not stop at acknowledgement" to the prompt body to bypass the gate. The Why-so-short section now lists all three skill-drift behaviours covered by the nudges (req-from-code over-emit + placeholder fields, vplan-draft self-review, change acknowledgement gate). Steps 1 (mece) and 3 (vplan-draft) work unchanged. P3 in particular benefits from the v1.2 fix that drops the hardcoded tc__ prefix.
Each agent.md shipped under .github/agents/ previously ended with a relative `See [skills/pharaoh-X/SKILL.md](../../skills/pharaoh-X/SKILL.md)` link. The relative path resolves correctly inside the upstream Pharaoh repo (where dogfooding happens) but is a dead link in every user project, because the `skills/` directory only exists in the plugin source. 65 broken local refs across 71 agent files. More importantly: the LLM that handles the @pharaoh.X invocation in Copilot Chat sees only the agent.md content, never the SKILL.md the file points at. Most atomic agents shipped as 10-line stubs (10 lines agent.md vs ~300-500 lines SKILL.md), so the LLM had to improvise the skill's procedure from background knowledge. That is the root cause of the v1.2 retest findings (req-from-code emits Pharaoh-internal placeholders not in the project's tailoring; vplan-draft self-reviews when asked to draft). This commit appends the full SKILL.md content to every agent.md (stripping the SKILL.md frontmatter), and rewrites every reference to `skills/shared/X` and `../shared/X` to absolute URLs pinned to useblocks/pharaoh@v1.2.0 so the inlined content stays clickable. The broken `(../../skills/pharaoh-X/SKILL.md)` trailer is removed in the process. Result: * 73 of 73 agent files self-contained — no further file fetches required for an LLM to execute the skill correctly. * 0 broken local markdown refs (verified by parser). * 41 `../shared/X` and 24 `skills/shared/X` references rewritten to pinned absolute URLs. * Diff is +17367 / -65 lines, mostly the inlined skill specs. * sphinx-build -W and ubc check both still pass. Tracked upstream as `useblocks/pharaoh#18` (the workflow-gate + incomplete-useblocks#13 follow-up). The proper structural fix is a VS Code extension that registers @pharaoh.X chat participants from the plugin install dir; this in-PR inline is the workshop-grade workaround.
ubmarco
approved these changes
May 10, 2026
Member
ubmarco
left a comment
ubmarco
left a comment
There was a problem hiding this comment.
Looks good, thanks for the quick help!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bootstrap the Pharaoh authoring and review layer on top of the existing Sphinx-Needs configuration. Pharaoh re-uses the type and link declarations in
docs/ubproject.toml. It does not change how needs are stored or built.What this adds
pharaoh.tomlat the workspace root:strictness = "advisory",mode = "reverse-eng", codelinks enabled.required_linkslists the four chains that the existing 268-need corpus already satisfies at 100% coverage:spec -> req,arch -> req,safety_goal -> hazard,fsr -> safety_goal..pharaoh/project/: per-type lifecycle (workflows.yaml), ID conventions (id-conventions.yaml), artefact catalog (artefact-catalog.yaml), and a review checklist per declared need type plus arequirement.mdalias..github/agents/and.github/prompts/: GitHub Copilot Chat agents for Pharaoh's atomic skills (@pharaoh.req-draft,@pharaoh.mece,@pharaoh.flow, ...) and reusable prompts (/pharaoh.author,/pharaoh.mece, ...)..github/copilot-instructions.md: repository-wide Copilot preamble that loads the Pharaoh context.docs/pharaoh.rst: a setup explanation page added to theExplanationtoctree. Liveliteralincludeofpharaoh.toml, table of files Pharaoh creates, build + verification steps, tailoring guidance..gitignore: four narrow entries (.pharaoh/runs/,.pharaoh/plans/,.pharaoh/session.json,.pharaoh/cache/). The tracked.pharaoh/project/tailoring is intentionally not ignored.Verification
uv run sphinx-build -W -b html docs docs/_build/html— passes.uv run sphinx-build -W -b ubtrace docs docs/_build/ubtrace— passes.ubc check .fromdocs/— 0 errors over 31 files.pharaoh:meceagainst the producedneeds.json— 0 gaps against the configured chains. Other findings (status mismatches, ID-regex violations, types injected bysphinx-test-reports) are pre-existing properties of the corpus and out of scope here.Notes
require_change_analysis = false,require_mece_on_release = false) because Pharaoh is being introduced over an existing catalogue. Usepharaoh:gate-advisorto tighten them once authoring stabilises.impl,test, andcomponentwere intentionally omitted fromrequired_links. The corpus shows mixed parent types below 90% coverage for those, so they are not project-wide policy yet.