From b9aeb673c7b3dcd4e6d590ed51354962671b1602 Mon Sep 17 00:00:00 2001 From: Chris Leiter Date: Mon, 5 Oct 2026 18:45:35 -0400 Subject: [PATCH] Publish preview 5 identity checks and MIT reuse terms --- .github/copilot-instructions.md | 2 +- AGENTS.md | 2 +- CHANGELOG.md | 15 ++++ CONTRIBUTING.md | 3 + LICENSE | 21 ++++++ README.md | 31 +++++--- START_HERE.md | 2 +- VERSION | 2 +- docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md | 82 ++++++++++++++++++++++ docs/exec_ctrl/V2_PUBLICATION_READINESS.md | 3 + docs/v2/MIGRATION.md | 7 ++ docs/v2/ROADMAP.md | 5 +- docs/v2/TOOLING.md | 5 +- examples/v2/docs-record.json | 2 +- examples/v2/pending-release-record.json | 2 +- framework/catalog.json | 2 +- tests/README.md | 4 +- tests/test_publication_readiness.py | 43 ++++++++++++ tools/exec_ctrl.py | 7 +- 19 files changed, 219 insertions(+), 21 deletions(-) create mode 100644 LICENSE create mode 100644 docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fb6bb28..7b0ff5c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,4 +7,4 @@ Use only relevant modules. Preserve host/organization policy and existing user w This repository contains the framework, optional offline tooling, templates and historical v1 references. Do not load legacy packs for a v2 task unless maintaining an explicitly selected v1 adoption. Current work and evidence are in -[the current publication record](../docs/exec_ctrl/V2_PUBLICATION_READINESS.md). +[the current publication record](../docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md). diff --git a/AGENTS.md b/AGENTS.md index f2f5c68..10bad7a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ Read only the modules relevant to the task. Do not recursively load the v1 libra When editing this repository: - Treat Markdown, adapters, catalog, examples and tools as one product. Keep their - behavior coherent. Current work: [publication readiness](docs/exec_ctrl/V2_PUBLICATION_READINESS.md). + behavior coherent. Current work: [publication readiness](docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md). - Preserve existing work and historical evidence. Do not rewrite v1 records as v2 proof. Label preserved v1 instructions as reference. - Use Python 3.10+ standard library only for the optional helper. It must remain diff --git a/CHANGELOG.md b/CHANGELOG.md index e7f7ef1..78a856b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## 2.0.0-preview.5 — 2026-10-05 + +- Publish the accumulated v2 improvements with a pinned preview tag and clear + current-main entry. Preserve the older `v2` branch and v1 history as reference. +- Add the owner-selected MIT license for framework use and distribution. +- Apply feedback from the controlled Go availability-summary repair: preserve + dirty work, compare current source identity and distinguish author review. +- Include disposable release acceptance for wrong staged artifacts, verified + rollback, unavailable policy, inert metadata and missing independent approval. +- Reject stale public README and newest changelog versions in repository validation; + add failing-before-repair release-metadata regressions. +- Keep the helper offline/read-only, schema 1 and existing CLI formats. Historical + records remain pinned to their original helper/version. See + [publication evidence and limits](docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md). + ## 2.0.0-preview.4 — 2026-10-05 - Reject observed file edits, truncation, replacement, deletion or redirection diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1392afe..9a70555 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,9 @@ Change normative guidance before adapting examples and evidence records. Add tes for behavioral changes to routing, parsing, policy composition or evidence checks; do not add tests that only assert prose contains a preferred sentence. Check the entry contract's reading budget and inspect version/migration boundaries. +Keep VERSION, catalog, activation entry, the README's bold current-version marker, +newest changelog heading and active example records on the same version. Preserve +historical changelog entries and evidence records with their original identities. Verify generated pending records and example policies as well as changed commands. Test denial, stale identity, malformed input and read-only behavior for new helper capabilities. Explicit-file snapshots must disclose their bounded scope; never diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e456a6e --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Leiter Consulting + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index e3a0b6f..8132548 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,12 @@ Give your agent the work and this repository: > Fix the checkout retry bug. Use https://github.com/LeiterConsulting/exec-ctrl -The default branch carries the v2 preview; the [v2 branch](https://github.com/LeiterConsulting/exec-ctrl/tree/v2) -is also available for development. Pin a reviewed commit for reproducible ongoing -adoption. The preserved [v1 guide](V1_README.md) remains available for existing users. +The default branch, `main`, carries the current v2 preview. See 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 +[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. The agent reads the entry instructions, inspects your project, selects relevant controls, and carries them through implementation, verification and handoff. @@ -72,11 +75,19 @@ flowchart LR ## Status -**2.0.0-preview.4** adds reproducible project-lifecycle tests, audited CLI execution -and rejection of observed file changes during snapshot capture. It retains the -session/checkpoint guidance, task playbooks, pending records and typed policy gates. -See [publication readiness and evidence](docs/exec_ctrl/V2_PUBLICATION_READINESS.md) -and [test coverage](tests/README.md) for current results and how to reproduce them. +**2.0.0-preview.5** brings the controlled real-project feedback and disposable +release/rollback acceptance into a versioned public preview. It checks artifact +identity despite a healthy response, preserves required review holds, and rejects +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. + +The [Ping Monitor revisit](docs/exec_ctrl/REAL_PROJECT_PING_MONITOR.md) exercised a +real Go defect in an isolated worktree. The +[policy/release scenarios](docs/exec_ctrl/V2_POLICY_RELEASE_ACCEPTANCE.md) exercised +actual disposable artifacts and deliberately held missing approval. These controlled +cases inform the guidance; they do not establish independent IDE adoption. The [preview 3 evolution record](docs/exec_ctrl/V2_SESSION_EVOLUTION.md) preserves its 97-test hosted validation and controlled lab results. Those historical results @@ -93,3 +104,7 @@ evidence explicit. Existing v1 users can keep their workflows. The [v1 guide](V1_README.md), templates and historical records remain available as versioned reference. + +## License + +exec-ctrl is available under the [MIT license](LICENSE). diff --git a/START_HERE.md b/START_HERE.md index 856ad40..0434a97 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -1,6 +1,6 @@ # exec-ctrl: agent activation contract -Version: 2.0.0-preview.4. This is the v2 entry point. Use plain Markdown; no +Version: 2.0.0-preview.5. This is the v2 entry point. Use plain Markdown; no installation, command, account or plugin is required for the workflow. ## 1. Establish target, intent and access diff --git a/VERSION b/VERSION index 43b82e4..8caa887 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.0.0-preview.4 +2.0.0-preview.5 diff --git a/docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md b/docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md new file mode 100644 index 0000000..1094101 --- /dev/null +++ b/docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md @@ -0,0 +1,82 @@ +# Preview 5 publication + +Date: 2026-10-05. Baseline: merged `main` at +`32f1795a27fa3c55e7f79a260293c99ad0d51c48`, framework preview 4. +User scope: final tests, fixes, retests and public availability for project use. +Method and target: this repository. Publication branch: `codex/preview-5-publication`. + +## What this release contains + +Preview 5 packages the compact link-first activation, ten selectively loaded +modules, session controls, additive policy gates and optional offline/read-only +Python helper. It includes the merged +[Ping Monitor feedback](REAL_PROJECT_PING_MONITOR.md) and +[disposable release/policy acceptance](V2_POLICY_RELEASE_ACCEPTANCE.md). +Their original revisions/results remain historical evidence, not fresh proof +for this release. The Go application fix remains a separate local project change. + +Final inspection found that repository validation accepted a stale public README +or newest changelog entry while catalog/entry versions matched. Two new negative +tests failed before the correction; a positive historical-changelog case passed. +Validation now requires the current README version marker and newest changelog +version. The three cases run in ordinary unittest discovery and CI. Link checking +is isolated in those fixtures and exercised separately by the existing suite. + +VERSION, catalog, activation and active synthetic records advance together to +`2.0.0-preview.5`. Schema 1, CLI/snapshot formats, host authority and helper +side-effect limits stay unchanged. Review new controls and revalidate active +records; preserve historical records with their original helper/version. +The activation entry gains no mandatory reads. The README identifies `main` as +current and the older `v2` branch as historical instead of offering it for new work. +On 2026-10-05 the owner selected the [MIT license](../../LICENSE); its standard +text is included at the repository root. This resolves the roadmap's owner-choice +gate for reuse terms without closing the independent adoption gates. + +## Verification and publication + +Run from the repository root with Python 3.10+ and the standard library: + +```sh +python tools/exec_ctrl.py validate +python -m unittest discover -s tests -v +git diff --check +``` + +- Release-metadata reproduction: three cases ran against the pre-fix helper; + stale README and stale newest changelog were incorrectly accepted (two failures). +- Local Windows/Python 3.13.7 validation: version preview 5, ten modules and 307 + supported local links. Activation entry: 1,264 words (ceiling 1,700). +- Full local suite: 114 discovered tests, 112 passed and two symlink-creation + skips. `git diff --check` passed. Release-metadata regressions pass after repair. +- A tracked-source ZIP extracted outside the checkout passed repository validation + and all 114 tests, with the same two host-specific skips. No Git metadata, + local test artifacts or external project work is required in the source archive. +- Hosted Windows/Linux Python 3.10/3.13 results must belong to the final PR head; + exact job logs and disposition are recorded with the GitHub release below. +- Merge/tag publication requires the main tree to match that tested candidate. + The tag target and final publication status are available in GitHub metadata. + +Publication identity and hosted results belong to the release's PR and +[GitHub prerelease](https://github.com/LeiterConsulting/exec-ctrl/releases/tag/v2.0.0-preview.5). +Do not extend earlier passing runs to an untested revision. GitHub's source +archives contain the framework; no plugin, generated target documents or installer +is required for the Markdown workflow. + +## Use and acceptance limits + +For current updates, give your agent its task and the repository link: + +> Fix the checkout retry bug. Use https://github.com/LeiterConsulting/exec-ctrl + +For reproducibility, substitute +https://github.com/LeiterConsulting/exec-ctrl/tree/v2.0.0-preview.5 and retrieve the +entry/modules from that revision. If the agent cannot fetch them, it must disclose +that limit rather than claim activation. See [migration](../v2/MIGRATION.md). + +This is a public preview for scoped project use. Offline helper acceptance and +controlled author-run cases do not establish independent task-plus-link adoption +across IDEs, real enterprise compliance, approved scanner integration, external +connector writes, independent review or production/customer acceptance. The +[field-trial protocol](../v2/FIELD_TRIALS.md) and +[stable-release gates](../v2/ROADMAP.md) remain applicable. Source identity and +evidence tags cannot establish semantic truth or authenticate an approver. diff --git a/docs/exec_ctrl/V2_PUBLICATION_READINESS.md b/docs/exec_ctrl/V2_PUBLICATION_READINESS.md index 0a10057..7431fa2 100644 --- a/docs/exec_ctrl/V2_PUBLICATION_READINESS.md +++ b/docs/exec_ctrl/V2_PUBLICATION_READINESS.md @@ -1,5 +1,8 @@ # v2 publication readiness +This record covers preview 4. Current release preparation and acceptance: +[preview 5 publication](V2_PREVIEW_5_PUBLICATION.md). + Started: 2026-10-05. Baseline: `2b9cfbd`, clean `main`, preview 3. Method and target: this repository. Branch: `codex/publication-readiness`. User scope: put tests in place, execute and improve the framework, iterate on diff --git a/docs/v2/MIGRATION.md b/docs/v2/MIGRATION.md index f0adf6e..2bb7860 100644 --- a/docs/v2/MIGRATION.md +++ b/docs/v2/MIGRATION.md @@ -42,3 +42,10 @@ Preview.4 retains schema 1, the snapshot format and CLI commands. Snapshot captu now rejects observed changes during a file read. A previously accepted unstable capture may return exit 2; isolate the inputs and capture again. Preserve earlier records with their original helper/version rather than relabeling old evidence. + +Preview.5 retains schema 1 and the existing CLI/snapshot formats. Repository +validation additionally rejects stale README and newest changelog version metadata. +Use `main` for current instructions or the `v2.0.0-preview.5` tag for a fixed source; +the older `v2` branch preserves an earlier preview. For active machine records, +review the updated guidance, regenerate with the current version and recheck current +evidence. Keep earlier records and their helpers unchanged. diff --git a/docs/v2/ROADMAP.md b/docs/v2/ROADMAP.md index ac48fd6..c8a4e67 100644 --- a/docs/v2/ROADMAP.md +++ b/docs/v2/ROADMAP.md @@ -98,4 +98,7 @@ offline suite does not satisfy the cross-agent gate. No repository license file existed in the reviewed baseline. Record the owner's chosen reuse/distribution terms before presenting a stable release for broad -adoption; this increment does not invent those terms. +adoption. On 2026-10-05 the owner selected the [MIT license](../../LICENSE) for +[preview 5 publication](../exec_ctrl/V2_PREVIEW_5_PUBLICATION.md). That decision +addresses reuse terms; the independent adoption and other acceptance gates above +remain open. diff --git a/docs/v2/TOOLING.md b/docs/v2/TOOLING.md index 975a0a2..5d767d9 100644 --- a/docs/v2/TOOLING.md +++ b/docs/v2/TOOLING.md @@ -154,8 +154,9 @@ validation, or a caller's parsing error for a failed application test. This is a structural checker, not a security scanner, policy engine or proof of completion. It cannot detect omitted risk facts, undisclosed policies, fabricated reports or a stale snapshot given a new label. Review those claims separately. -It does not fetch evidence references. `validate` checks catalog/entry coherence -and local Markdown file destinations. Supported link syntax includes inline links +It does not fetch evidence references. `validate` checks catalog/entry coherence, +current README/changelog version metadata, active examples and local Markdown +file destinations. Supported link syntax includes inline links and images, titles, angle destinations, balanced/escaped parentheses, and full, collapsed or shortcut references. Fenced code, inline code and HTML comments are ignored. First reference definitions win; unused definitions are not checked. diff --git a/examples/v2/docs-record.json b/examples/v2/docs-record.json index 2a6a0f8..c7a16a5 100644 --- a/examples/v2/docs-record.json +++ b/examples/v2/docs-record.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "framework_version": "2.0.0-preview.4", + "framework_version": "2.0.0-preview.5", "id": "synthetic-docs-example", "objective": "Illustrate a reviewed spelling correction; no real task evidence", "subject": "synthetic-example-snapshot-1", diff --git a/examples/v2/pending-release-record.json b/examples/v2/pending-release-record.json index ce7e04c..461fa92 100644 --- a/examples/v2/pending-release-record.json +++ b/examples/v2/pending-release-record.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "framework_version": "2.0.0-preview.4", + "framework_version": "2.0.0-preview.5", "id": "synthetic-pending-release", "objective": "Illustrate pending release obligations; no real approvals or evidence", "subject": "synthetic-unverified-inputs", diff --git a/framework/catalog.json b/framework/catalog.json index 18baf13..889a187 100644 --- a/framework/catalog.json +++ b/framework/catalog.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "framework_version": "2.0.0-preview.4", + "framework_version": "2.0.0-preview.5", "entry": "START_HERE.md", "kinds": ["docs", "fix", "feature", "refactor", "audit", "incident", "migration", "release", "planning"], "risks": ["low", "medium", "high", "unknown"], diff --git a/tests/README.md b/tests/README.md index dcd05bd..23eaf18 100644 --- a/tests/README.md +++ b/tests/README.md @@ -19,7 +19,7 @@ the optional helper itself remains offline and read-only. | `test_exec_ctrl.py` | Routing, authority/risk facts, additive policy identity, evidence gates, closure denials, CLI exit codes | | `test_adversarial.py` | Malformed JSON/type mutations, size limits, policy order and supported local Markdown links | | `test_session_tools.py` | Pending records, typed evidence requirements, current-file snapshots, containment and resource bounds | -| `test_publication_readiness.py` | Complete disposable project workflow, all modes/modules through 94 routing cases, audited CLI behavior, history preservation and unstable capture | +| `test_publication_readiness.py` | Complete disposable project workflow, all modes/modules through 94 routing cases, audited CLI behavior, history preservation, unstable capture and stale release-metadata denial | | `test_release_acceptance.py` | Real disposable zipapp build/staging/runtime/rollback, required review hold, unavailable policy, inert metadata and a guarded private-file canary | ## Reproducible project acceptance @@ -81,5 +81,5 @@ also require an agent to inspect the real target and carry out their guidance. O results cannot prove instruction retrieval, semantic defect detection, actual enterprise policy compliance, connector authorization, independent approval or customer acceptance. Use the [field-trial protocol](../docs/v2/FIELD_TRIALS.md) for task-plus-link adoption -and the [publication record](../docs/exec_ctrl/V2_PUBLICATION_READINESS.md) for this +and the [publication record](../docs/exec_ctrl/V2_PREVIEW_5_PUBLICATION.md) for this increment's evidence. Keep earlier runs/versioned records unchanged. diff --git a/tests/test_publication_readiness.py b/tests/test_publication_readiness.py index 5129f31..e81c503 100644 --- a/tests/test_publication_readiness.py +++ b/tests/test_publication_readiness.py @@ -3,6 +3,7 @@ import copy import json import os +import shutil import subprocess import sys import tempfile @@ -14,6 +15,48 @@ import exec_ctrl as ec +class ReleaseMetadataTests(unittest.TestCase): + """Reject stale public release identity even when the catalog is coherent.""" + + def setUp(self): + temp = tempfile.TemporaryDirectory(prefix="exec-ctrl-release-metadata-") + self.addCleanup(temp.cleanup) + self.root = Path(temp.name).resolve() + self.version = ec.load_catalog()["framework_version"] + files = ["VERSION", "framework/catalog.json", "START_HERE.md", "README.md", + "AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md", "CHANGELOG.md", + "examples/v2/team-rules.json", "examples/v2/release-rules.json", + "examples/v2/docs-record.json", "examples/v2/pending-release-record.json"] + files.extend(module["path"] for module in ec.load_catalog()["modules"]) + for name in files: + target = self.root / name + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(ec.ROOT / name, target) + # Isolate release identity; supported links have their own fixture coverage. + links = patch.object(ec, "check_links", return_value=0) + links.start() + self.addCleanup(links.stop) + + def test_current_release_accepts_preserved_historical_changelog(self): + result = ec.validate_repository(self.root) + self.assertTrue(result["valid"]) + self.assertEqual(result["version"], self.version) + + def test_validation_rejects_stale_readme(self): + readme = self.root / "README.md" + readme.write_text(readme.read_text(encoding="utf-8").replace( + "**" + self.version + "**", "**1.0.0**"), encoding="utf-8") + with self.assertRaisesRegex(ec.Invalid, "README version mismatch"): + ec.validate_repository(self.root) + + def test_validation_rejects_stale_newest_changelog_even_with_current_history(self): + changelog = self.root / "CHANGELOG.md" + changelog.write_text("# Changelog\n\n## 1.0.0\n\nHistorical notes\n\n" + + changelog.read_text(encoding="utf-8"), encoding="utf-8") + with self.assertRaisesRegex(ec.Invalid, "latest changelog version mismatch"): + ec.validate_repository(self.root) + + class PublicationReadiness(unittest.TestCase): @classmethod def setUpClass(cls): diff --git a/tools/exec_ctrl.py b/tools/exec_ctrl.py index 963b375..2b4a9d2 100644 --- a/tools/exec_ctrl.py +++ b/tools/exec_ctrl.py @@ -560,6 +560,11 @@ def validate_repository(root=ROOT): catalog = load_catalog(root) version = (root / "VERSION").read_text(encoding="utf-8").strip() require(version == catalog["framework_version"], "VERSION/catalog mismatch") + readme = (root / "README.md").read_text(encoding="utf-8") + require("**" + version + "**" in readme, "README version mismatch") + changelog = (root / "CHANGELOG.md").read_text(encoding="utf-8") + latest = re.search(r"^## ([^\s]+)(?:[ \t].*)?$", changelog, flags=re.M) + require(latest is not None and latest[1] == version, "latest changelog version mismatch") entry = (root / catalog["entry"]).read_text(encoding="utf-8") require(version in entry, "entry version mismatch") require(len(entry.split()) <= 1700, "activation contract exceeds 1700-word budget") @@ -575,7 +580,7 @@ def validate_repository(root=ROOT): check_record(read_json(root / "examples/v2/pending-release-record.json"), catalog, [example_rules[1]]) checked = check_links(root) return {"valid": True, "version": version, "modules": len(catalog["modules"]), "local_links_checked": checked, - "limits": "Catalog, examples and supported local links only; external URLs, anchors and actual agent behavior are not verified."} + "limits": "Catalog, release metadata, examples and supported local links only; external URLs, anchors and actual agent behavior are not verified."} def main(argv=None):