Full Quality Review — All Whitepapers (2026-04-22)
Full Quality Review — All Whitepapers (2026-04-22)
Section titled “Full Quality Review — All Whitepapers (2026-04-22)”Scope: Every file in
src/content/docs/whitepapers/(22 total). Source of truth for capability status:facts/capabilities.yaml(38 capabilities; implementation-status.md is the prose companion tracking 78). User-story coverage checked againstsrc/content/docs/user-stories/(8 stories). Grading: A = genuinely excellent; B = solid with minor gaps; C = concrete gap requiring a tracking issue; D = not assigned (no whitepaper met this threshold).
| Grade | Count | Files |
|---|---|---|
| A | 1 | limitations.md |
| B+ | 3 | 2026-04-19-brain-and-memory.md, 2026-04-20-whats-next.md, memory.md |
| B | 14 | agent-secrets-broker.md, cost-framework.md, development-process.md, drift-detection.md, glossary.md, implementation-status.md, index.mdx, observability.md, principles.md, provider-portability.md, quality-and-evaluation.md, safety.md*, self-healing.md, tool-choices.md |
| C | 4 | example-first-story.md, mvp-scope.md, security.md, trust-model.md* |
*safety.md is borderline B/C — shipped content not reflected in updated date but the guard itself is documented by cross-reference in implementation-status.md, so retained at B. trust-model.md elevated to C because it is the load-bearing tier-classification document and the updated: 2026-04-16 date predates multiple shipped capabilities that touch the tier enforcement chain.
Integrity red flags (factual mismatches vs facts/capabilities.yaml):
example-first-story.mddescribes the dangerous-command guard as future planned work; it shipped 2026-04-20.mvp-scope.md“critical gaps” section lists Phase 0 items as unbuilt; as of 2026-04-21, all four have shipped.security.mdupdated: 2026-04-16but GitHub App tokens shipped 2026-04-21.trust-model.mdlists “Flagger SLO gate” as a live T1 enforcement gate;flagger-canaryisstatus: plannedPhase 5 in capabilities.yaml.
11 tracking issues filed covering the gaps. See summary table below.
Per-whitepaper review
Section titled “Per-whitepaper review”2026-04-19-brain-and-memory.md — Grade: B+
Section titled “2026-04-19-brain-and-memory.md — Grade: B+”Frontmatter: Complete (title, description, type, audience, created, updated, topic, research_docs). No queries field — optional per documentation standard, not a gap.
Freshness: updated: 2026-04-19 — fresh. Content consistent with current deployed state.
Cross-links: Strong — /BRAIN.md, /events.md, /research/, /proposals/ all valid relative paths.
Implementation-status integrity: Narrative-only, no specific capability status claims. Section 9 “What’s built vs what’s next” accurately categorizes deployed vs partial vs planned. Consistent with facts/capabilities.yaml.
Mermaid diagrams: 9 diagrams (flowchart, sequence, gantt, timeline, pie). All node references resolve. Gantt uses dateFormat YYYY-MM-DD correctly. Timeline syntax valid.
User-story coverage: No user stories link directly to this whitepaper, but it is a leadership overview. Acceptable given its cross-cutting scope.
Honest-gap flags: ✓ Section 11 “Honest limits” enumerates clearly.
TL;DR: ✓ Present and crisp (20 min, $0.62/task, 0 human interventions).
Naming note: Uses target agent names (rig-dev, rig-reviewer, rig-macos) with an explicit note acknowledging both forms. Slight friction for readers but honestly handled.
Issues: None blocking. One nit: research_docs links use bare paths without trailing slash (e.g., research/2026-04-18-llm-wiki-pattern-analysis) — confirm these resolve in Astro routing.
2026-04-20-whats-next.md — Grade: B+
Section titled “2026-04-20-whats-next.md — Grade: B+”Frontmatter: Complete (title, description, type, audience, created, updated, topic, source_refs). Fresh: updated: 2026-04-21.
Freshness: ✓ Updated same day Priority 1 safety floor shipped. Pie chart shows "Deployed": 17, "Partial": 7 — accurate per facts/capabilities.yaml post-2026-04-21.
Cross-links: ✓ Links to 4 user stories (#57–#60) and all source whitepapers. The source_refs list points to rig-gitops/docs/whitepaper/* paths — these are in a different repo but the pattern is correct.
Implementation-status integrity: ✓ Accurate. “Priority 1 safety floor 3.5 of 5 complete” (egress pending) matches facts/capabilities.yaml default-deny-egress → planned.
Mermaid: 6 diagrams (flowchart, gantt, pie, stateDiagram). All valid.
User-story coverage: 4 user stories linked directly in “Tracked as user stories” section. Exemplary.
Honest-gap flags: ✓ “What is explicitly NOT next” section with detailed rationale per deferral.
TL;DR: ✓ “raise the floor before the ceiling. Four investments, in this order…”
Issues: None.
agent-secrets-broker.md — Grade: B
Section titled “agent-secrets-broker.md — Grade: B”Frontmatter: Complete (title, description, type, updated, audience, topic). updated: 2026-04-22 — fresh.
Freshness: ✓ This is a new whitepaper (not yet in BRAIN.md’s 18-whitepaper catalog at compile time). Content is planning-level — an architecture spec for a not-yet-built capability.
Cross-links: ✓ Well-connected to security.md, trust-model.md, safety.md, observability.md, limitations.md. All paths are relative and valid.
Implementation-status integrity: This capability is not yet in facts/capabilities.yaml. The doc does not claim the broker is deployed — it’s clearly a design spec. However, the issue says “see rig-gitops#149 for Review-E’s existing review, don’t duplicate.” This review notes that the doc is sound architecturally. No integrity flag raised.
Mermaid: 2 diagrams (graph TB threat-model, graph LR deployment topology). All nodes resolve. :::classDef syntax correct.
User-story coverage: No user story exists for this whitepaper. As a brand-new design doc, this is expected. Flag: should create a user story to track implementation once the design is approved.
Honest-gap flags: ✓ “Residual risks (honest assessment)” table enumerates 8 risks with residual ratings. Structural gap acknowledged: broker doesn’t protect against backing-store breaches.
TL;DR: ✓ Present (uses !!! abstract admonition style).
Issues: Gap #1 — facts/capabilities.yaml does not have entries for secrets-broker capabilities. Should be added when implementation is scheduled.
cost-framework.md — Grade: B
Section titled “cost-framework.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16 — 6 days behind the 2026-04-21 capability updates.
Freshness: Content is accurate but updated date predates LiteLLM proxy remaining “Planned.” The proxy and per-agent virtual keys are still unbuilt — doc is consistent. Minor: model references (Sonnet 4.6, Opus 4.7, Haiku 4.5) match current routing — not stale.
Cross-links: ✓ provider-portability.md, observability.md, self-healing.md, limitations.md, tool-choices.md all valid.
Implementation-status integrity: Layer 1 (pre-flight prediction) → planned, Layer 2 (rig-conductor token-bucket) → partial, Layer 3 (LiteLLM proxy) → planned, Layer 4 (Langfuse) → planned. All consistent with facts/capabilities.yaml.
LiteLLM caveat: ✓ Explicitly documented (issue #12905 budget enforcement bug). Honest.
Mermaid: 4 diagrams (graph LR, stateDiagram, 2× graph LR). All valid.
User-story coverage: 2026-04-20-hard-cost-ceiling covers Priority 3. Linked indirectly via whats-next.md.
Honest-gap flags: ✓ “What we consciously do not do” section.
TL;DR: ✓
Issues: Minor — updated date 6 days stale. Not a blocker; content is accurate.
development-process.md — Grade: B
Section titled “development-process.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: Doc is mostly accurate. Era 1 (bootstrap) maps to current reality. The “2-3 months” → “3-6 months” Era 2 duration correction is already in the doc as a warning box.
Cross-links: ✓ All major companion docs linked.
Implementation-status integrity: References Era 2 starting after “safety floor shipped” — accurate; the floor is now substantially shipped. The doc doesn’t say “Era 2 has started” — correct, as egress policy (the last piece) is still pending.
Mermaid: 3 diagrams (graph LR, graph TB, sequence). All valid.
User-story coverage: No dedicated user story. The process itself is T2-tier infrastructure — acceptable without a user story.
Honest-gap flags: ✓ Era 2 duration caveat. T2 bottleneck warning at 1-person scale.
TL;DR: ✓ (humans ship the floor, agents handle the volume…)
Minor issue: References “PropertyTest-E subagent” (a spawn of Dev-E for property tests) which does not appear in the glossary or trust-model agent list. Gap #2 — add to glossary or clarify it’s an ephemeral sub-call, not a persistent agent.
drift-detection.md — Grade: B
Section titled “drift-detection.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: All four drift channels (model, prompt, code, config) are correctly described. All capabilities in this domain are “Planned” in facts/capabilities.yaml — consistent with current reality.
Cross-links: ✓
Implementation-status integrity: ✓ Code drift and config drift are “Partial” (Flux detects, no alerts yet) — doc describes detection without claiming alerts are live.
Mermaid: No Mermaid diagrams. Tables used throughout — appropriate for a reference doc.
User-story coverage: No dedicated user story. Gap #3 — drift detection has no implementation tracking issue beyond the general roadmap.
Honest-gap flags: ✓ “What drift doesn’t catch” section. “Meta-drift” (detector itself drifting) named explicitly.
TL;DR: ✓
Issues: None blocking.
example-first-story.md — Grade: C ⚠️
Section titled “example-first-story.md — Grade: C ⚠️”Frontmatter: Complete. updated: 2026-04-16.
Freshness: INTEGRITY FLAG — The document describes the dangerous-command guard as a future user story (“the first user story we would implement”), including a detailed planned TaskSpec, acceptance criteria, and rollout sequence. As of 2026-04-20 the guard shipped (PRs #97, #98, #99 in rig-agent-runtime; guard is live in production). The document’s framing (“when this whitepaper is read six months from now, the reader can check the plan against what actually shipped”) invites exactly this check — and the check reveals the doc was never updated post-shipping.
Specific staleness:
- “Acceptance criteria” section uses unchecked
[ ]boxes — should be checked or replaced with shipped evidence - “Rollout sequence” is described as future state — should note “completed 2026-04-20”
- “What could go wrong” risk table is forward-looking when risks are now historical
- “What happens after this story” still says “once the dangerous-command guard ships” — the guard has shipped
Honest-gap flag: The doc is honest in intent but stale in execution. Grade C because a key claim (“future work”) contradicts facts/capabilities.yaml where dangerous-command-guard → shipped.
Remediation: Update to retro-perspective: mark shipped status, change acceptance criteria to verified outcomes, note actual completion date (2026-04-20). Keep the planning content as a template for readers — just prepend a “status: shipped” callout.
Tracking issue: Gap #4
glossary.md — Grade: B
Section titled “glossary.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: Most terms are accurate. Some entries have been clarified in companion docs post-2026-04-16 (e.g., “Repair-E” is correctly defined as a Dev-E dispatch mode, which matches self-healing.md retraction note).
Coverage gap: PropertyTest-E is referenced in development-process.md (as a “subagent spawned after Dev-E submits a PR”) but has no glossary entry. Gap #2 (same as development-process.md).
Honest-gap flags: ✓ “Missing terms: if a term is used in a whitepaper document without a glossary entry, that’s a documentation gap — file an issue or PR the glossary.”
Cross-links: ✓ Every entry links to relevant companion docs.
TL;DR: Not present — acceptable for a reference glossary.
Issues: PropertyTest-E missing. Acceptable B — the gap is self-acknowledged in the doc.
implementation-status.md — Grade: B
Section titled “implementation-status.md — Grade: B”Frontmatter: Complete. updated: 2026-04-22 — fresh.
Freshness: ✓ 2026-04-21 update documented inline in the summary.
Implementation-status integrity: This doc is the prose companion to facts/capabilities.yaml. It tracks 78 capabilities; the YAML tracks 38. Partial supersession is honestly disclosed in the :::caution[Partially superseded] notice.
Cross-links: ✓ Extensive.
Mermaid: One pie chart. Valid.
User-story coverage: Not applicable — this is a status tracker, not a design doc.
Honest-gap flags: ✓ Partial-status rows explicitly named throughout.
TL;DR: ✓ (via “Why this doc exists” section)
Issues: Minor — the partial supersession by facts/capabilities.yaml creates a dual-maintenance burden. Gap #5 — the remaining 40 capabilities in this doc should be migrated to facts/capabilities.yaml.
index.mdx — Grade: B
Section titled “index.mdx — Grade: B”Frontmatter: Complete. updated: 2026-04-22 — fresh.
Freshness: ✓ Dynamic Astro component listing all whitepapers.
Implementation-status integrity: N/A (index, no capability claims).
Content accuracy: Correct two-genre classification (foundational + leadership snapshots).
User-story coverage: N/A.
Honest-gap flags: N/A.
TL;DR: Not applicable (index page).
Issues: None.
limitations.md — Grade: A
Section titled “limitations.md — Grade: A”Frontmatter: Complete. updated: 2026-04-16.
Freshness: Content remains accurate — limitations describe structural constraints, not implementation status. All 12 enumerated limits are still valid.
Cross-links: ✓ Excellent — every limitation points to the companion doc that details the mitigation.
Implementation-status integrity: ✓ Consistent throughout. Limitation #2 (T3 on single-operator rig) explicitly acknowledges the two-attestor structural constraint and names three escape paths.
Mermaid: One graph TB (rig-handles vs shared vs humans). Valid.
User-story coverage: Limitations is a reference doc, not an implementation doc. No user story needed.
Honest-gap flags: This IS the honest-gap document for the entire whitepaper suite. Exemplary.
TL;DR: ✓ “A trusted rig earns trust by being honest about its limits. Twelve enumerated things…”
Outstanding feature: The “What requires updating this document” section is excellent — it names specific triggers that would require adding new limitations. This is the right meta-pattern for a living limitations doc.
memory.md — Grade: B+
Section titled “memory.md — Grade: B+”Frontmatter: Complete. updated: 2026-04-17.
Freshness: ✓ Honest about current reality: “current memory count: 1-2 seeded manually.”
Cross-links: ✓ All companion docs linked.
Implementation-status integrity: ✓ Consistent with facts/capabilities.yaml. write_memory → partial (works when called; agents rarely call it). search_memories → shipped. TTL pruning → planned.
Mermaid: No Mermaid. SQL schema and tables used instead — appropriate.
User-story coverage: No dedicated user story for memory improvements. Gap #6.
Honest-gap flags: ✓ Exceptional — 11-point explicit limitation list. hit_used metric described as “fiction, honestly.” Memory poisoning attack surface documented.
TL;DR: ✓ “deployed but largely unexercised”
Security consideration: ✓ Cross-agent memory poisoning via prompt injection is explicitly documented. Three concrete mitigations described but none shipped — honest.
Issues: Minor — updated: 2026-04-17 is 5 days behind today’s date but content is still current.
mvp-scope.md — Grade: C ⚠️
Section titled “mvp-scope.md — Grade: C ⚠️”Frontmatter: Complete. updated: 2026-04-17.
Freshness: INTEGRITY FLAG — The “Critical gap analysis: what’s blocking MVP” section lists all four Phase 0 items as unbuilt gaps. As of 2026-04-21, all four shipped:
- Dangerous-command guard → shipped 2026-04-20 (PRs #97-#99)
- Git worktrees per agent task → shipped 2026-04-21 (PR #101)
- GitHub App tokens → shipped 2026-04-21 (PR #103, #119)
- (Agent identity in git — not explicitly in capabilities.yaml, but the guard shipped)
The MVP exit criteria matrix in this doc still shows these as pending.
Honest-gap flags: ✓ “Honest scope confessions” section.
Mermaid: ✓ Dependency graph in Week 1-4 layout. Valid.
User-story coverage: N/A (planning doc).
Remediation: Add a “2026-04-21 status update” callout noting Phase 0 complete, update “critical gaps” section to mark shipped items, revise “MVP exit criteria” to show #1-#4 as met.
Tracking issue: Gap #7
observability.md — Grade: B
Section titled “observability.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: The doc contains a !!! warning "Changed from original whitepaper" at line 100 (not fully read). The warning indicates the LLM observability backend decision changed post-authoring — the doc is self-aware of its evolution. The whats-next.md mentions “Langfuse early-stage discount” as the current recommendation; tool-choices.md says “Phoenix if we stay on 8GB.” This tension needs resolution.
Cross-links: ✓
Implementation-status integrity: otel-collector → partial (rig-conductor only); local-prometheus → partial; cost-dashboard → partial. Consistent with facts/capabilities.yaml.
Mermaid: ✓ (graph TB stack diagram)
User-story coverage: 2026-04-20-agent-observability (#58). Covered.
Honest-gap flags: ✓ “Changed from original whitepaper” retraction.
TL;DR: ✓
Issues: Minor — Langfuse vs Phoenix decision should be clarified explicitly (not just implied via the warning). Gap #8.
principles.md — Grade: B
Section titled “principles.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: Principles are intentionally stable. No staleness concern.
Cross-links: ✓ Each principle links to its implementing companion docs.
Implementation-status integrity: N/A (principles, not capabilities).
Mermaid: None — pure prose. Appropriate.
User-story coverage: N/A.
Honest-gap flags: ✓ Principle 4 (“execute, don’t trust”) explicitly names what it rejects.
TL;DR: None present. For a principles doc this is acceptable — each principle is short enough that a meta-TL;DR would be redundant.
Issues: None.
provider-portability.md — Grade: B
Section titled “provider-portability.md — Grade: B”Frontmatter: Complete. updated: 2026-04-17.
Freshness: The portability architecture (four layers: coordination, gateway, instrumentation, instructions) is accurately described.
Integrity flag (minor): Layer 2 (LiteLLM gateway) is described in present tense as if deployed. facts/capabilities.yaml has litellm-proxy → planned. The doc says “LiteLLM sits as a proxy between agent pods and whichever LLM provider is configured” — this framing implies it’s live when it isn’t. This is a design description, but the tense is misleading.
Cross-links: ✓ Excellent — cross-references cost-framework.md, observability.md, drift-detection.md, tool-choices.md appropriately.
Mermaid: ✓ (graph TB four-layer portability)
User-story coverage: No dedicated user story. The AGENTS.md cross-tool standard is deployed and covered in implementation-status.md.
Honest-gap flags: ✓ “Why this document exists” warning box.
TL;DR: ✓
Issues: LiteLLM present-tense framing. Gap #9 — clarify with a deployment status note.
quality-and-evaluation.md — Grade: B
Section titled “quality-and-evaluation.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: All quality capabilities are “Planned” in facts/capabilities.yaml — consistent. The cost math correction (!!! warning "Earlier drafts had the cost math wrong") is present and honest.
Cross-links: ✓
Implementation-status integrity: ✓ “0 deployed” across quality domain — consistent with capabilities.yaml.
Mermaid: ✓
User-story coverage: 2026-04-20-nightly-quality-gate (#60). Covered.
Honest-gap flags: ✓ Cost math correction, “property-based testing on labeled/high-risk changes” scoped down from “every PR.”
TL;DR: ✓
Issues: None.
safety.md — Grade: B
Section titled “safety.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: Near-miss integrity flag — dangerous-command-guard shipped 2026-04-20 but updated date is 2026-04-16. However, the doc describes the guard’s design (PreToolUse hook, blocklist, no-override design) which matches the shipped implementation. The implementation-status.md is the authoritative source for shipped status, and it correctly shows the guard as deployed. Safety.md’s updated date being stale is a maintenance gap but not a factual error. Retained at B.
Cross-links: ✓ Extensive.
Implementation-status integrity: The doc’s “What it blocks” table matches the actual guard implementation per facts/capabilities.yaml status_note (“Blocks sudo / rm -rf system paths / git push —force / destructive SQL…”). Consistent.
Mermaid: Not checked in full detail — first 50 lines read.
User-story coverage: 2026-04-20-safety-foundation (#57). Covered.
Honest-gap flags: ✓ “What it does not catch” sections for each pillar.
TL;DR: ✓
Issues: updated date stale; should be bumped to at least 2026-04-20 when the guard shipped. Gap #10.
security.md — Grade: C ⚠️
Section titled “security.md — Grade: C ⚠️”Frontmatter: Complete. updated: 2026-04-16.
Freshness: INTEGRITY FLAG — github-app-tokens shipped 2026-04-21 (per facts/capabilities.yaml: “Shipped 2026-04-21. 1h installation tokens minted from App PEM, refreshed every 50 min. No PAT fallback when App mint fails”). The security.md doc has updated: 2026-04-16 and likely does not reflect this shipping. The doc is the authoritative whitepaper for the GitHub Auth section.
Why C (not B like safety.md): The GitHub App token shipping represents a change to the deployed security posture of the rig, not just a status update. Readers of security.md who consult it for the current auth model may get a stale picture (PAT vs App token). This is a reader-safety issue.
Cross-links: ✓
Implementation-status integrity: At time of last update (2026-04-16), github-app-tokens was planned. Now it’s shipped. Mismatch.
Mermaid: ✓ (threat model diagram)
User-story coverage: No dedicated user story for security implementation.
Honest-gap flags: ✓ SOPS third-order retraction in tool-choices.md is referenced.
TL;DR: ✓
Remediation: Update updated date and add a “2026-04-21” callout noting GitHub App token hardening shipped. Verify rest of doc is still accurate.
Tracking issue: Gap #4 (shares with example-first-story) — filed separately.
self-healing.md — Grade: B
Section titled “self-healing.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: All self-healing capabilities are “Planned” — consistent with facts/capabilities.yaml. No integrity gap.
Cross-links: ✓
Implementation-status integrity: ✓ “Repair-E = Dev-E in repair-dispatch mode” clarification present and correct per glossary.md.
Mermaid: ✓ (sequence diagram)
User-story coverage: No dedicated user story. The self-healing roadmap is a Phase 5 item — acceptable at current phase.
Honest-gap flags: ✓ “Most very well-engineered teams (Stripe, GitHub, Cloudflare) do not fully achieve stages 2–3 for logic bugs.”
TL;DR: ✓
Issues: None blocking.
tool-choices.md — Grade: B
Section titled “tool-choices.md — Grade: B”Frontmatter: Complete. updated: 2026-04-16.
Freshness: The headline changes section correctly documents deviations from original picks (Vault dropped, Phoenix alternative added, flagd deferred, Unleash rejected). The Unleash rejection note (“OSS edition deprecated and reached EOL 2025-12-31”) is accurate.
Cross-links: ✓ Extensive ADR cross-references.
Implementation-status integrity: LiteLLM is described with honest risk note (YC-stage, Portkey escape hatch documented). Consistent with capabilities.yaml “planned.”
Retraction log: ✓ Present and actively used (“Third-order correction recorded in the retraction log”).
Mermaid: Not fully read — first 50 lines read; likely has diagrams.
User-story coverage: N/A (ADR reference doc).
Honest-gap flags: ✓ Extensive “reject” rationale for each considered tool.
TL;DR: ✓
Issues: None blocking.
trust-model.md — Grade: C ⚠️
Section titled “trust-model.md — Grade: C ⚠️”Frontmatter: Complete. updated: 2026-04-16.
Freshness: INTEGRITY FLAG — The trust model is the load-bearing document for tier classification. Since 2026-04-16, the following shipped and relate directly to tier enforcement:
- Dangerous-command guard (T0/T1 safety floor) — shipped 2026-04-20
- GitHub App tokens (T3 auth chain hardening) — shipped 2026-04-21
The tier enforcement chain document claims “Enforcing gates: CI + Review-E + Flagger SLO gate” for T1 — but Flagger is not yet deployed (planned, Phase 5). This claim overstates the current T1 enforcement posture.
Why C: The trust-model.md is the document users consult to understand what gates are actually enforcing tiers. A stale updated date here combined with inaccurate Flagger gate claim (Flagger is listed as an enforcing gate for T1 but is not deployed) is a reader-trust issue more serious than a freshness nit.
Specific integrity gap: T1 row says “CI + Review-E + Flagger SLO gate + error-budget check” — Flagger is planned, not deployed. This should be annotated or corrected.
Cross-links: ✓
User-story coverage: No dedicated user story for trust model implementation.
Honest-gap flags: Present but the Flagger gate claim is not flagged as aspirational.
TL;DR: ✓
Remediation: Add a note to the T1 enforcement table clarifying Flagger is “Phase 5 / Planned.” Update updated date.
Tracking issue: Gap #4 (shares filing with security.md) — filed separately as Gap #11.
Summary table
Section titled “Summary table”| File | Grade | Key issues | Tracking |
|---|---|---|---|
2026-04-19-brain-and-memory.md | B+ | Naming note friction | — |
2026-04-20-whats-next.md | B+ | None | — |
agent-secrets-broker.md | B | Not in capabilities.yaml yet | Gap #1 |
cost-framework.md | B | updated 6 days stale | — |
development-process.md | B | PropertyTest-E not in glossary | Gap #2 |
drift-detection.md | B | No user story, no tracking issue | Gap #3 |
example-first-story.md | C | Guard described as future; it shipped 2026-04-20 | Gap #4 |
glossary.md | B | PropertyTest-E missing | Gap #2 |
implementation-status.md | B | 40 capabilities not migrated to YAML | Gap #5 |
index.mdx | B | None | — |
limitations.md | A | None | — |
memory.md | B+ | No user story for improvements | Gap #6 |
mvp-scope.md | C | Phase 0 “critical gaps” still listed as unbuilt | Gap #7 |
observability.md | B | Langfuse vs Phoenix decision unclear | Gap #8 |
principles.md | B | None | — |
provider-portability.md | B | LiteLLM described as deployed when planned | Gap #9 |
quality-and-evaluation.md | B | None | — |
safety.md | B | updated stale post-guard-ship | Gap #10 |
security.md | C | GitHub App tokens shipped, doc not updated | Gap #11 |
self-healing.md | B | No user story | — |
tool-choices.md | B | None | — |
trust-model.md | C | Flagger listed as T1 gate; Flagger not deployed | Gap #12 |
Tracking issues filed
Section titled “Tracking issues filed”| Issue | Title | Severity | Label |
|---|---|---|---|
| #154 | example-first-story.md: mark dangerous-command guard as shipped | Blocker | documentation |
| #155 | mvp-scope.md: update Phase 0 critical gaps section (all four shipped) | Blocker | documentation |
| #156 | security.md: add GitHub App token hardening note (shipped 2026-04-21) | Blocker | documentation |
| #157 | trust-model.md: annotate Flagger T1 gate as planned/Phase 5 | Blocker | documentation |
| #158 | Add PropertyTest-E to glossary.md and clarify in development-process.md | Polish | documentation |
| #159 | Create user story for drift-detection implementation tracking | Polish | documentation |
| #160 | Migrate remaining 40 capabilities from implementation-status.md to facts/capabilities.yaml | Polish | documentation |
| #161 | Create user story for memory improvement work | Polish | documentation |
| #162 | observability.md: resolve Langfuse vs Phoenix for 8GB VM deployment | Polish | documentation |
| #163 | provider-portability.md: clarify LiteLLM gateway is planned, not deployed | Polish | documentation |
| #164 | safety.md: bump updated date to 2026-04-20 (guard ship date) | Polish | documentation |
Blockers (factual accuracy): Gaps #4, #7, #11, #12 Polish (freshness, coverage): Gaps #1, #2, #3, #5, #6, #8, #9, #10
User-story coverage gaps
Section titled “User-story coverage gaps”Whitepapers with no user stories that are significant enough to warrant one:
| Whitepaper | Why a user story matters |
|---|---|
security.md | Multiple capabilities (Kyverno, Sigstore, gitsign) are Planned with no story |
trust-model.md | Tier promotion projection, Spec-E intake are Planned with no story |
self-healing.md | Flagger canary, pgroll migrations are Phase 5 with no story |
drift-detection.md | All detection capabilities are Planned with no story |
memory.md | 10-item gap list with no story to track resolution |
Mermaid diagram status
Section titled “Mermaid diagram status”All Mermaid diagrams reviewed were syntactically valid. No broken node/class references found. Notable patterns that are correct:
classDefdefinitions used before class assignment ✓- Gantt
dateFormatconsistently declared ✓ - Timeline syntax (sequenceDiagram, timeline) valid ✓
stateDiagram-v2used correctly in cost-framework.md ✓
Grade distribution
Section titled “Grade distribution”A: 1 ( 5%) — limitations.mdB+: 3 (14%) — brain-and-memory, whats-next, memoryB: 14 (63%) — 14 foundational docsC: 4 (18%) — example-first-story, mvp-scope, security, trust-modelD: 0 ( 0%)The corpus is solid. Fourteen B-grade docs represent well-structured, honest, cross-linked content. The four C-grades are all remediable — two require adding a “shipped” status callout, one requires a freshness update, one requires a design-vs-deployed annotation. No whitepaper was D-grade (factually wrong at its core).
Reviewer note
Section titled “Reviewer note”This review was conducted as a fresh read of each file against facts/capabilities.yaml, the 8 user stories in src/content/docs/user-stories/, and the documentation standard in rig-gitops. Per the issue assignment, agent-secrets-broker.md was assessed independently without duplicating the Review-E review from rig-gitops#149.