Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 41 additions & 18 deletions PLANS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@

Use this file for active, blocked, or recently completed execution work. Update it before implementation and before handoff or commit. Older completed plans are indexed in [the execution-history archive](docs/engineering/execution_history/README.md).

## Active Plan: M2 ecosystem and framework coverage for 0.5.0
## Recently Completed Plan: M2 ecosystem and framework coverage for 0.5.0

Status: active; release candidate locally validated; release PR and stable external delivery pending
Status: completed; stable 0.5.0 delivery and external reconciliation verified
Owner: Codex
Last Updated: 2026-08-12
Last Updated: 2026-08-13
Release Classification: release-required
Target Stable Version: 0.5.0
Tracking Issues: #76, #78 (OCR 1.9.2); feature PR #77
Closure Reconciliation: no-release
Closure Target Stable Version: N/A
Tracking Issues: #76, #78 (OCR 1.9.2); feature PR #77; release PR #79

### Goal

Expand All @@ -21,21 +23,21 @@ the existing read-only evidence MCP, repair issue #76 release recovery, and
qualify checksum-pinned OCR 1.9.2 through issue #78 before final validation.
The implementation, installed-artifact E2E, both owner-authorized local OCR
review cycles, deterministic remediation, package reorganizations, protected
feature merge, and TestPyPI development readback are complete. The final
repository mutation for stable 0.5.0 is locally prepared and validated; complete
its protected release PR, publication, immutable evidence, issue closure, and M2
external reconciliation without another repository pull request.
feature and release merges, stable publication, immutable evidence, issue
closure, and M2 external reconciliation are complete. This documentation-only
reconciliation records that externally verified outcome without changing the
package or publishing another artifact.

### Decisions

- Release-required target is 0.5.0. Keep this plan active through feature PR,
TestPyPI development verification, final release PR, stable registries,
provenance, annotated tag, immutable Release, receipt, supported-Python
installs, and completed closure of issues #76 and #78.
- The release PR records M2 and external publication as pending because those
facts do not exist before merge. After its immutable receipt and independent
readback prove stable delivery, close the issues and active objective without
another repository mutation; the release receipt is the final status evidence.
- The M2 lifecycle was release-required with target 0.5.0 and remained active
through feature and release PRs, registry publication, provenance, annotated
tag, immutable Release, receipt, supported-Python installs, and completed
closure of issues #76 and #78.
- Release PR #79 correctly recorded external publication as pending before its
merge. The immutable receipt and independent readback now prove stable
delivery. The present status reconciliation is a no-release documentation
correction and does not alter the completed release lifecycle.
- Use only anonymized technology selection conclusions from the private
inventory. Never persist private host, project, namespace, path, payload, or
identifying aggregate data; all public fixtures and examples are synthetic.
Expand Down Expand Up @@ -147,13 +149,34 @@ external reconciliation without another repository pull request.
16. [x] Prepare and locally validate the final release candidate as the last
repository mutation, archive completed 0.4.7 history, consume fragments 76,
77, and 78, and reconcile M2 while leaving external publication pending.
17. [ ] Push the release branch once, open the exact final release PR, read back
17. [x] Push the release branch once, open the exact final release PR, read back
its head, required checks, and review threads, then squash-merge only after
every protected gate passes.
18. [ ] Complete stable 0.5.0 TestPyPI/PyPI, provenance/hash/tag/immutable
18. [x] Complete stable 0.5.0 TestPyPI/PyPI, provenance/hash/tag/immutable
Release/receipt/Python-install readback and close #76 and #78 as completed
without another repository PR.

### Stable Delivery And External Reconciliation Checkpoint

- Release PR #79 was read back at reviewed head
`e3ceda38b28c056a3391492e542c7daf8bfbfc78` and merged as signed commit
`008f99d8e8b745c19cc7064832890e31d7d8a555`; the merge and reviewed head
have the same tree. Release workflow `31604133351` completed every
authorization, build, registry, supported-Python verification, and immutable
GitHub Release job successfully.
- Stable TestPyPI and PyPI artifacts, provenance, hashes, annotated tag
`v0.5.0`, and the immutable GitHub Release were independently read back. The
release receipt SHA-256 is
`f375762bbac6659d296918b35a2f61155882311659add04310744921feaa293c`.
- Issues #76 and #78 contain the canonical receipt comment and are closed as
completed. The next scheduled compatibility discovery completed successfully
with OCR 1.9.2 still current and no newly opened release issue. BL-008 and
BL-009 are complete; conditional BL-010 remains M6 work and does not block M2.
- M2 is therefore established. This no-release documentation reconciliation
updates status-bearing sources only; it does not run OCR again, change the
package version, or publish artifacts. The full 0.5.0 cycle remains here until
the next release PR archives it under the documented lifecycle rule.

### Feature Merge And Development Publication Checkpoint

- Feature PR #77 was updated once after local consolidation and read back at
Expand Down
9 changes: 4 additions & 5 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The diagram uses green for established, blue for in-progress or next work, gray
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/>in progress"]
M1 --> M2["M2 Ecosystem and framework coverage<br/>established"]
M1 --> M4["M4 Policy and project guidance<br/>planned"]
M1 --> M5["M5 Measurement audit and profiles<br/>planned"]
M1 --> M6["M6 Later and conditional work<br/>conditional"]
Expand All @@ -19,18 +19,17 @@ flowchart LR
classDef planned fill:#57606a,stroke:#424a53,color:#ffffff
classDef conditional fill:#9a6700,stroke:#7d4e00,color:#ffffff

class M0,M1 established
class M0,M1,M2 established
class M3 next
class M4,M5 planned
class M2 next
class M6 conditional
```

| Milestone | Status | Intended outcome | Major dependency | Completion signal |
| --- | --- | --- | --- | --- |
| 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 | In progress | Supply framework and template evidence selected from demonstrated use without creating framework-specific review engines. | Established evidence, snapshot/delta, scoped-completeness, and built-in MCP contracts. | Selected static plugins and template review rules have deterministic fixtures, bounds, provenance, component ownership, completeness, first-class source/target delta queries, installed-artifact validation, verified use through the existing built-in MCP, and independently read-back stable delivery. |
| M2 Ecosystem and framework coverage | Established | Supply framework and template evidence selected from demonstrated use without creating framework-specific review engines. | Established evidence, snapshot/delta, scoped-completeness, and built-in MCP contracts. | Selected static plugins and template review rules have deterministic fixtures, bounds, provenance, component ownership, completeness, first-class source/target delta queries, installed-artifact validation, verified use through the existing built-in MCP, and independently read-back stable delivery. |
| 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 | 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. |
Expand All @@ -40,7 +39,7 @@ flowchart LR

- OCR compatibility and the established common evidence model now converge at compact-bootstrap/evidence-MCP integration.
- 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 implementation, protected feature merge, and TestPyPI development verification are complete; only the final stable-delivery signal remains pending in the release lifecycle. Conditional future ecosystem packs do not block closure, and M4 can proceed independently from the stable evidence contracts it consumes.
- M2 is established through independently verified stable delivery of its framework plugins, template rules, scoped evidence, deltas, and built-in MCP projection. Conditional future ecosystem packs remain in M6 and do not reopen M2; M4 can proceed independently from the stable evidence contracts it consumes.
- 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.
Expand Down
1 change: 1 addition & 0 deletions docs/codex/TASKS_BACKLOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Statuses are `ready`, `planned`, `parked`, `conditional`, or `owner action`. Rel
| File-based user configuration | Retained and redesigned | BL-020 waits for profile, MCP, and evidence schemas while preserving environment precedence and excluding secrets. |
| M2 evidence gaps (BL-008) | Completed and removed | Demonstrated framework resolution, component ownership, scoped completeness, and first-class MCP delta projection ship through the shared evidence contracts; unproven formats are not retained as mandatory work. |
| M2 framework selection (BL-009) | Completed and removed | The anonymized selection produced bounded static Jinja2, Go web, Symfony/Twig, and React/Next providers with synthetic cross-provider validation and no second MCP. |
| M2 milestone closure | Completed | Stable 0.5.0 delivery and independent external readback establish M2; BL-010 remains a conditional M6 extension and is not unfinished M2 scope. |

## M3 External MCP hardening

Expand Down