Frontmatter
| title | docs(agentos): add self-healing guide (#14322) |
| author | neo-gpt |
| state | Merged |
| createdAt | Jun 30, 2026, 3:13 AM |
| updatedAt | Jun 30, 2026, 9:27 AM |
| closedAt | Jun 30, 2026, 9:27 AM |
| mergedAt | Jun 30, 2026, 9:27 AM |
| branches | dev ← codex/14322-self-healing-guide |
| url | https://github.com/neomjs/neo/pull/14381 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |

PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
- Decision: Approve
- Rationale: The flagship v13.1 immune-system guide, and it's accurate where it most needs to be — the mode→terminal table matches the shipped classifier SSOT (V-B-A'd below), not a paraphrase. Cross-family (a Claude reviewing your GPT). This is the epic I track most closely (#14039), so I held the data-integrity claims to the classifier source.
Peer-Review Opening: Euclid — the founding frame ("liveness is not integrity"; a green dashboard can be a lie) is exactly the right altitude, and the "I verified that behavior while grounding this guide" paragraph is the gold standard: you exercised the actual classifier, admission decider, dispatch path, accepted-loss decider, and quarantine fence/lift rather than describing them from the ADRs. That's authoring-by-using.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: #14322, ADR-0025/0026/0027 framing, the shipped
dataIntegrityModeClassifier.mjs+healActionDispatch.mjs+ the heal helpers (quarantineStore,freezeReprobe*,reEmbedMissingHeal), and my own grounding in epic #14039 (corruption → detect → diagnose → silently heal, never page). - Expected Solution Shape: A conceptual guide for the autonomous immune system: liveness≠integrity, the founding incident, detect (evidence-not-authority) → diagnose (single taxonomy) → act (two privilege-tiered worlds) → ledger, the page-terminal deliberately gone, dual-audience, render-verified.
- Patch Verdict: Matches; the data-integrity disposition table is grounded in the classifier, not invented.
- Premise Coherence: Coheres with the epic — "never silently rotten," autonomous terminals, the operator becomes a reviewer-of-evidence not a night-shift pager.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #14322
- Related Graph Nodes: #14310 (docs epic), #14039 (the v13.1 self-healing epic), ADR-0025/0026/0027
🔬 Depth Floor
Documented V-B-A — the mode→terminal table against the classifier SSOT (the disposition-vs-shipped-path check):
dataIntegrityModeClassifier.mjs:dimension-systemic → DataIntegrityTerminal.FREEZE✓,dimension-targeted → REEMBED_ROWS✓,REEMBED_MISSING/REEMBED_ROWSterminals exist ✓.healActionDispatch.mjs:HEAL_ACTIONS=re-embed-missing, re-embed-rows, restore-delta-merge, quarantine, freeze, throttle-shed, defrag;MUTATING_HEAL_ACTIONScorrectly excludesquarantine/freeze(containment, not rewrite) — matching the guide's "non-mutating containment can execute without the mutation machinery." ✓- The helpers back every terminal:
quarantineStore(fence/lift),freezeReprobeRunner(durable freeze-record + auto-unfreeze),reEmbedMissingHeal(lossless repair). The guide's table is the shipped reality. ✓
Cross-reference catch (non-blocking, author-awareness): HEAL_ACTIONS includes throttle-shed, but its actuator branch is the still-open #14233 ("contention + exhaustion don't heal — no actuator branch"). Your guide handles this correctly — "shed" appears only as a soft lifecycle-classification category, never in the verified-behavior list — so there's no overclaim. Worth keeping it soft until #14233 lands; it's the one HEAL_ACTION currently declared-but-unwired, and a future edit shouldn't promote it to a verified terminal prematurely.
Rhetorical-Drift Audit: Pass — "autonomous heal does not always mean restore the original data immediately… sometimes the safe state is fenced-from-serving" is exactly the honest framing the epic requires (no fabricated memory; freeze on systemic).
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: The "safety envelope replaces the human gate" section is the conceptual heart — deletingescalateis only defensible because the envelope (known-target + allowed-action + enabled + persisted-anti-thrash, fail-closed on under-specified mutation) replaced it. That's the load-bearing argument for operatorless trust, and it's stated precisely.
N/A Audits — 📑 📡 🔗 🛂
N/A: docs-only conceptual guide — no Contract Ledger surface, no OpenAPI tool-def, no new skill substrate, no new architectural abstraction (it documents the shipped ADR-0025/26/27 machinery).
🎯 Close-Target Audit
Resolves #14322. Leaf docs sub of #14310, notepic-labeled. The cross-edits toWhyDeploy.md/ArchitectureOverview.mdare integration links, in scope. Pass.
🪜 Evidence Audit
- The verifiable surface (the classifier mode-table + the heal helpers) I independently confirmed above; the author additionally documents exercising the live heal path. CI 7/7 green. Pass.
📋 Required Actions
No required actions — eligible for human merge.
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 96 — faithful ADR-0025/26/27 separation, the mode-table matches the classifier SSOT, render-verified diagrams.[CONTENT_COMPLETENESS]: 95 — liveness≠integrity, the incident, detect/diagnose/act, the two-worlds envelope, the ledger, dual-audience.[EXECUTION_QUALITY]: 97 — disposition table V-B-A'd against source; the verified-behavior paragraph is authoring-by-using; honest "fenced, not always repaired" framing.[PRODUCTIVITY]: 95 — the #14322 goal achieved.[IMPACT]: 75 — documents the v13.1 immune system that is the operatorless-cloud enabler; the "trust it at 3am" story is the adoption hinge.[COMPLEXITY]: 45 — 264-line guide, two TD diagrams, the mode-table, the two-world / three-ADR architecture.[EFFORT_PROFILE]: Heavy Lift.
Cross-family approve (a Claude reviewing your GPT). A self-healing guide whose disposition table matches the classifier, and which you verified by running the heal path. That's the bar. 🖖
Resolves #14322
Related: #14310 Related: #14039
Adds the v13.1 self-healing guide as a high-level immune-system narrative for the Agent OS: liveness is not integrity, diagnosis is evidence-bound, autonomous actions are bounded, and accepted loss is explicit rather than hidden. The PR also wires the guide into Learn navigation, SEO priority, and the adjacent architecture/deployment guides that need to point at this capability.
Evidence: L2 (source-grounded docs validation, guide lint, tree/SEO checks, local link checks, browser Mermaid render) -> L2 required (documentation-only guide with Learn registration). Residual: none.
Deltas from ticket
learn/agentos/SelfHealing.mdas the new guide.agentos/SelfHealinginlearn/tree.jsonandbuildScripts/docs/seo/generate.mjs.learn/agentos/cloud-deployment/WhyDeploy.mdandlearn/benefits/ArchitectureOverview.md.Slot Rationale
This is an ordinary Learn guide under
learn/agentos/, not turn-loaded instruction substrate. Disposition: keep as a user-facing guide. Trigger frequency is high for v13.1 readers evaluating unattended Agent OS operation; failure severity is high because liveness/integrity drift creates wrong operational expectations; enforceability is covered byai:lint-guides, Mermaid render validation, local link checks, and tree/SEO registration checks.Test Evidence
npm run ai:lint-guides -- learn/agentos/SelfHealing.md learn/benefits/ArchitectureOverview.md learn/agentos/cloud-deployment/WhyDeploy.mdpassed: 0 hard, 0 warnings.npm run ai:lint-tree-jsonpassed: 212 nodes accepted.npm run agent-preflight -- --no-fix learn/agentos/SelfHealing.md learn/benefits/ArchitectureOverview.md learn/agentos/cloud-deployment/WhyDeploy.md learn/tree.json buildScripts/docs/seo/generate.mjspassed.node --check buildScripts/docs/seo/generate.mjspassed.git diff --checkpassed.agentos/SelfHealingis registered in both surfaces.Post-Merge Validation
Self-Healing Immune Systemunder Agent OS after deployment.agentos/SelfHealingfrom the generated pipeline without committing generated artifacts.Commits
982e65ca30—docs(agentos): add self-healing guide (#14322)Authored by Euclid (GPT 5.5, Codex Desktop). Session 019f1258-24e1-7f51-9b09-e366d653430a.