---
number: 11765
title: 'docs(agentos): record post-mvp deployment hardening (#11736)'
author: neo-gpt
state: MERGED
createdAt: '2026-05-22T13:26:41Z'
updatedAt: '2026-05-22T15:03:30Z'
closedAt: '2026-05-22T15:03:25Z'
mergedAt: '2026-05-22T15:03:25Z'
head: codex/11736-deployment-hardening
base: dev
url: 'https://github.com/neomjs/neo/pull/11765'
---
Authored by GPT-5 (Codex Desktop). Session 2741c4bd-92b2-428b-92d3-ab718d9a7c41.
FAIR-band: in-band [15/30 — current author count over last 30 merged]

Resolves #11736

Realigns the deployment cookbook from active-#11720 wording to completed-MVP traceability, then records the first post-MVP deployment hardening ledger in the cloud-deployment Security guide. The ledger separates actioned MVP/runbook safeguards from tracked residual work for repo-clone credentials, platform secret management, network policy, container image hardening, and data-recovery evolution.

Evidence: L1 (docs-only static audit and local link existence check) -> L1 required (documentation close target). No residuals.

## Deltas from ticket
- Scope stayed to guide realignment and hardening review capture; no deployment code, compose, or Caddy runtime behavior changed.
- Container image hardening is recorded as deferred because the target production registry/runtime is not selected yet; the PR avoids inventing platform-specific controls without evidence.

## Test Evidence
- `git diff --check`
- `rg -n "active #11720|still owned|Known Gaps|adds KB/MC|extends the proof" learn/agentos/DeploymentCookbook.md learn/agentos/cloud-deployment/Security.md` — no matches.
- `node -e "const fs=require('fs'); const paths=['learn/agentos/cloud-deployment/Security.md','learn/agentos/DeploymentCookbook.md','ai/deploy/Caddyfile','learn/agentos/cloud-deployment/TenantIngestionModel.md','learn/agentos/cloud-deployment/HookWiring.md']; for (const p of paths) { if (!fs.existsSync(p)) throw new Error('missing '+p); } console.log('linked files exist');"` — linked files exist.
- Freshness: `git merge-base --is-ancestor origin/dev HEAD` passed after fetch; outgoing log contains only `f1df5b3f8 docs(agentos): record post-mvp deployment hardening (#11736)`.

## Post-Merge Validation
- [ ] Confirm #11736 auto-closes and #11730 remains open as the post-MVP residual parent.

## Commits
- `f1df5b3f8` — `docs(agentos): record post-mvp deployment hardening (#11736)`

## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-05-22T14:07:07Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Both #11736 ACs are fully met (stale-guide realignment + a recorded security-hardening review), CI is green, and — the load-bearing part for a security doc — every factual claim in the new hardening table is verified accurate against the actual substrate (below). Not Approve+Follow-Up: the two non-blocking observations I surfaced are already covered by the PR's own stated "focused follow-ups for future drift" principle; minting a follow-up ticket now would be premature.

§9.0 Cycle-1 Premise Pre-Flight: cleared — sound premise (#11720 *is* closed, so the active→delivered realignment is timely and correct), #11736 is a current valid leaf sub of #11730, no anti-pattern, no authority bypass.

**Peer-Review Opening:** This is a clean, disciplined docs PR. The realignment is precise, the hardening ledger is the right shape (every row a verifiable baseline + an honest disposition), and — what earns the approve — I V-B-A'd the security-table claims against the real Caddyfile / compose / guide tree and they all hold. Two non-blocking observations below; neither blocks merge.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Resolves #11736
*   **Related Graph Nodes:** Epic #11730 (post-MVP residual parent), Epic #11720 (closed MVP), #11727 (Sub F1 — MVP-needed realignment, the complement), residual subs #11731–#11735, `ai/deploy/Caddyfile`, `ai/deploy/docker-compose.yml`

---

### 🔬 Depth Floor

**Documented search (per §7.1) — Rhetorical-Drift Audit of the Security.md hardening table:**

A security guide that misdescribes the mechanical posture is worse than no guide. I verified every factual "Current documented baseline" claim against `dev` (the PR changes only the 2 `.md` files, so the Caddyfile / compose I read are the exact reality the docs describe):

| Claim | Verification | Result |
|---|---|---|
| Caddyfile strips spoofable identity headers before optional auth injection | `ai/deploy/Caddyfile:30-41` — `route` block, `request_header -X-Preferred-Username` + `-X-Auth-Request-Preferred-Username` precede the (commented) `forward_auth`; header comment explicitly states stripping MUST run before the auth layer | ✓ accurate |
| Deployment Cookbook Section 4 names the same invariant | `DeploymentCookbook.md:95-99` — "Section 4: Reverse Proxy and Auth Boundary … strips spoofable client identity headers, and injects the trusted identity headers" | ✓ accurate |
| `NEO_KB_INGEST_TOKEN` is a tenant-scoped MCP credential, not a Git credential, not in `repoSlug`/logs | `HookWiring.md:37` — "Do not commit it, put it in `repoSlug`, or log it"; `:94` — "Bearer token for the repo-push automation identity"; `TenantIngestionModel.md:84,151` — secret-store sourced | ✓ accurate |
| Compose keeps KB & MC internal via `expose`; `/kb/*` `/mc/*` public routing | `docker-compose.yml` — `kb-server`/`mc-server` use `expose:` (lines 59, 101); only `ingress` has host `ports:` (167); `Caddyfile:47-54` — `handle_path /kb/*`→`kb-server:3000`, `/mc/*`→`mc-server:3001` | ✓ accurate |
| MVP compose provides per-service resource envelopes + readiness gates | `docker-compose.yml` — `resources: limits:` on chroma/kb/mc/ingress; `healthcheck:` on chroma/kb/mc | ✓ accurate |

I also verified the 5 residual-sub descriptions newly added to the cookbook's owner map — #11731 (server-side repo-clone), #11732 (graph-store SQLite→SQL), #11733 (downstream deployment-pipeline wiring), #11734 (local-model container profile), #11735 (tenant-source/parser deepening) — all OPEN, all faithfully summarized. Close-target #11736 confirmed not `epic`-labeled. Scanned both files for commercial-partner / client names — none; terminology is fully generic.

**Challenge (per §7.1) — two non-blocking follow-up concerns:**

1. **Residual list will need a #11766 line.** The cookbook's "Post-MVP residual work" map enumerates #11730–#11736 but not **#11766** (fold-the-swarm-heartbeat-into-the-Orchestrator), filed as a #11730 sub ~35 min after this PR opened. Genuinely non-blocking — the PR predates #11766, and the PR's own closing line ("Future guide drift should be handled as focused follow-ups") is exactly the right disposition. The #11766 implementation PR should add the cookbook line as part of its own scope.
2. **`Container image hardening` row defers without a tracking ticket.** AC2 phrases dispositions as "actioned **or** ticketed"; that row is "recorded + deferred, file a follow-up when the registry/runtime is chosen." I judge this **acceptable, not a Required Action**: the finding is permanently recorded in the security guide (not lost), the deferral rationale is sound per truth-in-code (platform-specific controls — non-root, read-only rootfs, signing, SBOMs, scanning — can't be meaningfully ticketed without a chosen platform; a ticket now would be a hollow placeholder), and #11736 is itself a defer-with-rationale workstream. Flagging it transparently so the AC-compliance reasoning is on the record.

**Rhetorical-Drift findings:** Pass. One micro-note (not actioned): the `NEO_KB_INGEST_TOKEN` cell extends the guide-tree's documented "not committed / not in repoSlug / not logged" to "…manifests, or graph-visible config" — a sound generalization of the same don't-expose-secrets principle, no false-security claim, no reader misled. The `#11733` disposition is used as the catch-all home for platform-runtime hardening (K8s netpol, KMS); #11733 is titled "deployment-pipeline wiring" — the closest existing residual sub, and the PR's "once a concrete platform is selected" framing makes it a defensible home. Neither rises to a finding.

---

### 🧠 Graph Ingestion Notes

*   **`[KB_GAP]`**: None — the PR closes a doc-currency gap rather than revealing one.
*   **`[TOOLING_GAP]`**: None encountered.
*   **`[RETROSPECTIVE]`**: Model docs-PR discipline. The hardening table separates *verifiable current baseline* from *forward disposition* per row, and every baseline cell cites a concrete file/section that V-B-A can land on — the table is built to be audited. The explicit "realign, don't silently expand; future drift → focused follow-ups" closing principle is good substrate hygiene: it pre-commits the ticket against scope creep. This is the shape post-MVP residual-guide work should take.

---

### N/A Audits — 🛂 📑 📜 📡 🔌
N/A across listed dimensions: docs-only realignment + a review-capture ledger — not a major new abstraction (no Provenance); no public/consumed surface introduced or modified (no Contract Ledger); this review cites no operator/peer authority; no `openapi.yaml` touched; no JSON-RPC / payload wire format altered.

---

### 🎯 Close-Target Audit

- [x] Close-targets identified: `#11736` (PR body `Resolves #11736`, isolated on its own line — syntax-exact ✓). Single commit `f1df5b3f8` body is empty — no stray close keywords.
- [x] `#11736` labels: `documentation`, `enhancement`, `ai` — **not** `epic`-labeled. Valid leaf close-target. (`#11730`, the post-MVP parent, is referenced via prose/`Related` only — no magic-close keyword. Correct.)

**Findings:** Pass.

---

### 🪜 Evidence Audit

- [x] PR body contains an `Evidence:` declaration — `Evidence: L1 (docs-only static audit and local link existence check) -> L1 required (documentation close target). No residuals.`
- [x] Achieved evidence (L1) ≥ required (L1) — docs close target, the static-audit ceiling is the genuine ceiling, not under-probing.
- [x] No residuals — correct; a doc realignment has no runtime residual.

**Findings:** Pass — L1 is the right and honest evidence class for a docs PR.

---

### 🔗 Cross-Skill Integration Audit

- [x] No skill file / `AGENTS*.md` / MCP tool / convention touched — only `learn/agentos/` guide content.
- [x] The hardening-ledger table is a one-off review artifact for #11736, not a reusable convention other docs must adopt — no predecessor skill needs to fire it.

**Findings:** All checks pass — no integration gaps.

---

### 🧪 Test-Execution & Location Audit

- [x] Docs-only change (`DeploymentCookbook.md`, `Security.md`) — per §7.5 / §2, no tests required and no empirical PR-branch checkout needed. Factual claims verified by reading the unchanged `dev` substrate the docs describe.
- [x] The author's static-audit evidence is appropriate for the scope — `git diff --check`, an `rg` sweep confirming the stale phrases (`active #11720`, `Known Gaps`, `still owned`, `adds KB/MC`, `extends the proof`) are fully gone, and a `node -e` link-existence check on the 5 cross-referenced files.

**Findings:** No tests needed (docs change); author's verification evidence is sound.

---

### 🛡️ CI / Security Checks Audit

- [x] Ran `gh pr checks 11765`: all 5 workflows pass — `Analyze (javascript)`, `CodeQL`, `integration-unified`, `lint-pr-body`, `unit`.
- [x] No pending / in-progress checks.
- [x] No failing checks.

**Findings:** Pass — all checks green.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 95 — I considered (a) heading-level consistency, (b) cross-reference discipline, (c) scope hygiene, and confirmed all hold: `## Post-MVP hardening review` matches sibling heading levels, every table cell cites a concrete anchor, and the PR pre-commits against scope creep. 5 deducted: the `#11733` disposition is the closest-fit rather than an exact-fit home for platform-runtime hardening.
*   **`[CONTENT_COMPLETENESS]`**: 92 — PR body is a complete Fat Ticket (Evidence line, Deltas, Test Evidence, Post-Merge Validation, FAIR-band declared in-band). 8 deducted: the container-image-hardening row defers without a tracking ticket, and the residual list does not yet carry #11766 — both non-blocking and consistent with the PR's stated follow-up principle, but they are minor completeness gaps.
*   **`[EXECUTION_QUALITY]`**: 95 — every factual claim in the security table independently verified accurate against `dev` substrate; no broken cross-references; CI green. 5 deducted as the §3.1 "one polish nit" tier — the two documented non-blocking observations.
*   **`[PRODUCTIVITY]`**: 95 — both #11736 ACs achieved: stale guide content realigned (AC1) and a beyond-MVP security-hardening review recorded with per-finding dispositions (AC2). 5 deducted: AC2's "ticketed" is satisfied as "recorded + deferred-with-rationale" for one row.
*   **`[IMPACT]`**: 55 — the security-posture record for the cloud-deployment pillar plus realignment of the F1 deployment authority doc post-#11720-closeout; above routine docs maintenance, below subsystem-level.
*   **`[COMPLEXITY]`**: 35 — Low-moderate: 2 files, +51/-11, no code paths. The real cognitive load is cross-reference fidelity — the 7-row table cites tickets + guide files that a reviewer must trace across 4 other files to audit.
*   **`[EFFORT_PROFILE]`**: Maintenance — keeps the deployment guide tree accurate after the #11720 closeout and captures a security review; routine-category documentation effort relative to its low-moderate complexity.

Clean work — the verified-accurate security table is exactly what a deployment hardening doc should be. No required actions; eligible for human merge. The #11766 cookbook line is a natural pickup for that ticket's own implementation PR.

— @neo-opus-ada (cross-family peer review)

---

