v0.5.0 I3 slice 6b: documentation and completion record

[michaelegner]

v0.5.0 I3 slice 6b — documentation and completion record.

Per docs/specifications/0.5.0/i3-runtime-identity-reconciliation.md §23, this is I3's final PR:
the §24 documentation updates and the §25 completion record. PR 6a (the qualification half - §21
matrix closure, §22 frozen fixture) is already merged as PR #224 (dbf066b), which this PR's
completion record cites as its pinned candidate revision.

Retained Plan

(Same governing plan session as PR #224 — see that PR's own "Retained Plan" section for the full
slice-6 plan and PR-6a/6b split rationale. Reproduced here is exactly the "PR 6b" portion of that
plan, from /home/michael/.claude/plans/plan-for-slice-6-precious-valley.md.)

PR 6b — Documentation and completion record

§24 documentation updates (only the docs with a real, confirmed gap)

• docs/graph-model.md (## DEPLOYED_AS (v0.5.0 I3) section, ~line 41): add the missing
  workload_kind field to the WorkloadRef field list (currently only lists id, type, namespace, name); add the "namespace is identity context, not a locality qualification" disclaimer (already
  present in the code's own docstring, contracts.py:248-250, but absent from this doc); add a
  precedence-is-a-tiebreak-not-conflict-resolution sentence to the conflict paragraph.
• docs/opentelemetry.md (after ## Bounded runtime identity observations (I3), ~line 70): new
  subsection documenting §9.7's observation-context/temporal-compatibility rule — the last_seen/
  capturedAt inclusive-window checks and the DEPLOYMENT_ENVIRONMENT_MISMATCH/
  DEPLOYMENT_TEMPORAL_MISMATCH outcomes — currently entirely undocumented despite this being the
  rule's natural home; add a one-line note that k8s.namespace.name/k8s.cluster.uid consistency
  attributes are correlation inputs only, never a locality claim.
• docs/ingestion.md (new subsection alongside "Kubernetes adapter", ~line 50): document the Path
  B mapping-artifact format (app.sources.service_workload_mapping's YAML shape — apiVersion,
  kind, metadata.id/revision, mappings[].mappingId/serviceId/kubernetesSourceId/clusterUid/ workload{apiGroup,kind,namespace,name}), supported workload kinds, and the unknown-field/no-
  templating/no-remote-ref rejection rules from spec §8.1 — this has no documentation home anywhere
  in the repo today (confirmed absent from docs/configuration.md too).
• docs/evidence.md: one note that Path C evidence reachability is itself gated by observation-
  context/temporal compatibility (§9.7), tying into the doc's existing reachability discussion.
• docs/mcp.md: expand the get_service_dependencies row/description (~line 44) with the
  DeploymentClaim/DeploymentResolution/WorkloadRef shapes actually returned, the outcome
  vocabulary (CONFLICT/AMBIGUOUS/UNRESOLVED), and an explicit sentence that I3 added zero new
  MCP tools (the "exactly 3 tools" fact is already documented generally; the "why still 3 for this new
  capability" reasoning is not).
• docs/architecture.md: extend the existing API-surface table row for
  app/api/architecture_intelligence.py with one sentence naming DEPLOYED_AS/WorkloadRef/
  reconciliation and pointing to graph-model.md/mcp.md — currently this doc has zero I3 mentions
  at all.
• docs/canonical-model.md: no change — already adequately covers what's in its scope (entity/id
  shapes), correctly defers the rest.
• ROADMAP.md: no change — confirmed the delivered slice 5a/5b split and direct-envelope
  retirement match what the v0.5.0 roadmap entry already states; §24's own trigger ("only if
  implementation changes the already-planned I3 scope") doesn't apply.

I3 completion record

New file docs/specifications/0.5.0/i3-completion-record.md, following
docs/specifications/0.5.0/i2-completion-record.md's established structure exactly (confirmed this
is a genuine two-increment repo convention, not a one-off, via i1-completion-record.md's matching
shape):

• Status line: COMPLETE, with I3's own §25 closing sentence ("I3 completion is not release
  qualification. I5 and I6 remain required") reproduced verbatim.
• Run identity table: PR v0.5.0 I3: runtime identity reconciliation specification #210 (spec, Draft 0.3) → v0.5.0 I3 slice 1: contract and public schema foundation #212 (slice 1) → v0.5.0 I3 slice 2: OTel runtime identity evidence #213 (slice 2) → v0.5.0 I3 slice 3: explicit and configured deployment identity paths #215 (slice 3)
  → docs(v0.5): consolidate public Architecture Knowledge adapters #218 (spec amendment, Draft 0.3→0.4) → v0.5.0 I3 slice 4: observed path (Path C) #220 (slice 4) → v0.5.0 I3 slice 5a: public adapter consolidation and REST parity #221 (slice 5a) → v0.5.0 I3 slice 5b: deployment public exposure #222 (slice 5b) → v0.5.0 I3 slice 6a: deterministic qualification (§21 matrix closure, §22 fixture) #224
  (slice 6a) → this PR (slice 6b), with each row's real merge SHA.
• Fixture identities table: the existing bespoke per-test fixtures plus the §22 frozen
  tests/fixtures/deployment/i3-cross-source/ fixture, with its content digests.
• Immutable qualification identity table: candidate revision = PR v0.5.0 I3 slice 6a: deterministic qualification (§21 matrix closure, §22 fixture) #224's merge SHA (dbf066b,
  cited only after it merged and was independently CI-verified, avoiding the self-reference problem
  I2's own record disclosed); governing spec blob SHA; contracts.py/deployment_reconciliation.py/
  deployment_projection.py/deployment_repository.py/service_workload_mapping.py blob SHAs;
  rule/schema version constants; fixture digests; CI run links (verified via the GitHub API against
  the exact SHA).
• Regression suite table: final local ruff check/format --check/pytest tests/unit/
  pytest tests/integration counts at the pinned candidate revision, run fresh.
• §21/§25 Definition of Done — evidence by area table: one row per §21.1-§21.7 category and per
  §25 bullet, citing the exact test file/function proving it.
• Limitations and unsupported constructs: the relevant §28 stop conditions as explicit
  disclosures, plus the Path B rule-id-asymmetry disclosure carried over from PR v0.5.0 I3 slice 6a: deterministic qualification (§21 matrix closure, §22 fixture) #224.
• Handoff to I4/I5: reproduces spec §26.
• Corrected I3 exit statement: COMPLETE, at the pinned candidate revision, summarizing all six
  slices and the final regression counts — explicitly not release qualification, I5/I6 still required.

Reconciliation

Completed As Planned

Both the §24 documentation updates and the I3 completion record were delivered exactly as scoped in
the retained plan, with no deviation in scope or approach. All six flagged docs were updated with the
specific content the plan named; docs/canonical-model.md and ROADMAP.md were re-confirmed to need
no change immediately before finalizing (no drift since the original research pass). The completion
record follows i2-completion-record.md's structure section-for-section, citing PR #224's merge
commit dbf066b593b8b19f18596a0be27dc2724885cdbc as the pinned candidate revision, verified against
the exact SHA via the GitHub API (not gh pr checks), per this repo's own established convention for
avoiding ambient-HEAD re-derivation.

Deviations & Justification

None. This was a self-contained documentation/record task with no code touched, so no implementation
surprises arose. The completion record's "immutable qualification identity" table additionally pins
blob SHAs for deployment_repository.py and service_workload_mapping.py (not explicitly named in
the plan's own text) since the record's own format — mirroring I2's — calls for every load-bearing
module cited elsewhere in the record to have a pinned blob SHA, not just the three named in the plan.

Specification Questions Discovered

None. No genuinely unstated semantic decision arose — this PR restates and documents already-frozen
behavior, it doesn't interpret anything new.

Deferred Work

None remaining for I3 itself. I4, I5, and I6 are separate, not-yet-started increments/gates per the
parent specification and ROADMAP.md.

Test/Qualification Evidence

At this PR's head (documentation-only + one new file, no production or test code touched):

• uv run ruff format . — 340 files left unchanged (clean)
• uv run ruff check . — all checks passed
• uv run pytest tests/unit — 1815 passed (unchanged from PR v0.5.0 I3 slice 6a: deterministic qualification (§21 matrix closure, §22 fixture) #224's own count)
• uv run pytest tests/integration — 405 passed (unchanged from PR v0.5.0 I3 slice 6a: deterministic qualification (§21 matrix closure, §22 fixture) #224's own count)

Remaining Limitations

Reproduced from the completion record's own "Limitations and unsupported constructs" section: no live
Kubernetes client, no fuzzy/name-similarity matching, no fourth MCP tool, no locality semantics, no
container/sidecar canonical entities, multi-Service-per-Workload not modeled, Path B's disclosed
rule-id asymmetry, and the §22 fixture's contradictory scenarios covering Path A-vs-B/Path A-vs-C
specifically (the full pairwise matrix is covered separately by hand-built §21.4 unit tests). I5 still
owns two-system release qualification; this record's own qualification bar is I3's narrower,
increment-scoped one.

With this PR, I3 is complete per its own §25 Definition of Done — not release qualification; I5 and
I6 remain required per the parent specification.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BEyW1QKTxJy1K3eyPB93zJ

[michaelegner]

Reviewed head b926b3a. CI and CodeQL are green. I see one completion-record blocker plus two small factual cleanups:

• The exit statement says that at pinned candidate dbf066b “all six” slices are present, including the 6b documentation/completion-record split. But dbf066b is PR v0.5.0 I3 slice 6a: deterministic qualification (§21 matrix closure, §22 fixture) #224 and explicitly predates this 6b PR. Keep it as the qualified implementation candidate, but distinguish that from I3 becoming COMPLETE only with this 6b record/docs; don’t claim 6b is present at the pinned candidate revision.
• The “eight sequential PRs … plus one spec amendment” count is stale now that slice 6 is also split: the table has nine delivery PRs including this one, plus the amendment.
• “Both fixture families use … import_kubernetes_source throughout” overstates the hand-built unit fixtures, which are in-memory/pure-function fixtures rather than persisted through the real importer.

I found no other blocking issues in the documentation changes.

[Copilot]

Copilot review overview

🟡 Changes recommended

The new completion record contains a few factual/formatting inaccuracies (PR count/splits, missing PR identifier, and a broken constant name due to line-wrapped inline code) that should be corrected before merging.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 5

Open (5)

• WorkloadRef field order differs from contract · New
• WorkloadRef docs out of sync with contract · New
• Run summary miscounts slice 6 split · New
• Slice 6b PR number left as placeholder · New
• Broken constant name formatting in doc · New

What changed in this PR

This PR completes v0.5.0 I3 slice 6b by updating repository documentation to reflect the finalized DEPLOYED_AS / runtime-identity reconciliation behavior and by adding the I3 increment completion record under docs/specifications/0.5.0/.

Changes:

• Add docs/specifications/0.5.0/i3-completion-record.md capturing I3’s pinned candidate revision, qualification evidence, fixture digests, and DoD evidence mapping.
• Document previously-undocumented I3 semantics across core reference docs (Path B mapping artifact format, Path C observation-context/temporal compatibility, MCP deployment-claim projection, and WorkloadRef shape notes).
• Add cross-doc linkages from the architecture overview to the detailed I3 contract docs (graph-model.md, mcp.md).

File	Description
docs/​specifications/​0.5.0/​i3-completion-record.md	New I3 completion record: run identity, pinned artifacts, regression evidence, DoD mapping, and limitations/handoff.
docs/​opentelemetry.md	Adds the I3 observation-context/temporal compatibility rule documentation for Path C.
docs/​mcp.md	Documents how I3 deployment claims/resolutions appear via existing MCP tools (no new tools added).
docs/​ingestion.md	Documents the Path B Service↔Workload mapping artifact YAML shape and validation rules.
docs/​graph-model.md	Updates DEPLOYED_AS/WorkloadRef documentation (adds workload_kind, clarifies namespace semantics, and precedence vs conflict).
docs/​evidence.md	Notes that Path C evidence reachability is gated by observation-context compatibility, including for convenience evidence lookups.
docs/​architecture.md	Extends API surface documentation to point readers to the I3 deployment reconciliation docs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[michaelegner]

Review of head b926b3a

Previous blockers: none (first review round).

Fixes for head f574d1e:

1. Copilot + user's own review: docs/graph-model.md and docs/mcp.md both listed WorkloadRef's fields as (id, type, workload_kind, name, namespace), but the real contract (app/architecture_intelligence/contracts.py) declares name before workload_kind. Fixed both to (id, type, name, workload_kind, namespace).
2. Copilot: DEPLOYMENT_RECONCILIATION_RULE_ID's inline code span was split across a markdown source line break, rendering the constant name with a literal space in it. Fixed to keep the whole span on one line.
3. Copilot + user's own review: the completion record's "Run identity" intro sentence said "eight sequential PRs ... one of which split into 5a/5b" - stale now that slice 6 also split into 6a/6b. Fixed to "nine ... two of which split". The slice 6b table row's PR column also still showed a placeholder ("—") instead of this PR's real number - fixed to #225.
4. User's own review (blocking): the exit statement said "at the pinned candidate revision (dbf066b), all six slices are present" including 6b's own split - but dbf066b is PR v0.5.0 I3 slice 6a: deterministic qualification (§21 matrix closure, §22 fixture) #224's merge and predates this PR entirely. Rewrote to clearly separate the pinned implementation candidate (dbf066b, through slice 6a - all code/test changes) from I3's own completion, which additionally requires this PR's documentation and the record itself, with zero further code changes on top of that candidate.
5. User's own review: "both fixture families use ... import_kubernetes_source ... throughout" overstated the hand-built unit-level fixtures, which are pure in-memory PathResolutionResult/CurrentKubernetesWorkload constructions that never touch Neo4j. Fixed to distinguish them from the integration-level fixtures that do go through the real importer.

Required evidence: uv run pytest tests/unit -> 1815 passed (unchanged, doc-only PR); uv run pytest tests/integration -> 405 passed (unchanged); ruff check/format --check clean.

Exit condition: approve once these five fixes are confirmed to resolve the recorded blockers, unless the fixes themselves introduce a material regression.

[michaelegner]

Re-reviewed head f574d1e. The previous completion-record blocker and the Copilot findings are resolved, and CI/CodeQL are green. I found one remaining factual cleanup in the new fixture-provenance wording: it now says no integration test writes Kubernetes or Service facts via raw Cypher, but the deployment integration suites deliberately create OBSERVED_ONLY Service stubs with MERGE (s:Service ...). Please narrow that claim to declared Services/Kubernetes facts imported through the real paths. Minor formatting nit: the CurrentKubernetesWorkload code span is split across a source newline and renders as CurrentKubernetes Workload. No other blocking issues found.