{
  "markdown": "<!-- mcp-name: io.github.cdeust/ai-architect-mcp-spec -->\n\n<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"AI Architect MCP Spec — verified PRDs for agentic delivery pipelines\" width=\"100%\"/>\n</p>\n\n**AI Architect MCP Spec** is published as `ai-architect-mcp-spec` across its\nClaude Code, Codex, Gemini, MCPB, PyPI/npm, and MCP Registry surfaces. `0.7.0`\nmoved the MCP Registry entry and primary bundle to the new identity while\nkeeping the Claude/Codex/Gemini plugins under `prd-spec-generator`; `0.8.0`\ncompleted the migration — no `prd-spec-generator` plugin or release alias is\nretained anywhere. The former `io.github.cdeust/prd-spec-generator` Registry\nversions are deprecated with a pointer to the canonical entry rather than\nleft active and frozen.\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"MIT License\">\n  <img src=\"https://img.shields.io/badge/TypeScript-7.0+-3178c6.svg\" alt=\"TypeScript 7.0+\">\n  <img src=\"https://img.shields.io/badge/Node-20.x_·_22.x-339933.svg\" alt=\"Node 20/22\">\n  <img src=\"https://img.shields.io/badge/Tests-1506_passing-brightgreen\" alt=\"1506 passing\">\n  <img src=\"https://img.shields.io/badge/Packages-10-orange\" alt=\"10 packages\">\n  <img src=\"https://img.shields.io/badge/MCP_Tools-17-8A2BE2\" alt=\"17 MCP tools\">\n  <img src=\"https://img.shields.io/badge/Validators-Hard_Output_Rules-red\" alt=\"Hard Output Rules\">\n  <img src=\"https://img.shields.io/badge/Calibration-Closed_Loop-success\" alt=\"Closed-loop reliability calibration\">\n  <a href=\"https://www.bestpractices.dev/projects/13832\"><img src=\"https://www.bestpractices.dev/projects/13832/badge\" alt=\"OpenSSF Best Practices\"></a>\n</p>\n\n<p align=\"center\">\n  <strong>Cross-platform PRD verification for Codex, Gemini CLI, Claude Code, CI, and any stdio MCP host.</strong><br>\n  The deterministic two-tool verifier travels everywhere; the full 9-file generation pipeline remains available to orchestration-capable hosts.\n</p>\n\n<p align=\"center\">\n  <a href=\"#what-an-agent-can-ask-it\">What An Agent Asks</a> · <a href=\"#getting-started\">Getting Started</a> · <a href=\"#the-pipeline\">Pipeline</a> · <a href=\"#the-mcp-tools\">Tools</a> · <a href=\"#multi-judge-verification\">Verification</a> · <a href=\"#calibration--falsification\">Calibration</a> · <a href=\"#architecture\">Architecture</a> · <a href=\"#the-zetetic-standard\">Zetetic Standard</a>\n</p>\n\n<p align=\"center\">\n  <strong>Companion projects:</strong><br>\n  <a href=\"https://github.com/cdeust/Cortex\">Cortex</a> — persistent memory that injects past decisions into every PRD<br>\n  <a href=\"https://github.com/cdeust/zetetic-team-subagents\">zetetic-team-subagents</a> — 97 genius reasoning patterns that judge each claim<br>\n  <a href=\"https://github.com/cdeust/ai-architect-mcp-codebase\">ai-architect-mcp-codebase</a> — the codebase intelligence layer this generator consumes upstream\n</p>\n\n---\n\nEvery AI agent that drafts a PRD eventually invents a function that doesn't exist, claims latency it can't measure, or writes acceptance criteria that don't tie back to the requirements they're supposed to test. The output sounds confident. It is not actionable. The next stage in the pipeline — code generation, ticket import, sprint planning — silently inherits the hallucination, ships it, and pays for it later.\n\n**AI Architect MCP Spec** is a TypeScript MCP server that fixes this at the structural level. Its portable verifier gives Codex, Gemini CLI, Claude Code, CI, and other stdio MCP hosts the same deterministic Hard Output Rules and cross-section traceability checks. The full pipeline is a stateless reducer (`step(state, result?) → next_state, action`) driven by a host that can execute its orchestration actions; Claude Code is the only packaged full-pipeline host today. Sections are produced one at a time, validated before the host ever sees them, and every load-bearing claim is judged by a panel of genius reasoning agents drawn from `zetetic-team-subagents` against the codebase graph from `ai-architect-mcp-codebase`. The loop is closed: per-judge reliability is calibrated from history, retry budgets are derived from survival statistics, KPI gates are tuned against frozen baselines, and held-out partitions are mechanically sealed so no calibration result can be peeked at before evaluation.\n\n**10 packages. 17 MCP tools. 20 pipeline steps (11 PRD generation + 9 opt-in implementation). Multi-judge verification with consensus. Closed-loop calibration with externally-grounded falsifiers. 1506 tests. Every numeric constant traces to a citation, a benchmark, or a `// source: provisional heuristic` admission.**\n\n---\n\n## Closed-loop reliability calibration\n\nVerification is not a one-shot pass/fail report. Every claim resolution can flush an observation back to a calibration repository, every consensus run can pull calibrated posteriors from history, and every closed loop runs an external control arm so the calibration's effect is *measured*, not assumed.\n\n- **Per-judge Bayesian reliability calibration** — Beta(7,3) prior with sensitivity / specificity split per `claim_type`. Posteriors stored in a SQLite-backed `ReliabilityRepository`; observations flushed on every claim resolution.\n- **MAX_ATTEMPTS retry calibration** — Kaplan-Meier survival math (`kmEstimate` / `kmMedianAttempts` / `logRankTest` with Greenwood + Brookmeyer-Crowley CIs); Schoenfeld sample-size derivation event-rate-corrected to ~519 (was 823) against the measured `event_rate=0.4762`, CP CI `[0.4456, 0.5069]`.\n- **KPI gate tuning** — Clopper-Pearson exact CIs; per-machine-class wall_time normalization with 5-bucket `detectMachineClass`; frozen-baseline content-hash assertion; `loadCalibratedGates` + `hold_provisional` ratchet protection.\n- **Plan-mismatch fire-rate** — measured via XmR control charts (Wheeler 1995, Western Electric 1956) with a synthetic injection round-trip pre-flight that catches drift between the diagnostic prefix and the regex matcher.\n- **Externally-grounded held-out subsets** — Ajv schema oracle, mathjs oracle, `tsc` subprocess code oracle, `validateSection` spec oracle. `OracleUnavailableError` typed throw replaces stub-mode fabrication. This is the layer that breaks annotator-circularity — judges and oracles share no inference path.\n- **CC-3 forced-exploration control arms** — every closed loop carves out a 20% partition that reverts to the prior. Without it, calibration-on-calibration looks like progress whether or not it actually is.\n- **Cross-arm comparison metrics** — `computeAblationComparison` / `computeReliabilityComparison` / `computeKpiGateComparison` produce paired-bootstrap CIs (Efron & Tibshirani 1993 §16.4; deterministic mulberry32 RNG; 12-decimal reproducibility pin). Outcome is a falsifiable recommendation: `calibrated_helps`, `prior_helps`, or `inconclusive_underpowered`.\n- **Mechanically-enforced held-out partition seals** — three sealed lock files (`maxattempts-heldout.lock.json`, `kpigates-heldout.lock.json`, `heldout-partition.lock.json`) commit a sha256 of the partition before evaluation. The `SEAL_VERIFIED` typeof sentinel is the only way to compute cross-arm metrics on a sealed partition; passing anything else is a type error at the boundary.\n- **Production-mode dispatcher** — `makeProductionDispatcher` + `AgentInvoker` interface. The CLI `--mode production|canned` flag selects whether calibration sees real verdicts or canned ones; the canned arm is preserved for offline reproducibility.\n\n---\n\n## What an agent can ask it\n\n```\nstart_pipeline(feature_description, codebase_path?)\n  → returns the first NextAction; the host executes it and feeds the result\n    back via submit_action_result. Eleven steps later: 9 PRD files written.\n\nsubmit_action_result(run_id, result)\n  → drives the reducer one more step. The host sees only SUBSTANTIVE actions\n    (ask_user, call_pipeline_tool, call_cortex_tool, spawn_subagents,\n     write_file, done, failed). emit_message is coalesced into the\n     messages array; the host never has to \"advance past\" a banner.\n\nvalidate_prd_section(content, section_type)\n  → deterministic Hard Output Rules — zero LLM calls, pure regex/parsing.\n  → returns: violations[], hasCriticalViolations, totalScore.\n\nvalidate_prd_document(sections[])\n  → cross-section checks: SP arithmetic, AC numbering, FR-AC coverage,\n    test traceability. Catches what per-section validation misses.\n\ncoordinate_context_budget(prd_context, completed_sections[])\n  → per-section retrieval/generation token budgets so Cortex recall and\n    section drafting don't fight over the same context window.\n\nmap_failure_to_retrieval(violations[])\n  → closes the validation→retrieval feedback loop. When a section fails\n    validation, this returns the corrective Cortex query that would\n    have prevented the failure.\n```\n\n---\n\n## Getting started\n\n### Install (marketplace — recommended)\n\n```bash\nclaude plugin marketplace add cdeust/ai-architect-mcp-spec\nclaude plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace\n```\n\nRestart your Claude Code session. The 17 MCP tools register on first\nstdio handshake. Then:\n\n```\n/generate-prd build OAuth login for the admin console\n```\n\nThe plugin's bundled MCP server at `mcp-server/index.js` is self-contained\n(only `better-sqlite3` is an optional native dependency for the evidence\nrepository — gracefully degrades to in-memory mode when absent).\n\n#### Migrating from `prd-spec-generator`\n\nThe old plugin and marketplace are deprecated publications, not aliases. Remove\nthem before installing the canonical package:\n\n```bash\nclaude plugin uninstall prd-spec-generator@prd-spec-generator-marketplace\nclaude plugin marketplace remove prd-spec-generator-marketplace\nclaude plugin marketplace add cdeust/ai-architect-mcp-spec\nclaude plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace\n```\n\nCallers that used `prd-spec-generator:generate-prd` must use\n`ai-architect-mcp-spec:generate-prd`. The `prd-gen` MCP server name,\n`@prd-gen/*` private workspace packages, `PRD_GEN_*` environment variables,\nand `.prd-gen` local data directory remain stable internal interfaces; they do\nnot keep the deprecated publication installed.\n\nPlugin-scoped MCP tool names include both the publication name and the stable\nserver key, so prompts, automation, and allowlists must migrate the complete\nprefix:\n\n- old: `mcp__plugin_prd-spec-generator_prd-gen__<tool>` <!-- mcp-prefix-allow-legacy -->\n- new: `mcp__plugin_ai-architect-mcp-spec_prd-gen__<tool>`\n\nGemini CLI also keys installed extensions by the manifest name. Replace an\ninstalled extension under the former identity instead of updating it in place:\n\n```bash\ngemini extensions uninstall prd-spec-generator\ngemini extensions install https://github.com/cdeust/ai-architect-mcp-spec\n```\n\n### Companion ecosystem\n\nFor full effect, install the three companion plugins so the pipeline can\nconsume codebase intelligence, persistent memory, and the genius-agent\npanel:\n\n```bash\nclaude plugin marketplace add cdeust/ai-architect-mcp-codebase  # codebase graph intel\nclaude plugin marketplace add cdeust/Cortex                  # persistent memory\nclaude plugin marketplace add cdeust/zetetic-team-subagents  # the genius + team agents\n\nclaude plugin install ai-architect-mcp-codebase\nclaude plugin install hypermnesia-mcp\nclaude plugin install zetetic-team-subagents\n```\n\nEach plugin is independently useful; together they are the ai-architect\necosystem. See [Companion ecosystem](#companion-ecosystem) above.\n\n### Building from source\n\nFor development or to run the audit cycle locally:\n\n```bash\ngit clone https://github.com/cdeust/ai-architect-mcp-spec.git\ncd ai-architect-mcp-spec\npnpm install --frozen-lockfile\npnpm build      # builds all 9 buildable packages via tsc\npnpm bundle     # produces the standalone mcp-server/index.js\npnpm test       # 1506 tests (vitest workspace, all packages; the\n                # ai-architect-mcp-codebase wire contract is pinned\n                # unconditionally — see docs/INTEGRATION-TESTING.md)\n```\n\n`pnpm verify` runs all of the above (install + build + bundle + test) —\nsame as CI.\n\n**Prerequisites for source builds:** Node.js 20.x or 22.x, pnpm v10+\n(`corepack enable && corepack prepare pnpm@10`).\n\n### Smoke-test offline\n\n```bash\n# Reducer end-to-end without a real host (uses the canned dispatcher):\npnpm test --filter @prd-gen/orchestration smoke\n\n# Benchmark KPI run:\npnpm test --filter @prd-gen/benchmark pipeline-kpis\n```\n\nBoth run in <2s on an M-series Mac. No LLM calls, no MCP traffic — the\nreducer is fully driven by canned ActionResults so you can audit behaviour\noffline.\n\n### Use with other MCP hosts\n\nHonest scoping first. The **full pipeline is host-dependent**: the reducer\nreturns actions (`ask_user`, `spawn_subagents`, `write_file`) that assume a\nhost which executes them and feeds results back. Claude Code (via the plugin +\n`/generate-prd` skill) remains the only packaged host for that workflow.\n\nCodex and Gemini instead receive the portable **Spec Verifier**: a no-LLM\nsurface with exactly two deterministic tools and the same `audit-prd` and\n`validate-spec` skills:\n\n- `validate_prd_section` — Hard Output Rules against a single section\n- `validate_prd_document` — cross-section checks (SP/AC/FR/test traceability)\n\nInstall it in Codex from the repository marketplace:\n\n```bash\ncodex plugin marketplace add cdeust/ai-architect-mcp-spec\ncodex plugin add ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace\n```\n\nInstall the same package as a Gemini CLI extension:\n\n```bash\ngemini extensions install https://github.com/cdeust/ai-architect-mcp-spec\n```\n\nBoth manifests launch `mcp-server/index.js` with `--profile verifier`. The\nexisting Claude manifest passes no profile and therefore retains the default\n17-tool `full` surface.\n\nA zero-violation result means that the document satisfies the implemented\nstructural rules. It does **not** prove factual accuracy, product value,\nimplementation feasibility, security, or semantic correctness.\n\nFor an un-packaged MCP host, clone the repository and select the same narrow\nprofile explicitly. Replace `/abs/path` with the clone location.\n\n```bash\ngit clone https://github.com/cdeust/ai-architect-mcp-spec.git /abs/path/ai-architect-mcp-spec\ncd /abs/path/ai-architect-mcp-spec/mcp-server\nnpm ci --omit=dev\n```\n\n**OpenAI Codex CLI** (`~/.codex/config.toml`, shared with the ChatGPT\ndesktop app and Codex IDE extension):\n\n```bash\ncodex mcp add prd-spec -- node /abs/path/ai-architect-mcp-spec/mcp-server/index.js --profile verifier\n```\n\n**Cursor** (`.cursor/mcp.json`) and **Windsurf**\n(`~/.codeium/windsurf/mcp_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"prd-spec\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/abs/path/ai-architect-mcp-spec/mcp-server/index.js\",\n        \"--profile\",\n        \"verifier\"\n      ]\n    }\n  }\n}\n```\n\n**VS Code** (`.vscode/mcp.json`):\n\n```json\n{\n  \"servers\": {\n    \"prd-spec\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\n        \"/abs/path/ai-architect-mcp-spec/mcp-server/index.js\",\n        \"--profile\",\n        \"verifier\"\n      ]\n    }\n  }\n}\n```\n\n---\n\n## The pipeline\n\nThe reducer produces twenty sequential steps: eleven PRD-generation steps, then nine opt-in post-specs implementation steps entered only through a human gate. Each step emits at most one substantive action; the host executes it and feeds the result back. A typical trial-tier feature run (11 sections) takes ~62 host-visible iterations.\n\n| # | Step | What it produces |\n|---|------|------------------|\n| **1** | `banner` | Welcome banner with run ID + feature description + capability summary |\n| **2** | `preflight` | Probes the required ecosystem MCPs (Cortex, ai-architect) before the pipeline depends on them; skippable via `skip_preflight` |\n| **3** | `context_detection` | Detects PRD type from trigger words; asks user when ambiguous |\n| **4** | `input_analysis` | Calls `index_codebase` (ai-architect-mcp-codebase) when a path is provided; sets `codebase_graph_path` |\n| **5** | `feasibility_gate` | Detects epic-scope inputs (≥2 EPIC_SIGNALS); asks user to focus |\n| **6** | `clarification` | Compose-then-answer rounds (4–10 depending on tier); short-circuits on \"proceed\" |\n| **7** | `budget` | Per-section retrieval/generation token allocation via Cortex paper's 60/30/10 split |\n| **8** | `section_generation` | One section at a time: Cortex recall → engineer draft → validate → (retry up to 3) |\n| **9** | `jira_generation` | Synthesises JIRA tickets from requirements + user_stories + acceptance_criteria |\n| **10** | `file_export` | Writes 9 files (6 core + 3 companion) per SKILL.md |\n| **11** | `self_check` | Two-phase multi-judge verification (see below); typed `verification` field on `done` |\n\nSteps 12–20 are the opt-in post-specs implementation loop: `implementation_gate` (human gate — \"Implement\" vs \"PRD only\"; also writes `10-verification-report.md`) → `pre_impl_grounding` → `implementation` (engineer subagent in an isolated worktree) → `post_impl_verification` (index → detect changes → semantic diff → security gates) → `testing` → `review` (a FAIL verdict retries `implementation` on the same worktree, bounded by `REVIEW_RETRY_CAP`) → `pr_gate` (mandatory human gate before any push) → `pr_creation` → `finalize`. Answering \"PRD only\" at `implementation_gate` skips straight to `finalize`; `complete` is the terminal marker, not a step.\n\nEvery step is independently testable (`stepOnce(state, result?)` returns the same shape as the runner). The runner coalesces `emit_message` actions internally so the host never sees a no-op.\n\n---\n\n## The MCP tools\n\nThree surfaces. The reducer drives the full pipeline; the validation + verification\n+ budget tools can be consumed directly by other systems without entering the\npipeline; the diagnostics surface exposes config + health + history.\n\n```\nReducer (3):\n  start_pipeline             Initialize a run; returns first NextAction\n  submit_action_result       Drive the reducer one step; returns next NextAction\n  get_pipeline_state         Read-only state snapshot for diagnostics\n\nValidation (2):\n  validate_prd_section       Hard Output Rules — single section\n  validate_prd_document      Cross-section checks (SP/AC/FR/test traceability)\n\nVerification (3):\n  plan_section_verification  Extract claims + select judge panels\n  plan_document_verification Same, document-wide\n  conclude_verification      Aggregate JudgeVerdict[] → VerificationReport;\n                             accepts optional `claims` array carrying\n                             `external_grounding` so oracle-resolved ground\n                             truth can replace LLM-only consensus where\n                             schema/math/code/spec oracles are available\n\nBudget + feedback (2):\n  coordinate_context_budget  Per-section token allocation\n  map_failure_to_retrieval   Validation failure → corrective Cortex query\n\nDiagnostics (7):\n  get_config, read_skill_config, check_health, get_prd_context_info,\n  list_available_strategies, get_quality_history, get_strategy_effectiveness\n```\n\nEach tool takes structured Zod-validated arguments and returns a typed response. No tool calls an LLM — section drafts and judge verdicts come back via the host's `spawn_subagents` action so the same pipeline runs against any agent runtime.\n\n---\n\n## Multi-judge verification\n\nThe `self_check` step is a two-phase contract. Phase A plans the verification batch and persists a snapshot of `(claim_ids, judges)` to state. Phase B receives the verdicts, parses them against the snapshot, and aggregates via the consensus engine.\n\n```\nplan_document_verification(sections[])\n  → extracts atomic Claims (FR-001, AC-005, NFR-LATENCY-1, ...)\n  → selects a panel per claim type:\n      architecture        → liskov + alexander + dijkstra + architect\n      performance         → fermi + carnot + curie + erlang\n      security            → wu + ibnalhaytham + security-auditor\n      data_model          → mendeleev + dba + lavoisier\n      acceptance_criteria → toulmin + popper + test-engineer\n      ...\n\n[host spawns the panel; each agent returns a JSON verdict]\n\nconclude_verification(verdicts[])\n  → Per claim, runs consensus():\n      strategy: weighted_average (default) | bayesian\n      fail_threshold: 0.5  (≥50% confidence-weighted FAIL → forces FAIL)\n      precautionary tie-breaker: more-severe verdict wins\n  → distribution_suspicious flag fires when 100% PASS over ≥5 claims\n  → returns ConsensusVerdict[] with full distribution + dissenting list\n```\n\nThe verdict taxonomy is deliberately five-level — not binary. NFR claims (latency, fps, throughput, storage) **MUST NOT receive PASS**: they are SPEC-COMPLETE if a measurement method is specified, NEEDS-RUNTIME otherwise. Judges that default to PASS for everything are caught by the `distribution_suspicious` detector and flagged in the typed `done.verification` field.\n\n---\n\n## Calibration & falsification\n\nThe verification subsystem is itself a hypothesis: that *consensus weighted by historically-calibrated reliability* outperforms *consensus weighted by a uniform prior*. The closed loop below is what tests it.\n\n1. **Observe.** Each verification run can flush per-judge observations (claim_id, claim_type, judge_id, verdict, oracle_truth?) to a SQLite reliability repository. Observations carry an `external_grounding` field that propagates from `Claim` through the orchestrator to the oracle resolution path; when an external oracle (Ajv schema, mathjs, `tsc`, `validateSection`) can resolve the claim, its truth replaces LLM-only consensus.\n2. **Calibrate.** On subsequent runs, calibrated posteriors weight consensus per judge, per `claim_type`. A 20% control-arm partition is forced-explored using the prior (`getReliabilityForRun` / `getRetryArmForRun` decide which arm a given run lands in deterministically from `run_id`). Without the control arm, calibration-on-calibration looks like progress whether or not it actually is.\n3. **Compare.** Cross-arm metrics (`computeAblationComparison`, `computeReliabilityComparison`, `computeKpiGateComparison`) run paired-bootstrap CIs (Efron & Tibshirani 1993 §16.4; deterministic mulberry32 RNG; 12-decimal reproducibility pin) and emit one of three falsifiable recommendations: `calibrated_helps`, `prior_helps`, or `inconclusive_underpowered`.\n4. **Seal.** Held-out partitions are committed to lock files (`maxattempts-heldout.lock.json` for §4.2, `kpigates-heldout.lock.json` for §4.5, `heldout-partition.lock.json` for the §4.1 50-claim externally-grounded corpus) with a sha256 hash of the partition. The cross-arm metric functions accept a `SEAL_VERIFIED` typeof sentinel as a parameter; the only way to obtain that sentinel is to verify the seal first. Peeking at a held-out partition before evaluation is a type error.\n5. **Ground.** Where an external oracle can resolve a claim deterministically, it does. Where it cannot, `OracleUnavailableError` is thrown rather than fabricating a stub-mode truth. This is the line that breaks annotator-circularity: judges trained against (or biased toward) LLM-style reasoning cannot poison calibration that uses non-LLM truth.\n\nThe lock files, the seal-verification dance, and the control-arm partition together mean: when a cross-arm comparison says \"calibrated_helps with 95% CI excluding zero,\" the claim is *measured*, not vibes-checked. When it says \"inconclusive_underpowered,\" that is also a falsifiable claim — you need more data, not more confidence.\n\n---\n\n## Architecture\n\nTen workspace packages, each independently buildable, with strict Clean Architecture layering enforced by package boundaries.\n\n```\ncore              ← domain types, schemas, agent identities\n                    │  no I/O, no infrastructure dependency\n                    │  Zod-validated; the only place where verdict /\n                    │  section_type / capability shapes are defined\n                    ▼\nvalidation        ← Hard Output Rules (per-section + cross-section)\n                    │  pure functions; no I/O\n                    ▼\nstrategy          ← thinking-strategy selector (genius pattern routing)\n                    │\nmeta-prompting    ← prompt builders for clarification / draft / jira\n                    │  pure string composition\n                    ▼\nverification      ← claim extraction + judge selection +\n                    │  consensus engine (weighted_average + Bayesian)\n                    │  + buildJudgePrompt\n                    ▼\norchestration     ← stateless reducer, 20 step handlers, runner\n                    │  step(state, result?) → next_state, action\n                    │  emit_message coalescing; canned-dispatcher utility\n                    ▼\necosystem-adapters← StdioMcpClient, AiArchitectCodebaseClient, CortexClient\n                    │  the only package allowed to do I/O\n                    ▼\nmcp-server        ← composition root; 17 tools registered;\n                    │  evidence repository (better-sqlite3, optional)\n                    ▼\nbenchmark         ← pipeline KPI measurements + golden-fixture HOR scoring\n                    │  + calibration/ subtree:\n                    │    · ReliabilityRepository (SQLite, observation flush)\n                    │    · Kaplan-Meier + log-rank + Schoenfeld N\n                    │    · Clopper-Pearson exact CI + XmR control charts\n                    │    · paired-bootstrap (Efron-Tibshirani 1993 §16.4)\n                    │    · external oracles (Ajv / mathjs / tsc / validate)\n                    │    · machine-class detector + frozen-baseline gates\n                    │    · sealed held-out lock files (sha256 + SEAL_VERIFIED)\n                    │    · production-mode dispatcher + AgentInvoker seam\n                    │  Audit lineage: JSONL + .xmr sidecars per run.\nskill             ← SKILL.md + slash-command definitions for Claude Code\n```\n\n### Dependency rule (absolute)\n\nEvery package's `package.json` is checked: `core` depends only on `zod`; `verification` depends only on `core`; `orchestration` depends on `core`/`validation`/`verification`/`meta-prompting` (NOT on `ecosystem-adapters`); `ecosystem-adapters` depends on `core` + `verification`; `mcp-server` is the only place where everything composes.\n\nA cross-audit found and fixed two layer violations:\n- `orchestration` was importing `extractJsonObject` and `buildJudgePrompt` from `ecosystem-adapters` — pure utilities lived in the wrong package; moved to `core` and `verification` respectively.\n- Pure domain types (`Claim`, `JudgeVerdict`, `JudgeRequest`, `AgentIdentity`) lived in `ecosystem-adapters/contracts/subagent.ts`; moved to `core/domain/agent.ts`. The infrastructure package now re-exports them as a backward-compat shim.\n\n---\n\n## What this fixes that previous PRD generators don't\n\n| Failure mode | What we do |\n|---|---|\n| **Section drift between turns** | Single immutable `PipelineState` snapshot per step; reducer is pure; host can replay any step |\n| **Hallucinated symbols** | `validate_prd_section` runs Hard Output Rules; symbols cross-checked against `ai-architect-mcp-codebase` graph if `codebase_path` is set |\n| **NFRs claiming PASS without measurement** | Verdict taxonomy refuses PASS for latency/throughput/fps/storage; consensus engine forwards SPEC-COMPLETE / NEEDS-RUNTIME |\n| **Confirmatory bias (every judge says PASS)** | `distribution_suspicious` flag fires at 100% PASS over ≥5 claims; surfaced in typed `done.verification.distribution_suspicious` |\n| **Acceptance criteria not traceable to requirements** | Cross-document validator checks FR-AC coverage and AC numbering gaps |\n| **Tests claiming \"comprehensive\" without listing what they cover** | Test-traceability rule: every section's claimed test must reference an FR or AC ID |\n| **Retries that use the same context as the failure** | `map_failure_to_retrieval` closes the validator→Cortex feedback loop; corrective queries before retry |\n| **Magic-number budgets (\"we'll use 4K tokens for retrieval\")** | `coordinate_context_budget` produces per-section allocations from the canonical SECTIONS_BY_CONTEXT plan |\n\n---\n\n## How it composes with the rest of the ecosystem\n\n```\n                            ┌────────────────────────────────────┐\n                            │         Claude Code (host)         │\n                            └────────────────────┬───────────────┘\n                                                 │ stdio MCP\n              ┌──────────────────────────────────┼──────────────────────────────────┐\n              ▼                                  ▼                                  ▼\n   ┌───────────────────┐              ┌────────────────────┐              ┌───────────────────┐\n   │   ai-architect-   │   graph_path │   ai-architect-    │  recall      │      Cortex       │\n   │   mcp-codebase    │ ───────────► │   mcp-spec         │ ◄─────────── │   (memory engine) │\n   │   (Rust MCP)      │              │   (TS MCP)         │              │   (Python MCP)    │\n   │                   │   symbols    │                    │  excerpts    │                   │\n   │   read-only       │ ◄──────────► │   stateless        │ ───────────► │   thermodynamic   │\n   │   intelligence    │              │   reducer          │              │   memory          │\n   └───────────────────┘              └─────────┬──────────┘              └───────────────────┘\n                                                │\n                                                │ spawn_subagents\n                                                ▼\n                                  ┌─────────────────────────────┐\n                                  │   zetetic-team-subagents    │\n                                  │   97 genius + 19 team       │\n                                  │   Each judge cites its      │\n                                  │   primary paper.            │\n                                  └─────────────────────────────┘\n```\n\nEach project owns one concern. `ai-architect-mcp-codebase` knows what's true about the code. Cortex knows what we already decided. zetetic-team-subagents knows how to reason about a specific shape of claim. **AI Architect MCP Spec** is the deterministic glue that turns those three signals into a PRD an agent can act on.\n\n---\n\n## The Zetetic Standard\n\nEvery load-bearing constant in this codebase carries a `// source:` annotation. Three forms are accepted:\n\n```typescript\n// source: <citation>          // a paper, a spec, a referenced design doc\n// source: benchmark <path>    // a committed benchmark whose output produced this value\n// source: provisional heuristic — <calibration plan>\n                               // honest admission; tells the next reader\n                               // (a) why the value is what it is today and\n                               // (b) what evidence would change it\n```\n\nThe cross-audit found and tagged every previously bare constant. Examples:\n\n```typescript\n// pipeline-kpis.ts\nconst KPI_GATES = {\n  /** source: provisional heuristic. Smoke baseline = 62 iterations on\n   *  trial+codebase; cap is 100 (~60% headroom). dijkstra cross-audit\n   *  derived a structural max of 9 emit_message hops; the substantive-\n   *  action count builds on that. Replace with measured P95 + 1σ once\n   *  the calibrated baseline has enough runs. */\n  iteration_count_max: 100,\n  ...\n};\n\n// verification/consensus.ts\n/** source: provisional heuristic — Beta(7,3) (mean 0.7, ESS=10,\n *  moderately informative toward reliability). Replaced per agent by\n *  Beta(α+correct, β+incorrect) once calibrated from history. */\nconst DEFAULT_RELIABILITY_PRIOR_MEAN = 0.7;\n```\n\nThe four pillars (consistent / true / useful / necessary) and the seven rules of zetetic inquiry are inherited from the [zetetic-team-subagents standard](https://github.com/cdeust/zetetic-team-subagents#the-zetetic-standard). Provisional values are not silently propagated as truth.\n\n---\n\n## What this system does not do\n\nThe same standard applied to itself.\n\n1. **The PRD pipeline does not write code — and the server itself never does.** Steps 1–11 produce a PRD; symbols in the PRD are validated against the graph but never edited by us. The opt-in implementation loop (steps 12–20) runs only when a human answers \"Implement\" at `implementation_gate`; there, the host's engineer/test-engineer/code-reviewer subagents write, test, and review the implementation in an isolated worktree, and nothing is pushed or turned into a PR without the mandatory `pr_gate` approval. This server only emits `spawn_subagents` actions — it never edits source files or pushes branches itself.\n2. **It does not validate prose quality.** Hard Output Rules check structural invariants (FR numbering, AC traceability, NFR shape, cross-references). They do not check whether a sentence is well-written or persuasive. That is what the multi-judge phase is for, and even there the judges return verdicts on *claims* — atomic assertions — not on style.\n3. **The judge phase is end-to-end testable but the judges are not deterministic.** In tests we use a canned dispatcher that returns 100% PASS by construction; the `distribution_suspicious` detector exists precisely because real judge panels can also degenerate into confirmatory consensus, and we do not pretend otherwise.\n4. **The KPI gates are calibrated, not hand-picked.** `iteration_count_max`, `wall_time_ms_max`, and `mean_section_attempts_max` are calibrated against the K=100 frozen baseline with Clopper-Pearson exact CIs, per-machine-class wall_time normalization, and `loadCalibratedGates` + `hold_provisional` ratchet protection. The lock file commits a content-hash of the baseline; mutating it post hoc fails the seal verification. Where data is still thin, gates remain `hold_provisional` rather than locked. See [docs/PHASE_4_PLAN.md](docs/PHASE_4_PLAN.md) for the full pre-registration.\n5. **Citation presence ≠ citation validity.** A `// source: Knuth 1998` comment satisfies the convention whether or not Knuth 1998 exists or supports the value. We enforce that the citation IS THERE; the cross-audit cycle (genius + team review every phase) is what keeps it honest.\n\n---\n\n## Reproducing the audit cycle\n\nThe repo ships a multi-agent cross-audit workflow. After every non-trivial phase:\n\n```bash\n# Engineering team review:\n#   architect, code-reviewer, refactorer, test-engineer, security-auditor,\n#   devops-engineer, dba (when relevant)\n\n# Genius team review:\n#   feynman (integrity), curie (measurement), popper (falsifiability),\n#   dijkstra (correctness), shannon (signal), deming (variation),\n#   poincare (qualitative), ...\n```\n\nEach agent reads the current state of the code (not from memory) and produces a ranked finding list, severity-ranked. Findings are closed in the cycle that raised them; anything that cannot be closed without new measurement is carried with the evidence required to close it written down, so a deferral is a stated obligation rather than a silence.\n\n---\n\n## Project layout\n\n```\npackages/\n├── core/                  Domain types · schemas · agent identities · evidence repo\n├── validation/            Hard Output Rules · per-section + cross-section validators\n├── verification/          Claim extraction · judge selection · consensus engine\n├── meta-prompting/        Prompt builders (clarification / draft / jira)\n├── strategy/              Thinking-strategy selector\n├── orchestration/         Stateless reducer · 20 step handlers · runner · canned-dispatcher\n├── ecosystem-adapters/    StdioMcpClient · AiArchitectCodebaseClient · CortexClient\n├── mcp-server/            Composition root · 17 MCP tools registered\n├── benchmark/             Pipeline KPI measurement · golden-fixture HOR scoring\n│   └── calibration/       ReliabilityRepository · KM survival ·\n│                          Clopper-Pearson · XmR · paired-bootstrap ·\n│                          external oracles · sealed held-out partitions ·\n│                          production-mode dispatcher\n└── skill/                 SKILL.md · slash-command definitions\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n**Project documents:** [ROADMAP](docs/ROADMAP.md) (what the project intends to\ndo, and what it will not do, for the next year) ·\n[CONTRIBUTING](CONTRIBUTING.md) (how to propose a change,\nand the testing policy) · [GOVERNANCE](GOVERNANCE.md) (who decides, and what\nhappens to the project if the maintainer stops) · [SECURITY](SECURITY.md) (how\nto report a vulnerability, and the supply-chain guarantees) ·\n[Assurance case](docs/ASSURANCE-CASE.md) (the security argument and where it\nstops) · [CODE OF CONDUCT](CODE_OF_CONDUCT.md) · [CHANGELOG](CHANGELOG.md).\n\nThis software is the independent work of Clément Deust. It was developed\noutside any employment relationship and is not affiliated with, endorsed by,\nor owned by any past or present employer. It is part of the ai-architect\necosystem ([Cortex](https://github.com/cdeust/Cortex),\n[ai-architect-mcp-codebase](https://github.com/cdeust/ai-architect-mcp-codebase),\n[zetetic-team-subagents](https://github.com/cdeust/zetetic-team-subagents)).\n\nCitations and primary sources for algorithms and constants are documented\ninline in the code via `// source:` annotations per the project's\nsource-discipline rules. Removing those annotations does not change the\nlicense terms but does forfeit attribution to the original research the\ncode is built on.\n\n---\n\n<p align=\"center\">\n  <em>Don't ship a PRD that hallucinates a function it can't measure.<br>\n  Ship one whose every claim was judged by Pearl, Curie, Liskov, and a panel of seven others, validated against the call graph, and grounded in what Cortex remembers from yesterday.</em>\n</p>\n",
  "bytes": 37687,
  "sha": "e6d0eac38c447bfda12d55dc2b6e640108e0cc8f7ba381c9b3212c2de901a96f",
  "repo_slug": "cdeust/ai-architect-mcp-spec",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cdeust_ai_architect_mcp_spec_9be502d8/readme"
}