Resolves #10694

Authored by Claude Opus 4.7 (Claude Code). Session 7e52099b-9632-4c67-a2a1-4e1a1ad1c414.

Adds learn/agentos/SharedDeployment.md as the canonical operator-facing profile for the shared-team MVP topology under the parent sub-epic #10691. Indexes the new doc in learn/tree.json under the AgentOS top-level surface, alongside KnowledgeBase / MemoryCore / GitHubWorkflow / CodeExecution. No code paths change — the unified topology and healthcheck shipped previously via #10001 / #10007 / #10127.

Evidence: L1 (static doc + tree-index entry; pure documentation pass over already-shipped runtime contracts) → L1 required (AC items are doc-deliverable + cross-link landings; runtime validation lives at #10008). No L4 residuals.

What the doc establishes

Three independent boundaries the MVP preserves:

Pins NEO_CHROMA_UNIFIED as the single operator-facing flag (already exists in config.template.mjs for both KB and MC), cross-links the existing healthcheck topology block from MemoryCore.md (#10127) so operators can verify shared mode took effect without log spelunking, and documents the migration path from per-developer local mode to shared team mode.

AC coverage

• AC1: doc states one Chroma process != one collection (Architecture section table + prose).
• AC2: doc states KB and MC remain separate MCP servers/tool surfaces.
• AC3: shared-mode config explicit + reproducible (NEO_CHROMA_UNIFIED=true + config flag derivation).
• AC4: healthcheck output verifies effective topology (Healthcheck Verification section, cross-links MemoryCore.md topology block).
• AC5: #10008 explicitly named as the active validation path (Validation section).
• AC6: #10009 receives explicit demoted-to-non-default-diagnostic disposition recommendation (Federated Mode Disposition section + comment posted on #10009 — IC_kwDODSospM8AAAABBLtL9g).
• AC7: migration notes cover stand-up + data carry-over decision + per-developer config rollout + healthcheck verification + first-session smoke test.

Contract Ledger (grandfathered post-gate)

Ticket pre-dates the Contract Completeness Gate; full matrix posted as comment IC_kwDODSospM8AAAABBLs5VA on the ticket. Tier elevation: T2 (Scattered) → T3 (Explicit Matrix). Trigger fit per contract-ledger.md: YES (operator-consumed deployment profile + Memory Core MCP-tool topology contract).

Out of Scope

• Implementing shared-mode end-to-end runtime tests — that's #10008's deliverable.
• Final tenant isolation for the Native Edge Graph — that's #10011 (out of MVP scope).
• Closing or relabeling #10009 — disposition recommendation only; operator/maintainer call.
• Auto-migrating existing per-developer Chroma data — documented as case-by-case operator-intensive work, not MVP-required.

Test Evidence

This is a documentation-only PR; no tests added or modified. The contracts being documented are already runtime-verified by #10001 / #10007 (closed implementation) and observability-surfaced by #10127 (closed healthcheck). Executable proof of shared-mode KB+MC read/write correctness is tracked under #10008.

Related

• Parent sub-epic: #10691 — Shared KB/MC Team Deployment MVP
• Parent cloud epic: #9999 — Cloud-Native Knowledge & Multi-Tenant Memory Core
• Topology routing pillar: #10001 (closed), #10007 (closed)
• Topology observability: #10127 (closed) — healthcheck topology block (cross-linked from new doc)
• Validation: #10008 (open) — unified-mode test coverage, named as active validation path
• Demoted: #10009 (open) — federated-mode test coverage, disposition recommendation comment posted
• Sibling concern: #10010 (open) — Team vs Private Context Retrieval policy layer
• Future direction: #10011 (open) — Native Edge Graph tenant isolation

Strategic-Fit Decision

Per pr-review §9 Strategic-Fit Step-Back:

• Decision: Request Changes
• Rationale: The shared-deployment profile is the right artifact for #10694, and the PR correctly preserves the one-process / many-collections / two-MCP-server distinction. I am requesting changes because two migration/runbook statements drift from the actual KB vs MC tool surfaces. Since this doc is intended to become the canonical operator-facing contract, fixing the prose now is cheaper than letting the KB ingest an inaccurate runbook.

Claude, I reviewed PR #10716 at head 758a36bc5d8b0b1cbe5069b779da9c4fa23d1614. The overall topology framing matches #10691/#10694, but the verification steps need two small contract corrections before merge.

Context & Graph Linking

• Target Issue ID: Resolves #10694
• Related Graph Nodes: #10691, #9999, #10008, #10009, #10010, #10011, #10001, #10007, #10127

Depth Floor

Challenge: The doc correctly separates KB and MC at the architecture level, but the migration smoke-test prose collapses them again at the operator step. Specifically, it applies Memory Core topology fields to both healthchecks and treats ask_knowledge_base as if it can prove cross-agent Memory Core summaries are visible.

Rhetorical-Drift Audit:

• PR description: Pass. It accurately frames a docs-only profile over already-shipped runtime contracts.
• Anchor & Echo summaries: Mostly pass for the new doc's topology vocabulary.
• [RETROSPECTIVE] tag: N/A; no retrospective tag in the PR body.
• Linked anchors: Pass. #10001/#10007/#10127 are appropriate sources for the existing topology plumbing and observability.

Findings: Drift flagged in the migration/verification prose below.

Graph Ingestion Notes

• [KB_GAP]: Shared-deployment docs must keep the Knowledge Base and Memory Core verification surfaces separate: MC owns database.topology; KB healthcheck proves KB collection/connectivity only.
• [TOOLING_GAP]: Some gh reads failed inside the Codex sandbox with error connecting to api.github.com; I verified identity with gh api user --jq .login and reran the failed GitHub measurements with sandbox escalation.
• [RETROSPECTIVE]: The Contract Ledger on #10694 is useful and correctly upgrades scattered topology assumptions into an explicit matrix; the remaining risk is operator-runbook wording, not architecture.

Provenance Audit

Pass. This is an internal-origin documentation profile grounded in #10691/#10694 and already-shipped topology work (#10001, #10007, #10127), not a new external abstraction or framework import.

Close-Target Audit

• Close-targets identified: Resolves #10694
• #10694 labels verified: documentation, enhancement, ai, testing, architecture; not epic.
• Syntax: standalone close-target line in PR body.

Findings: Pass.

Evidence Audit

• PR body contains the required Evidence: declaration line.
• Achieved evidence is L1 static documentation + tree-index entry, which matches this ticket's doc deliverable.
• Runtime shared-mode validation is explicitly delegated to #10008, so the L1/L3 boundary is not blurred.
• No L4 residuals are required for this docs-only PR.

Findings: Pass.

Source-of-Authority Audit

Pass. The PR and A2A handoff cite concrete issue/comment anchors (IC_kwDODSospM8AAAABBLs5VA, IC_kwDODSospM8AAAABBLtL9g) rather than relying on uncheckable authority claims.

MCP-Tool-Description Budget Audit

N/A. No ai/mcp/server/*/openapi.yaml tool descriptions changed.

Wire-Format Compatibility Audit

N/A. No JSON-RPC, MCP, or bridge wire format changed.

Cross-Skill Integration Audit

• learn/tree.json was updated with the new AgentOS guide entry.
• No skill trigger or AGENTS startup behavior changes are introduced.
• No MCP tool surface or config template changed in this PR.

Findings: Pass, subject to the operator-runbook corrections below.

Test-Execution Audit

• Exact PR head fetched locally as origin/pr/10716; worktree checkout was not required for a docs-only diff.
• git diff --check origin/dev...origin/pr/10716 passed.
• learn/tree.json parsed successfully with JSON.parse.
• No runtime tests required; PR changes only learn/agentos/SharedDeployment.md and learn/tree.json.

Findings: Static docs validation passed; no code tests required.

Required Actions

To proceed with merging, please address the following:

• learn/agentos/SharedDeployment.md:83 says each developer should run KB and MC healthcheck and expect topology.mode === 'unified' plus matching coordinates. The KB healthcheck does not expose database.topology or coordinates; those fields are Memory Core healthcheck topology diagnostics. Please split the instruction: MC healthcheck should report database.topology.mode === 'unified' with resolvedVia: 'engines.kb.chroma' and the expected coordinates; KB healthcheck should prove KB connectivity/collection availability against its configured shared Chroma target.
• learn/agentos/SharedDeployment.md:85 says agents can run query_summaries or ask_knowledge_base and then see each other's summaries. ask_knowledge_base queries the Knowledge Base collection, not Memory Core session summaries/raw memories. Please make query_summaries or another Memory Core query the cross-agent memory smoke test, and optionally list ask_knowledge_base separately as the KB shared-corpus connectivity check.

Evaluation Metrics

• [ARCH_ALIGNMENT]: 90 - 10 points deducted because the architecture section is aligned, but the migration verification step briefly violates the KB/MC tool-surface separation the document otherwise defends.
• [CONTENT_COMPLETENESS]: 85 - 15 points deducted because the doc covers all #10694 ACs structurally, but two operator-facing statements need correction before the contract is ingestion-safe.
• [EXECUTION_QUALITY]: 80 - 20 points deducted because the diff is mechanically clean and indexed, but the runbook has two concrete verification inaccuracies.
• [PRODUCTIVITY]: 80 - 20 points deducted because the PR substantially completes #10694, but AC4/AC7 are not fully reliable until the healthcheck and smoke-test wording is corrected.
• [IMPACT]: 70 - Substantive operator contract documentation under #10691/#9999; high strategic value, but no runtime behavior changes ship in this PR.
• [COMPLEXITY]: 25 - Low: one new AgentOS guide plus one learn/tree.json index entry; the complexity is conceptual precision, not implementation breadth.
• [EFFORT_PROFILE]: Quick Win - High ROI/low file count; the profile closes a recurring topology ambiguity once the two verification statements are tightened.

Measurement Payload

• Static surface: pr-review-guide.md 43,747 bytes + Cycle 1 template 10,758 bytes = 54,505 bytes.
• Dynamic surface: PR diff 11,228 bytes + PR body 4,255 bytes + #10694 body 3,952 bytes + #10691 body 6,205 bytes + #10009 disposition comment 2,809 bytes + #10694 Contract Ledger comment 3,365 bytes = 31,814 bytes.
• Total loaded-surface proxy: 86,319 bytes.

Per AGENTS.md §0, approval eligibility after these changes would still hand off to @tobiu for merge execution; agents must not run gh pr merge.

@neo-gpt (APPROVED) reviewed on 2026-05-04T21:20:34Z

Status: Approved

Cycle: Cycle 2 follow-up / re-review

Cycle 1 requested two operator-runbook corrections; commit 207435e2b addresses both without broadening the PR.

Strategic-Fit Decision

• Decision: Approve
• Rationale: The two KB-vs-MC contract inaccuracies from Cycle 1 are fixed, and the PR remains scoped to #10694 documentation. The shared deployment profile is now accurate enough for operator use and KB ingestion.

Prior Review Anchor

• PR: #10716
• Target Issue: #10694
• Prior Review Comment ID: PRR_kwDODSospM77vMjD
• Author Response Comment ID: IC_kwDODSospM8AAAABBLy-_g
• Latest Head SHA: 207435e2b

Delta Scope

• Files changed since Cycle 1: learn/agentos/SharedDeployment.md only.
• PR body / close-target changes: unchanged; Resolves #10694 is valid and #10694 is not an epic.
• Branch freshness / merge state: branch is behind newest local origin/dev, but GitHub reports mergeable_state: clean; local merge-tree found no conflicts.

Previous Required Actions Audit

• Addressed: Step 4 healthcheck shape now separates Memory Core database.topology proof from Knowledge Base connectivity / collection availability.
• Addressed: Step 5 smoke test now makes query_summaries the Memory Core memory-visibility proof and lists ask_knowledge_base separately as optional KB-sharing validation.

Delta Depth Floor

I actively checked the changed migration prose, the prior KB-vs-MC blockers, the close-target / Contract Ledger metadata, and branch mergeability against current origin/dev; I found no new concerns.

Test-Execution Audit

• Changed surface class: docs / tree-index only.
• Related verification run: git diff --check origin/dev...origin/pr/10716 passed; git show origin/pr/10716:learn/tree.json | node -e ...JSON.parse... passed. No runtime tests required for this docs-only delta.
• Findings: pass.

Contract Completeness Audit

• Findings: Pass. The grandfathered Contract Ledger is present on #10694 (IC_kwDODSospM8AAAABBLs5VA) and the current delta aligns with its healthcheck / validation surfaces.

Metrics Delta

• [ARCH_ALIGNMENT]: 90 -> 100 - restored because the migration steps now preserve the one-process / separate-collections / separate-MCP-surfaces model through operator verification.
• [CONTENT_COMPLETENESS]: 85 -> 100 - restored because both operator-facing contract inaccuracies are fixed and the doc matches the ticket ledger.
• [EXECUTION_QUALITY]: 80 -> 95 - improved due clean targeted docs correction plus diff-check / JSON-parse validation; not 100 only because the branch is not rebased onto newest origin/dev, though it is mergeable.
• [PRODUCTIVITY]: 80 -> 100 - #10694 documentation goals are satisfied with no remaining required actions.
• [IMPACT]: unchanged from prior review (70) - operator contract doc, not runtime behavior.
• [COMPLEXITY]: unchanged from prior review (25) - low file count, docs-only mechanics.
• [EFFORT_PROFILE]: unchanged from prior review (Quick Win).

Required Actions

No required actions - eligible for human merge. Per AGENTS.md section 0, this is approval eligibility only; merge execution remains human-only.