Reconcile 0.4.6 lifecycle and planning truth

AGENTS.md

@@ -14,6 +14,7 @@ Use this file as the short repository map and source-of-truth index for Open Cod
 
 - `AGENTS.md` - short repository map and durable pointers.
 - `PLANS.md` - active, blocked, or recently completed execution registry.
+- `docs/engineering/execution_history/README.md` - release-tag index for archived completed plans and their audit evidence.
 - `docs/engineering/toolkit_strategy.md` - durable product and architecture strategy.
 - `ROADMAP.md` - outcome-oriented milestones and dependencies.
 - `docs/engineering/project_principles.md` - durable cross-cutting rules and ownership boundaries.
@@ -52,9 +53,10 @@ Use this file as the short repository map and source-of-truth index for Open Cod
 - Add a Towncrier fragment for every user-visible change during the 0.x line.
 - At plan start, classify every user-visible change as `no-release`, `release-required`, or `release-deferred`; record the classification and target stable version in `PLANS.md`. Removed or incompatibly changed CLI, environment, schema, reviewer-command, or documented integration behavior is always `release-required`.
 - For `release-required` work, keep the plan active across feature PR, merge, TestPyPI development verification, release PR, stable TestPyPI/PyPI publication, tag/immutable GitHub Release, provenance/hash checks, and supported-Python smoke installs. A feature merge or `.devN` build is an intermediate checkpoint, not closure.
+- A release PR may prepare every repository-side release input, but it cannot also be the final lifecycle closure PR because external artifacts do not exist before it merges. After stable publication and independent readback, use one small documentation-only `no-release` closure PR to reconcile repository truth; it must not publish another package.
 - Publication can stop before a stable release only when the user explicitly defers it. Record the deferral reason, target version, completed checkpoints, and exact resume action in `PLANS.md`; do not mark the release objective completed.
 - Before handoff, reconcile the promised outcome against external state rather than local files alone: read PyPI/TestPyPI versions, GitHub tag/Release, Actions conclusions, and artifact attestations when those systems are in scope.
 - Before staging or committing, update `PLANS.md` and promoted backlog items to post-commit truth.
-- When a milestone or release closes, reconcile every status-bearing representation in the same closure change: `PLANS.md`, roadmap table and diagram, and backlog. Remove only work proven complete by the merged implementation and validation evidence, preserve unfinished work even when it was previously grouped into the closing plan, and ensure diagram labels and status colors agree.
+- When a milestone or release closes, inspect the current implementation before preserving backlog scope, then reconcile every status-bearing representation in the same closure change: `PLANS.md`, roadmap table and diagram, backlog, and narrative current-state documentation. Remove only work proven complete by the merged implementation and validation evidence, preserve unfinished work even when it was previously grouped into the closing plan, and ensure diagram labels and status colors agree.
 - Run `git diff --check` and the validation appropriate to the changed subsystem.
-- Compact or archive completed plan detail only after validation and handoff are recorded.
+- Compact or archive completed plan detail only after validation and handoff are recorded. Keep the most recent externally reconciled release cycle in `PLANS.md`; during the next post-release closure, move the previously retained cycle to `docs/engineering/execution_history/releases.md`, update its stable-tag entry in the archive index, verify the anchors, and preserve the original receipts.

README.md

@@ -31,9 +31,9 @@ Suppression uses both the GitLab diff position and a stable finding fingerprint,
 
 Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the evidence collector supplies target-ref decisions to OCR and never lets a source change self-authorize its own review. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
 
-## Project development
+## Project architecture
 
-The project is evolving from bounded background generation toward a shared Repository Evidence Engine: one deterministic evidence model will support both a compact OCR bootstrap and a built-in read-only MCP server. Development is ordered by outcomes and dependencies rather than speculative dates.
+The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed evidence through the mandatory built-in read-only MCP server. Reviewed external stdio or native HTTPS MCP servers compose alongside it without replacing the built-in evidence boundary.
 
 - [Toolkit strategy](docs/engineering/toolkit_strategy.md) - durable product boundaries, architecture, invariants, and non-goals.
 - [Roadmap](ROADMAP.md) - milestone status, dependencies, outcomes, and completion signals.
@@ -57,7 +57,7 @@ See the fully synthetic [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gi
 
 ## Configuration and safety
 
-Configuration is environment-only in v0.1. The [configuration reference](docs/configuration.md) documents supported `OCR_*`, `CI_*`, `GITLAB_*`, and MCP inputs. Posting requires `GITLAB_API_TOKEN`; job tokens and legacy aliases are deliberately unsupported.
+Configuration is environment-driven. The [configuration reference](docs/configuration.md) documents supported `OCR_*`, `CI_*`, `GITLAB_*`, and MCP inputs. Posting requires `GITLAB_API_TOKEN`; job tokens and legacy aliases are deliberately unsupported.
 
 Repository content, OCR output, and provider responses are untrusted inputs. The toolkit applies bounded reads and writes, secret redaction, Unicode normalization, Markdown/quick-action neutralization, fingerprinted comments, ownership boundaries for human replies, and rollback controls. Review the [security and trust model](docs/security.md) before enabling write access.
 

ROADMAP.md

@@ -9,9 +9,9 @@ The diagram uses the same statuses as colors: green for established, blue for ne
 flowchart LR
     M0["M0 Foundation<br/>established"] --> M1["M1 Evidence architecture<br/>established"]
     M0 --> M3["M3 External MCP hardening<br/>next / planned"]
-    M1 --> M2["M2 Ecosystem and framework coverage<br/>planned"]
+    M1 --> M2["M2 Remaining evidence and frameworks<br/>planned"]
     M1 --> M4["M4 Policy and project guidance<br/>planned"]
-    M1 --> M5["M5 Profiles and quality measurement<br/>planned"]
+    M1 --> M5["M5 Measurement audit and profiles<br/>planned"]
     M5 --> M6["M6 Later and conditional work<br/>conditional"]
 
     classDef established fill:#1f883d,stroke:#116329,color:#ffffff
@@ -29,18 +29,18 @@ flowchart LR
 | --- | --- | --- | --- | --- |
 | M0 Foundation | Established | Durable planning sources, high-signal repository security checks, and repeatable OCR compatibility policy. | Existing CI and the current recommended/tested OCR baseline. | Strategy, roadmap, and backlog agree; Bandit is a bounded repository gate; every unseen stable OCR release receives checksum-verified machine evidence with adjacent comparison identity; only a wholly safe contiguous patch chain may receive one protected bot-ready update patch, while material or ambiguous changes require human qualification and no path writes directly to `main`. |
 | M1 Evidence architecture | Established | One bounded evidence model supplies a compact bootstrap and built-in read-only MCP. | Machine-readable OCR capabilities and current context contracts. | Stable v0.4.0 publishes the model, immutable snapshots, typed deltas, bounded private storage, compact bootstrap, built-in MCP, semantic parity/removal, verified real-OCR use, reporting outcomes, and security hardening; TestPyPI/PyPI artifacts, provenance, hashes, annotated tag, immutable GitHub Release, and supported-Python smoke installs are independently verified. |
-| M2 Ecosystem and framework coverage | Planned | Resolve dependency, runtime, container, and framework state for demonstrated repository stacks. | Stable evidence model and snapshot/delta semantics. | Prioritized formats and framework plugins have deterministic fixtures, bounds, provenance, and source/target deltas. |
-| M3 External MCP hardening | Next / planned | Secure and document current read-only external MCP first, then compose it with built-in evidence tools. | Existing external MCP for threat modeling and current examples; M1 built-in MCP only for late composition. | Threat model precedes reference detection and provider examples; current generic, proxy, YouTrack, and Confluence patterns are validated; later combined examples enforce reserved namespaces and trust separation. |
+| M2 Ecosystem and framework coverage | Planned | Close demonstrated evidence resolution, precedence, completeness, or component-scope gaps and select framework plugins from actual use. | Established evidence model and snapshot/delta semantics; item-specific gaps only. | Remaining formats and selected framework plugins have deterministic fixtures, bounds, provenance, completeness, and source/target deltas without restating established collectors. |
+| M3 External MCP hardening | Next / planned | Threat-model external references and validate provider-specific read-only examples on the established built-in/external MCP composition boundary. | Existing external MCP and built-in composition for current generic operation; BL-011 before reference detection or provider examples. | Threat model precedes reference detection and provider examples; synthetic YouTrack, Confluence, or documentation examples preserve narrow read-only tools, reserved namespaces, and trust separation. Managed OAuth remains conditional on a named provider requirement. |
 | M4 Policy and project guidance | Planned | Supply relevant target-branch decisions and guidance without allowing self-whitelisting. | Evidence scoping and target/source snapshots. | Semi-structured decisions remain backward compatible; guidance paths and hints are bounded, target-derived, and non-authoritative. |
-| M5 Profiles and quality measurement | Planned | Offer explicit run-level review profiles, reuse OCR token/cost/budget telemetry, and measure only missing GitLab lifecycle, evidence/MCP, posting, and review-value signals. | OCR 1.8.7+ per-run override/result-identity capabilities and the atomic compact-bootstrap/evidence-MCP contract; toolkit metrics additionally require stable discussion fingerprints and demonstrated coverage gaps. | Profiles are deterministic and documented; a gap audit reuses OCR telemetry and result identity and either proves bounded result-derived reporting sufficient or justifies only the missing provider-neutral toolkit signals without sensitive, high-cardinality, or duplicate data. |
+| M5 Profiles and quality measurement | Planned | Audit current OCR telemetry and result-derived review signals before adding profiles or any toolkit metrics. | Established result, discussion, coverage, posting, and MCP-use receipts; the owner-approved matrix is required only for profile implementation. | The audit either proves current bounded reporting sufficient or isolates a separately scoped provider-neutral gap; any later profiles are deterministic and documented without sensitive, high-cardinality, or duplicate data. |
 | M6 Later and conditional work | Conditional | Activate routing, more ecosystems, fuzzing, configuration, forge adapters, or governance work only from demonstrated need. | Milestone-specific activation signals and stable preceding contracts. | Each item meets its own trigger and ships as a coherent validated slice without weakening core invariants. |
 
 ## Ordering notes
 
 - OCR compatibility and the established common evidence model now converge at compact-bootstrap/evidence-MCP integration.
-- M3 threat modeling and documentation of current external MCP can proceed from the established built-in composition boundary.
+- M3 threat modeling can proceed from the established generic composition boundary; provider examples wait for BL-011, while managed OAuth does not block static-header or stdio operation.
 - M2 and M4 can proceed from the stable evidence contracts they consume.
-- M5 profiles do not wait for every ecosystem, external MCP, or policy item; measurement begins after profile and lifecycle identifiers are stable.
+- The M5 measurement-gap audit can begin from current lifecycle and result receipts; BL-016 is required only for later named-profile comparisons.
 - Versioned documentation remains a separate MCP integration: the toolkit supplies package/version evidence but does not store documentation.
 - Additional code-hosting adapters are not ecosystem collectors. They remain conditional because the near-term product is GitLab-first.
 - Calendar commitments belong in release or project management systems when work is funded; they are intentionally absent here.

changelog.d/69.doc.md

@@ -0,0 +1 @@
+Document the established evidence and MCP architecture, reconcile the completed 0.4.6 lifecycle and remaining backlog with current code, and index archived execution history by stable release tag.

docs/codex/AGENT_EXECUTION_PITFALLS.md

@@ -26,6 +26,36 @@ This note records recurring execution mistake patterns discovered during real wo
 - Do not commit completed work while the active plan still says `planned` or `in_progress`.
 - Do not close a milestone by updating only its execution plan. Reconcile roadmap labels, diagram status colors, and the future backlog in the same closure change. Remove an entry only after its own deliverables and validation are proven complete; preserve unfinished adjacent work even if an earlier feature plan accidentally marked it complete.
 
+## Preserving the original backlog after implementation has moved on
+
+**Failure mode:** A future item keeps broad deliverables that current code and tests already satisfy, so completed behavior is planned again under its historical ID.
+
+**Correction:** Build a current capability matrix first. Retain only demonstrable gaps, mark deliberate non-goals explicitly, and preserve an old identifier only when its remaining scope is still coherent.
+
+## Letting conditional work block unconditional work
+
+**Failure mode:** A provider-specific or demand-triggered feature becomes a hard dependency for a generic capability that already works safely without it.
+
+**Correction:** Separate implementation, safety, and rollout edges. An unmet conditional trigger may block only the behavior that consumes it; it cannot block static-header, stdio, documentation, or other unconditional paths.
+
+## Calling the release PR the lifecycle closure
+
+**Failure mode:** Repository preparation and external publication are called complete in the same PR even though registry artifacts, provenance, tag, and immutable Release exist only after merge.
+
+**Correction:** Keep the release-required plan active through external readback, then use a small no-release closure PR to record receipts and reconcile repository truth without publishing again.
+
+## Updating status tables but not current-state prose
+
+**Failure mode:** The roadmap says a milestone is established while strategy and README still describe its implementation as a target or migration in progress.
+
+**Correction:** Search narrative documentation for the superseded architecture and update it in the same milestone closure. Classify migration evidence as historical rather than deleting it blindly.
+
+## Keeping completed plans indefinitely in the active registry
+
+**Failure mode:** `PLANS.md` becomes the permanent release database, obscuring active work and making resume state expensive to recover.
+
+**Correction:** Keep only active, blocked, recently completed work and the latest reconciled release. Move older completed cycles intact to the release-tag archive, update its index, validate anchors, and retain every decision and receipt needed to reconstruct context.
+
 ## Source And Privacy Boundaries
 
 - Inventory tracked source explicitly and avoid broad copy commands that could include ignored or untracked files.