diff --git a/README.md b/README.md index 8132548..cef34ed 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,14 @@ Give your agent the work and this repository: > Fix the checkout retry bug. Use https://github.com/LeiterConsulting/exec-ctrl -The default branch, `main`, carries the current v2 preview. See the +**v2 is the current generation on the default branch, `main`.** Give your agent +the repository link for current guidance. The [preview 5 release](https://github.com/LeiterConsulting/exec-ctrl/releases/tag/v2.0.0-preview.5) -for changes and verification. For reproducible adoption, give your agent the +is the latest tagged preview; `main` also includes subsequent field feedback. +For reproducible adoption, give your agent a reviewed commit or the [version tag](https://github.com/LeiterConsulting/exec-ctrl/tree/v2.0.0-preview.5) -and retrieve all instructions from that revision. The older `v2` branch is historical; -use `main` for current updates. The preserved [v1 guide](V1_README.md) remains available. +and retrieve all instructions from that revision. The older `v2` branch is historical. +The preserved [v1 guide](V1_README.md) remains available. The agent reads the entry instructions, inspects your project, selects relevant controls, and carries them through implementation, verification and handoff. @@ -81,7 +83,14 @@ identity despite a healthy response, preserves required review holds, and reject stale README/changelog versions during repository validation. It retains the compact activation entry, session controls, typed policy gates and offline, read-only helper. See [preview 5 publication evidence](docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md) and -[test coverage](tests/README.md) for current results and reproduction commands. +[test coverage](tests/README.md) for that release's results and reproduction commands. + +Subsequent updates on `main` include the +[completed application trial](docs/exec_ctrl/REAL_PROJECT_FACILITY_OPERATIONS.md) +and delivery guidance for preserving operator state during upgrades and checking +fresh served assets. The framework owner also reports successful use in **Cursor, +VS Code and Codex**. The [field record](docs/v2/FIELD_TRIALS.md) distinguishes that +reported experience from controlled tests and host trials with captured evidence. The [Ping Monitor revisit](docs/exec_ctrl/REAL_PROJECT_PING_MONITOR.md) exercised a real Go defect in an isolated worktree. The @@ -94,8 +103,10 @@ its 97-test hosted validation and controlled lab results. Those historical resul are not proof of this revision. Previous [controlled lab results](docs/exec_ctrl/V2_SECOND_PASS_TESTING.md) remain -versioned evidence. Independent task-plus-link trials across IDEs and the stable -v2 release gate remain open; see [field trials](docs/v2/FIELD_TRIALS.md). +versioned evidence. A stable `2.0.0` release still needs recorded host/version +trials and final migration/release checks; see the +[current publication checklist](docs/v2/ROADMAP.md#current-publication-state) +and [field-trial protocol](docs/v2/FIELD_TRIALS.md). A URL cannot force an IDE to retrieve instructions. exec-ctrl also cannot enforce permissions, branch protection or organizational policy by itself. Use the host's diff --git a/docs/v2/FIELD_TRIALS.md b/docs/v2/FIELD_TRIALS.md index ccbc18b..f5982c5 100644 --- a/docs/v2/FIELD_TRIALS.md +++ b/docs/v2/FIELD_TRIALS.md @@ -1,15 +1,42 @@ # Cross-agent field trials -Status: independent blind cross-agent trials not run. The +Status reviewed 2026-10-15: the framework owner reports successful use in Cursor, +VS Code and Codex. Detailed independent task-plus-link trial records have not +been supplied; the scenario matrix below remains a protocol, not a passing result. +See [reported host use](#reported-host-use) for the available evidence and gaps. + +The [controlled local lab](../exec_ctrl/V2_CONTROLLED_LAB_RESULTS.md) and [adversarial second pass](../exec_ctrl/V2_SECOND_PASS_TESTING.md) completed in -the authoring task. This file is the independent-trial protocol, not a claim that -the scenarios below passed across IDEs. A later +the authoring task. A later [Ping Monitor revisit](../exec_ctrl/REAL_PROJECT_PING_MONITOR.md) exercised a bounded fix in an existing real project; it was also a controlled authoring run. The [existing application trial](../exec_ctrl/REAL_PROJECT_FACILITY_OPERATIONS.md) -adds local regression and installed-baseline checks, with candidate deployment -acceptance explicitly pending. Neither revisit establishes blind adoption. +adds local regression, candidate deployment, native workflows and scoped state +preservation checks. Its authorized follow-up completed the bounded native gate; +the initial pending record remains historical. Neither revisit establishes blind +adoption across IDEs. + +## Reported host use + +Recorded 2026-10-15 from the owner's feedback in the development thread: + +> Exec-ctrl works GREAT in Cursor and VS Code as well as Codex so far. + +| Reported environment | Available evidence | Details not supplied | +| --- | --- | --- | +| Cursor | Owner-reported successful use | Host/model versions, settings, method revision, task prompt, retrieval transcript, diff and per-axis results | +| VS Code | Owner-reported successful use | Agent/extension identity and version, model/settings, method revision, task prompt, retrieval transcript, diff and per-axis results | +| Codex | Owner-reported successful use, separately from the controlled authoring trials linked above | Host/model versions, settings, method revision, task prompt, retrieval transcript, diff and per-axis results for the reported sessions | + +This is useful field feedback about practical use. It does not identify the VS Code +agent as GitHub Copilot, establish blind retrieval, or supply pass/fail results for +the scenarios below. Capture those details in the +[observed-trial template](../../templates/v2/FIELD_TRIAL.md) when available; do not +reconstruct a transcript or assign a source revision from this summary. No reported +failure is identified in this feedback; unrecorded behaviors remain unknown. + +## Independent task-plus-link protocol For each host, use a disposable target repository with realistic instructions, code and tests. Record host/version/settings, date, method commit, target baseline, diff --git a/docs/v2/ROADMAP.md b/docs/v2/ROADMAP.md index c8a4e67..cd268f6 100644 --- a/docs/v2/ROADMAP.md +++ b/docs/v2/ROADMAP.md @@ -1,7 +1,40 @@ # v2 review and delivery roadmap -Baseline reviewed: `68f5c4a`, 2026-09-23. This roadmap is planning; current evidence -lives in the [foundation record](../exec_ctrl/V2_FOUNDATION_EXEC_CTRL.md). +Original baseline reviewed: `68f5c4a`, 2026-09-23. The foundation sections retain +that review. Current publication status is recorded below; earlier results remain +attached to their original revisions. + +## Current publication state + +Reviewed 2026-10-15 against `main` at +`494e43550d73d270f5948fffb8054452cdd7a313` and the owner's subsequent host feedback. +v2 is already the default framework in the main repository. Stable release +promotion is the remaining publication step, with the gates below. + +| Requirement | Current evidence / state | Next action | +| --- | --- | --- | +| Current repository entry | `main` starts with v2; the older `v2` branch and v1 guide are historical | Use the repository URL for current instructions; pin a reviewed commit for reproducibility | +| Reuse terms | Owner-selected MIT license is published | Retain the license | +| Tagged release | `v2.0.0-preview.5` pins `8f0117cf3e36975874a0b96853476391b0f115df`; subsequent field feedback is on `main` | Preserve this preview tag; create a new tag for the next release | +| Framework checks | [Merged-main CI](https://github.com/LeiterConsulting/exec-ctrl/actions/runs/37486808367) passed all 114 tests on Windows/Linux with Python 3.10/3.13 at `494e435` | Validate the final release revision; do not extend that run to later edits | +| Controlled project use | Go repair and [application deployment follow-up](../exec_ctrl/REAL_PROJECT_FACILITY_OPERATIONS.md) completed their bounded scopes | Preserve the original evidence and its limits | +| Cross-agent use | Owner reports successful Cursor, VS Code and Codex use; [host details and observed trial records](FIELD_TRIALS.md#reported-host-use) remain incomplete | Capture actual host/agent versions, invocation, retrieval and behavioral evidence for each advertised host | +| Stable `2.0.0` | Not published; the stable gate below still applies | Finish recorded host trials, migration and final release review before promotion | + +To publish a stable release: + +1. Complete the [field-trial records](FIELD_TRIALS.md) for the hosts the release + advertises, including representative boundaries and any repaired failures. + Keep successful owner reports distinct from directly observed test results. +2. Check migration against existing instructions and active records, retaining + historical records/helpers and unresolved obligations. Review the known limits. +3. Advance VERSION, catalog, activation, README, newest changelog entry and active + examples together. Run repository validation, the full test suite, whitespace + checks and the hosted matrix on the release candidate. Check the source archive. +4. Review and merge that exact candidate, verify the merged tree and checks, then + create an immutable `v2.0.0` tag and publish its release with evidence links. + Leave previous preview tags intact. A new release must identify its own tested + revision instead of reusing old passing claims. ## Existing version: retain and change