Skip to content

feat(release): enforce exact-commit required checks before publication - #16

Open
CompleteDotTech wants to merge 23 commits into
mainfrom
agent/issue-805-p0-enforce-exact-commit-release-governance
Open

feat(release): enforce exact-commit required checks before publication#16
CompleteDotTech wants to merge 23 commits into
mainfrom
agent/issue-805-p0-enforce-exact-commit-release-governance

Conversation

@CompleteDotTech

@CompleteDotTech CompleteDotTech commented Aug 30, 2026

Copy link
Copy Markdown
Owner

Context

  • Summary: Publication is now an enforceable authorization decision tied to the exact source commit. A new exact-commit gate refuses to release a tag unless the CI run for that exact commit completed successfully on main and every required check for that SHA succeeded; the required-check names live in a versioned manifest bound to real CI job ids and are contract-tested against workflow routing. Both publication workflows (npm and GitHub Release) run the gate before any mutation and retain a deterministic machine-readable acceptance receipt. This is slice 1 of the issue — the in-repo enforceable controls — with the branch-protection/ruleset configuration, Rust toolchain version pinning, SBOM, and security/support surface gate documented as remaining in docs/RELEASE-GOVERNANCE.md ("Remaining work").
  • Files changed: scripts/verify-release-commit-gate.mjs (+560), scripts/verify-release-commit-gate-test.mjs (+660, 50 tests), scripts/release-required-checks.json, scripts/classify-ci-changes.py + test, .github/workflows/release-npm.yml, .github/workflows/release-github.yml, .github/workflows/ci.yml, scripts/check-ci-workflow-test.py, docs/RELEASE-GOVERNANCE.md, docs/index.md.
  • Issue: Refs P0: enforce exact-commit release governance and shipped-truth attestation OpenCoven/coven#805 (not Closes — slice 1 of the issue; repository-settings items remain).

Implementation

  • Approach: scripts/verify-release-commit-gate.mjs resolves the CI workflow run for the exact tagged commit over the REST API (workflow runs by head_sha, check-runs filter=latest, paginated with fail-closed refusal on truncated evidence) and enforces: run on main/push for the exact SHA, completed + success, strict required checks present-and-success for that SHA, routed checks success-or-skipped/absent, evidence only from the github-actions app. release-npm.yml gains an exact-source-gate job fed by the tag verification job's head_sha output; npm-publish requires it, so a red, missing, stale, cancelled, or skipped-required check on the tagged commit blocks registry mutation. release-github.yml re-runs the same gate against the verified source commit before creating/updating the release. The gate writes a deterministic receipt (coven.release-commit-gate-receipt/v1, no timestamps, no secrets) uploaded as the coven-release-commit-gate-<tag> artifact in both workflows.
  • User-visible behavior: none for CLI users; release operators get a hard failure (with the exact refusing class in the error) instead of a release from a red/unverified commit, plus retained check evidence per release.
  • Compatibility notes: no changes to npm publishing mechanics, tag signing requirements, provenance verification, or asset immutability semantics — the gate is strictly additive and fail-closed. Required-check names in scripts/release-required-checks.json are now contract-bound to ci.yml job names; renaming a CI job requires updating the manifest in the same PR (the contract test enforces this).

Test plan

Local checks actually run on this machine (no Rust toolchain available locally; Rust lanes deferred to CI):

  • node --test scripts/verify-release-commit-gate-test.mjs — 50/50 pass, covering every negative class in the issue: required check failure on the exact commit; green ancestor / tag-target SHA mismatch; missing, stale (queued/in-flight incl. newer attempt over green older), cancelled, timed-out, and skipped-when-required checks; failed routed check; third-party evidence; ambiguous duplicates; mismatched check-run head SHA; incoherent version metadata (non-vX.Y.Z); malformed manifests; truncated/paginated REST evidence; CLI misuse.
  • node --test scripts/package-github-release-test.mjs — 34/34 pass (existing release contract intact).
  • node --test scripts/release-stress-test.mjs — 4/4 pass.
  • python3 scripts/check-ci-workflow-test.py — extended with gate-wiring + manifest↔ci.yml job-name contract tests; all pass.
  • python3 scripts/classify-ci-changes-test.py — new routing entries covered; all pass.
  • python3 scripts/check-secrets.py — clean.
  • python3 scripts/check-coven-privacy.py --staged — clean on every commit.
  • actionlint over all workflows — clean.
  • cargo fmt --check / cargo clippy --workspace --all-targets -- -D warnings / cargo test --workspace --locked — deferred to CI (no Rust toolchain on this machine; no Rust code is touched by this PR).

Risk and Rollback

  • Risk level: medium for the release pipeline itself (new hard gate), low for everything else. Worst case: a legitimate release is blocked by the gate refusing evidence, which fails loudly with the reason.
  • Rollback plan: revert the workflow wiring commits — the gate is additive; removing exact-source-gate from npm-publish needs and the release-github step restores the prior pipeline exactly. No data or registry state changes.

Agent Handoff

  • Current state: three signed conventional commits on agent/issue-805-p0-enforce-exact-commit-release-governance; all runnable local checks green; actionlint clean.
  • Follow-ups (issue P0: enforce exact-commit release governance and shipped-truth attestation OpenCoven/coven#805 remaining work, detailed in docs/RELEASE-GOVERNANCE.md): apply the main ruleset/branch protection with administrator enforcement (maintainer action, not branch-editable); pin the Rust toolchain to an exact version; SBOM retention; security/support surface gate; extend the receipt with artifact digests/registry versions/signer output and link it from the release body.
  • Known gaps: the branch-protection configuration cannot be validated from a branch; the governance doc specifies the exact settings (including a ruleset JSON sketch) for maintainers to apply.

Vehicle note: opened in the fork CompleteDotTech/coven as the CI vehicle — this token cannot write to OpenCoven/coven. Re-target upstream once write access is restored. Refs OpenCoven#805.

@CompleteDotTech CompleteDotTech self-assigned this Aug 30, 2026
@CompleteDotTech CompleteDotTech mentioned this pull request Aug 30, 2026
Draft
9 tasks
@CompleteDotTech
docs(automations): record Coven Automations v1 program status (coven#…
44b540e 
…854) (OpenCoven#861)

Adds one dated status/decision record for issue OpenCoven#854 in docs/superpowers/plans/.

Independently verified against main @ 1364cec (2026-08-30): the coven#816
foundation series (PR OpenCoven#846, PR OpenCoven#847, parts 6-8 commits) landed the durable
local scheduler core - definitions, SQLite definition/occurrence/run records
with unique occurrence fencing, RRULE planning, bounded leases with expiry
recovery, latest-only misfire / overlap refusal, the 60s daemon tick with
scheduled dispatch, shared launch path, health and run history,
non-destructive paused legacy import, and coven.automations.* control
actions. Records what is still absent for v1 (versioned protocol schemas,
authority/receipt binding, deterministic-time contract, SDK surface,
conformance/chaos/SLO gates, live Beads mutation), the gate-by-gate verdict,
and the critical path. The program issue remains open; this record closes
no issue.

Refs OpenCoven#854.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech

CompleteDotTech commented Aug 30, 2026

Copy link
Copy Markdown
Owner Author

CI status after run 33321739750:

  • My breakage, fixed in aefe15a ("test(release): expect the exact-source gate in the publish needs contract"): the npm prepublish contract test release workflow publishes every package unconditionally pins the npm-publish needs list, and adding the exact-source-gate dependency changed it. Both npm onboarding smoke legs failed on that single assertion. Verified locally: node --test scripts/publish-npm-test.mjs → 82 pass / 0 fail.
  • Unrelated failure (not my breakage, not fixed by this PR): Rust tests (Windows) failed in daemon::tests::concurrent_api_kill_during_prompt_delivery_preserves_killed_status with Error: timed out waiting on channel (job log). This PR touches no Rust code; it is a concurrency/timeout-sensitive test, and at least four other PRs were running CI concurrently on this fork. Documenting per the sweep contract; if it recurs on the re-run I will leave the PR draft rather than retry blindly.
  • Everything else passed: Classify changes, Policy guard, Rust lint (Linux), Rust tests (Linux), AFS mount (Linux/macOS), Channels package, OpenClaw bridge, engine contract, Dependency audit.

Re-watch started for the fix commit.

@CompleteDotTech
CompleteDotTech marked this pull request as ready for review August 30, 2026 16:38
@CompleteDotTech
docs: plan cryptographic fresh-user and biometric assurance proofs (c…
fb302f2 
…oven#815) (OpenCoven#871)

* docs: plan cryptographic fresh-user and biometric assurance proofs (coven#815)

Specify COVEN-ASSURANCE/1, an independently verifiable step-up proof so
request authentication can satisfy FreshUserVerification/FreshBiometric
grant requirements without trusting client-asserted assurance levels.

The plan defines: possession/step-up key separation; binding the optional
step-up authorization key and its declared assurance class into the
pairing-v2 transcript; a separate authorization-key store; canonical
proof bytes over device, grant, revocation epoch, exact request or
DeviceActionIntent digest, server-issued single-use challenge, window,
and requested assurance; server-side effective assurance computed as
min(claimed, class ceiling) and passed to DeviceGrant::authorize;
fail-closed possession-only degradation; rotation/revocation semantics;
iOS/Android platform mapping; a self-verifying synthetic golden vector;
and TypeScript/JSON Schema for implementers. Every claim cites the
current mobile_memory code path it builds on.

No code changes: this is the design artifact the issue asks for.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs(mobile): specify COVEN-ASSURANCE/1 step-up assurance proofs

Add docs/design/mobile-assurance-step-up-v1.md, the plan and
implementation contract for issue OpenCoven#815: a separately enrolled,
platform-policy-protected step-up authorization key, bound into the
pairing-v2 transcript before grant issuance, whose fresh signatures
over canonical COVEN-ASSURANCE/1 bytes (device, grant, revocation
epoch, exact request or DeviceActionIntent digest, single-use server
challenge, validity window, requested assurance) are the only way to
raise assurance above possession. The server verifies the signature,
computes effective assurance itself, and passes it to
DeviceGrant::authorize; absent/invalid/expired/replayed proofs fail
closed. Covers storage separate from the possession key, replay
protection independent of request nonces, rotation/revocation
semantics, iOS/Android key-policy mapping, a security-invariant
mapping, TypeScript types + JSON Schema, and a portable golden vector.
Design artifact only; no behavior change.

Refs OpenCoven#815

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs: operationalize Coven Automations v1 tracker roadmap and drift c…
fcc026c 
…heck (coven#859) (OpenCoven#862)

Establish the GitHub-side half of the OpenCoven#859 operational delivery graph:

- docs/roadmaps/coven-automations-v1.md: program roadmap with canonical
  tracker roles, sync metadata, P0/P1/P2 policy, generated outcome-mapping
  table, dependency graph, release gates, active blockers, and drift
  detection usage. The mapping table block is generated by
  docs/roadmaps/drift-check.mjs --render and verified on every run.
- docs/roadmaps/coven-automations-v1.mapping.json: machine-readable
  one-to-one Bead <-> GitHub mapping for OpenCoven#854, OpenCoven#816, OpenCoven#855, OpenCoven#856, OpenCoven#857,
  and OpenCoven#858, with explicit dependencies, acceptance gates, dispositions,
  and evidence links. Bead IDs stay null (warn-level W010) until
  provisioning lands through OpenCoven/coven-cave#5220 per the
  operational correction on OpenCoven#859; no competing Beads store is created
  in this repository.
- docs/roadmaps/drift-check.mjs: credential-free, offline drift check
  covering state, priority, parent/dependency, evidence, generated-mirror,
  duplicate/missing mapping, cycle, and sensitive-payload drift classes,
  with --beads-export cross-checking and --selftest proving detection.
- docs/superpowers/plans/2026-08-30-issue-859-coven-automations-v1-...md:
  dated status/decision record: what exists on main (automations series
  landed 2026-08-28 via PRs OpenCoven#846/OpenCoven#847), pre-change integrity report,
  decisions D1-D7, verdict against the OpenCoven#859 acceptance criteria,
  remaining work, critical path, and the initial evidence packet.

Refs OpenCoven#859



fix: keep automation tracker docs scanner-safe

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs: consolidate Coven security policy, threat boundary, and support…
957715f 
… claims

* docs: consolidate Coven security policy, threat boundary, and support claims

Replace the duplicated SECURITY.md (repository policy plus a copied
organization-wide disclosure addendum) with one Coven-specific operational
security contract that visibly separates:

- supported release family and security-supported surfaces, with
  experimental/disabled surfaces (AFS mount backend, OpenClaw plugin,
  remote transports) marked explicitly;
- enforced properties today, each tied to its normative contract and
  verification family (Rust authority checks, capability advertisement,
  pre-effect validation, owner-protected local transport, redaction and
  artifact defaults, secret/privacy guards, explicit mutation replay);
- residual risk and safe configuration (same-user trust vs sandboxing,
  raw-artifact opt-in, retention limits, untrusted harnesses, AgentFS
  mount posture synced with OpenCoven#779);
- private reporting via GitHub Security Advisories as the primary path,
  with no personal-channel dependency and no unsupported response-time
  commitment, plus scoped third-party dependency/provider handling;
- design goals (session/memory/agent isolation) moved out of guarantees,
  cross-referencing OpenCoven#803/OpenCoven#804 instead of claiming unimplemented A2A
  isolation.

Removes the stale OpenTrust-scope addendum, the personal Discord DM
reporting path, and the 48-hour/14-day response promises that no
accountable process currently backs.

Refs OpenCoven#808

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* fix: document tokenized invite URL privacy rule

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs(pairing): plan TUI QR bootstrap and E2EE mobile pairing (refs Op…
9847960 
…enCoven#785) (OpenCoven#867)

* docs(pairing): plan TUI QR bootstrap and E2EE mobile pairing (refs OpenCoven#785)

Add the implementation plan for issue OpenCoven#785: the coven device command
family, canonical CBOR pairing offer with Universal Link encoding,
Noise_XK handshake with QR-pinned host authentication, rendezvous relay
MVP on coven-relay, six-word human verification derived from the
handshake hash, scope selection and capability binding, the adversarial
test matrix, and the maintainer decision points.

Extends the accepted mobile-device-trust architecture and elaborates
PR 3 + the rendezvous slice of PR 4 of the pairing delivery train.
Docs-only change; cross-links the delivery plan to the new plan.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* chore(pairing): retrigger CI for the plan PR (no content change)

The pull_request opened event raced the fork's lazy workflow
registration, so no run was created. This empty commit re-emits the
synchronize event; it changes no content.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch 2 times, most recently from db25b8d to 0e59f56 Compare August 30, 2026 17:54
@CompleteDotTech
docs: remove duplicate local public documentation (OpenCoven#870)
d07bf61 
* docs: point install guidance at canonical coverage

The canonical install, platform, deployment, uninstall, and install-debugging guides are merged in OpenCoven/coven-docs, so the duplicate local pages under docs/install/ become stable pointers per the Wave A cleanup plan. docs/install/development-channels.md keeps its local content because no canonical page covers pre-release channels yet.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: point onboarding pages at canonical guidance

Duplicate local onboarding pages (quickstart, first session, onboarding, showcase, doctor) become pointers to the canonical getting-started and doctor routes. coven-tui.md keeps its legacy-TUI contract and its root-absolute links are fixed to the retained local session-lifecycle contract and the canonical CLI reference.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: shrink the README to a landing page and codify the public-docs boundary

The README stops duplicating the canonical manual and keeps the landing-page facts: what Coven is, one install and quick-start path, canonical links, the source-adjacent ownership table, contributor rules, and security. DOCS-MAINTENANCE.md gains the enforceable public-doc directory boundary (canonical pointers or source-adjacent exceptions with stated ownership reasons), and docs/index.md links to it.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* ci: retrigger pull request checks after enabling fork Actions

No file changes. The pull request was opened before Actions was enabled on this fork, so no workflow run was created for its head SHA. This empty commit fires a pull_request synchronize event so the CI matrix can report.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from 0e59f56 to 63e81ea Compare August 30, 2026 18:02
@CompleteDotTech
docs(807): record shipped reliability scorecard status decision (Open…
a781c9e 
…Coven#863)

Investigate issue OpenCoven#807 against main at 1364cec (2026-08-30) and record
a dated status/decision document in the repo's record location
(docs/superpowers/plans/).

Facts recorded: the existing non-gating benchmark/chaos corpus, health
and recovery surfaces, release certification (certify-release.sh,
2026-08-29), packaged-artifact journey E2E, release-stress workflow,
and AFS gating posture, each with evidence links and dates; a verdict
against all six acceptance criteria (not satisfied on main; partial on
separation-by-convention, structured receipts, and privacy-by-design);
and a dependency-ordered critical path. No measurements, targets, or
SLOs are invented.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from 63e81ea to 1fda472 Compare August 30, 2026 18:09
@CompleteDotTech
docs: record issue 670 docs program status on main
c703693 
* docs: record issue 670 docs program status on main

Add a dated status/decision record for OpenCoven#670 at
docs/superpowers/plans/2026-08-30-issue-670-docs-program-status.md.

It records, with evidence links and dates: the merged progressive-help
implementation (OpenCoven#834), the merged packaged first-session E2E (OpenCoven#835,
closing OpenCoven#777), the canonical journey and docs CI live in
OpenCoven/coven-docs (OpenCoven#775/OpenCoven#778 state), the still-open single-source
cleanup of this repository (OpenCoven#776: README shrink, residual local pages,
missing CI ownership enforcement), and the open OpenCoven#779 certification
matrix. It gives a per-criterion verdict against OpenCoven#670's nine acceptance
criteria, what remains, and the critical path.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* chore: retrigger vehicle CI after a dropped pull_request event

The fork vehicle's Actions went live at 2026-08-30T15:54Z, after PR #10
opened at 15:46Z, so the opened/ready_for_review events never started a
run (0 check-runs on the head SHA ~20 minutes after creation). Push an
empty signed commit to fire the synchronize event; no file changes.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: keep issue 670 record clear of the privacy phone detector

The Coven privacy guard's phone_number rule (E.164-like plus-digit
tokens) flags the diff-stat notation (+1828), (+464), (+279), (+323),
and (+2686) in the OpenCoven#670 status record. Restate those as insertion and
deletion counts; no content changes.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from 1fda472 to 2b79dd9 Compare August 30, 2026 18:16
@CompleteDotTech
fix(agents): enforce target input-guardrail parity across handoffs
753f4bb 
* test(agents): characterize input-guardrail ingress at handoff boundaries

Characterizes the coven-agents runner's input-guardrail behavior so the
handoff bypass in OpenCoven#803 is visible from test output before
the enforcement change:

- direct-entry rejection vs handoff entry to the same target (parity
  regression: currently the handoff target's input guardrails never run)
- handoff target GuardrailChecked event ordering (after Handoff, before
  the target's first ModelRequested) and the exact evaluated input
- multi-hop A->B->C per-boundary checks and a target rejection at hop C
- input-guardrail implementation error vs policy rejection, direct and
  handoff (GuardrailFailed keeps its own message and source)
- handoff/tool action exclusivity stays pinned

Tests encode the corrected expectation and are paired with the runner
change in the next commit; compile proof and green runs defer to CI
(this workspace has no Rust toolchain).

Refs OpenCoven#803

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* fix(agents): enforce target input-guardrail parity across handoffs

Closes the ingress bypass in Runner::run_loop (OpenCoven#803): a
handoff target's input guardrails were never evaluated, so an agent
reached through a model handoff could consume input that direct entry
to it would reject.

- extract the input-guardrail evaluation into one shared path,
  Runner::check_input_guardrails, used by direct starts and by every
  handoff boundary
- evaluate the handoff target's input guardrails against the original
  user input — the same bounded string a direct start would check,
  never a serialized transcript — after the Handoff item/event is
  recorded and before the target's first model turn or tool execution
- a target rejection or guardrail implementation error fails the run
  (RunFailureKind::InputGuardrail) before the target's model call, so
  the target receives no model request and executes no tool; the
  GuardrailFailed/GuardrailRejected distinction is preserved
- emit GuardrailChecked with the target identity and Input stage;
  exactly one terminal RunCompleted/RunFailed pairing is preserved
- multi-hop A->B->C now applies each hop's ingress policy at its own
  boundary

Documented compatibility contract: target ingress is evaluated over the
original/root user input only. The structured task/context manifest for
delegated invocations is the successor contract in
OpenCoven#804; this patch is not complete A2A security.

Handoff/tool exclusivity, fail-fast topology validation, handoff
limits, session semantics, and output-guardrail behavior are unchanged.

cargo fmt/clippy/test verification defers to CI (no Rust toolchain in
this workspace); formatting verified with a standalone rustfmt binary.

Refs OpenCoven#803
Refs OpenCoven#804

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* fix: keep handoff checks warning-free

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from 2b79dd9 to cf4ae45 Compare August 30, 2026 18:26
@CompleteDotTech
docs(cli): document the deterministic JSON help contract (OpenCoven#868)
ba3a154 
Issue OpenCoven#774 asks Coven to keep default help concise, preserve every
command through the grouped `coven help --all` view, and expose a
deterministic JSON help contract. The executable side of that work
landed in OpenCoven#834; the contract itself remained undocumented for
consumers.

Document the contract in the developer core-functionality guide
(schemaVersion 1 payload shape, determinism and leak guarantees,
drift-fails-loudly rule) and surface it to script authors in the
automation JSON guide. Extend scripts/cli-docs-test.mjs so the docs
guard fails when the contract documentation regresses.

Refs OpenCoven#774

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from cf4ae45 to b1b3b48 Compare August 30, 2026 18:40
@CompleteDotTech
docs(automations): specify coven.automations.v1 schemas, state machin…
c4c9ccb 
…es, and changefeed

Publish the coven.automations.v1 contract as spec artifacts plus a normative
design document, so Cave, the SDK, Psyche adapters, runtimes, and future
implementations can consume automations without importing Coven internals.

spec/coven-automations/v1/ (draft 2020-12 JSON Schemas and machine-readable
artifacts, following the spec/device-pairing/v1 precedent):
- five object schemas (definition, occurrence, run, attempt, receipt) with
  monotonic revisions, integrity digests, exact-revision pinning, and
  fail-closed unknown-field behavior through an explicit extension bag
- command/response envelope: every mutating command carries a stable
  adoption key (first-commit-wins replay, ADOPTION_REPLAY_MISMATCH on
  conflict) and expectedRevision where applicable; responses are
  committed/replayed/rejected only, so a domain failure can never be
  wrapped as accepted
- typed error envelope with a frozen HTTP/control-action status mapping
- versioned changefeed envelope: per-stream gapless sequences, globally
  unique event ids, causation, cursor expiry, compaction snapshots
- state-machines.json: authoritative definition/occurrence/run/attempt
  machines plus the ten normative invariants
- capabilities.json: positive and explicit negative variant negotiation
- compatibility-matrix.json: change classes and profile-refusal rules
- test-vectors.json: golden valid/invalid/unknown-field/downgrade/
  unknown-variant vectors, adoption replay and revision-conflict cases,
  duplicate and out-of-order event replay, with pinned RFC 8785 digests
- coven.automations.v1.d.ts: pinned TypeScript projection for SDK/Cave
  canaries

docs/architecture/coven-automations-v1.md: the design document, citing the
current OpenCoven#816 code paths for every gap, ratifying the lifecycle semantics,
the OpenCoven#816 non-destructive migration, the Rust type mapping, and recording
alternatives considered for the genuinely maintainer-owned decisions.

No runtime code changes: schemas, vectors, and docs only.

Refs OpenCoven#855

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from b1b3b48 to 2dfc9c3 Compare August 30, 2026 19:10
@CompleteDotTech
refactor: extract route/version authority gate from coven-cli api
39feb6d 
* refactor: extract route/version authority gate from coven-cli api

Move ApiRoute, normalize_api_route, split_path_query, and the
route-version constants out of the 25k-line api.rs into a dedicated
api_routes.rs gate module (issue OpenCoven#806 slice 1: extract pure
request/route parsing first, behind stable contracts).

- the gate keeps its exact contract: non-/api/ paths pass through
  borrowed, /api/v1/<route> is rewritten to /<route>, unsupported
  versions answer 404 invalid_request with the apiVersion and
  supportedApiVersions payload, other malformed /api/... shapes
  answer 404 not_found
- characterize the pure classifier (positive, malformed, unsupported,
  passthrough, query-splitting, version-prefix-never-retained
  property) and pin the full unsupported-version rejection envelope
  plus the uniform 404 envelope for malformed API prefixes through
  handle_request
- document the authority-direction invariant on the gate and publish
  the concentration inventory, extraction order, and
  where-new-behavior-belongs map in docs/authority-module-inventory.md

No behavior change: handlers, routes, status codes, error envelopes,
payloads, and persistence are untouched.

Refs OpenCoven#806

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* chore: format authority gate test

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from 2dfc9c3 to 98e4b27 Compare August 30, 2026 19:25
@CompleteDotTech
feat(release): add exact-commit required-checks gate and manifest
9329a67 
Publication must be an authorization decision tied to the exact source
commit being released. Add scripts/verify-release-commit-gate.mjs, which
verifies over the REST API that the CI workflow run for the exact release
SHA exists on main, completed successfully, and that every required check
for that SHA succeeded (strict checks must report success; routed checks
accept success or skipped only). A green ancestor commit, unrelated
workflow, in-flight/stale/cancelled run, skipped required check, or
third-party check evidence all fail closed.

scripts/release-required-checks.json becomes the single source of truth
for release required-check names, binding each stable check name to its
CI job id. The gate emits a deterministic machine-readable receipt
(coven.release-commit-gate-receipt/v1) recording the run identity and
per-check evidence for retention.

Route the new release-gate files to npm_packaging in the CI classifier.

Refs OpenCoven#805

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
feat(release): gate npm and GitHub release publication on the exact c…
a0681dd 
…ommit

Wire the exact-commit gate into the release pipelines:

- release-npm.yml: verify-tag now emits the tagged commit as head_sha; a
  new exact-source-gate job runs the gate against that exact SHA before
  publication and uploads the acceptance receipt as an artifact;
  npm-publish requires the gate, so a red, missing, stale, or
  skipped-required check on the tagged commit blocks registry mutation.
- release-github.yml: re-run the same gate against the verified source
  commit before creating or updating the release, upload the receipt for
  retention, and grant checks: read for the run/check evidence.
- ci.yml: run the gate's negative/mutation contract tests in the policy
  guard.
- check-ci-workflow-test.py: contract that the gate stays wired (job
  present, npm-publish depends on it, receipt uploaded, GitHub release
  re-validates) and that release-required-checks.json names stay bound to
  real ci.yml job names, so routing changes must update the manifest and
  contract together.

Refs OpenCoven#805

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs(release): add release governance and shipped-truth attestation spec
9af5915 
Document the normative release invariant (publication is an
authorization decision bound to the exact source commit), the
exact-source acceptance mechanics, required-check manifest governance,
the branch-protection/ruleset requirements including administrator
enforcement and a bounded auditable break-glass process, tag/signer and
publication controls, channel synchronization, supply-chain evidence,
the acceptance receipt schema, the negative/mutation coverage, and the
remaining slice boundary for issue OpenCoven#805.

Refs OpenCoven#805

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
test(release): expect the exact-source gate in the publish needs cont…
7791f8f 
…ract

The npm prepublish contract pins the npm-publish needs list; the new
exact-source-gate dependency changed it, breaking the 'release workflow
publishes every package unconditionally' assertion on both smoke legs.
Update the contract to require the gate alongside the verified release
context so the publication job stays fully gated.

Refs OpenCoven#805

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
CompleteDotTech force-pushed the agent/issue-805-p0-enforce-exact-commit-release-governance branch from 98e4b27 to 7791f8f Compare August 31, 2026 08:13
@CompleteDotTech
feat(release): bind exact-commit gate evidence to the selected run at…
9e0136b 
…tempt

The verifier resolved a CI run but then accepted same-named check runs from
any GitHub Actions check suite on the commit, so a same-named job from
another workflow (or app) could satisfy a required check by name alone.
Check evidence is now the job list of the exact selected run attempt
(GET /actions/runs/{id}/attempts/{attempt}/jobs): every job must carry the
selected run id, the exact commit SHA, and the source workflow name, and
every job that ran in the selected run must be a declared required check
with an allowed conclusion, so the manifest cannot silently narrow what a
release depends on.

Adds negative coverage: cross-suite job binding, foreign workflow name,
stale head SHA, unclassified job, duplicate/unnamed jobs, paginated and
truncated job lists, and an end-to-end cross-suite refusal.

Refs OpenCoven#805

Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
feat(release): require complete manifest coverage and separate pr/rel…
c98e621 
…ease check policy

The manifest contract only validated the entries it listed, so silently
removing an entry narrowed the required set without any test noticing, and
the PR-merge policy and the release policy were conflated. The manifest now
declares the complete expected sets: strict + routed (release gate),
pr_only_checks (pull_request-only jobs, never release evidence), and pr_gate
(the branch-protection merge contract: PR gate aggregate plus the checks
that run unconditionally on pull requests). Release-only push jobs must not
be required for merge; the two policies are separate sets.

Contract tests (node and python) now assert every ci.yml job is claimed by
exactly the right policy dimension with its real display name, so nothing
can silently narrow the required sets, and the release gate already refuses
any undeclared job observed in the selected run.

Refs OpenCoven#805

Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
feat(release): serialize npm publication with one stable-channel lock
9876727 
The npm concurrency group was per tag (release-npm-${{ github.ref }}), so
two stable versions could run their publication pipelines concurrently and
interleave writes to the shared `latest` dist-tag. Both release workflows
now take one stable-channel lock each (release-npm-stable-channel,
release-github-stable-channel): pending releases queue behind an in-flight
one without cancelling it, serializing the complete npm-to-GitHub release
transaction across all tags.

Refs OpenCoven#805

Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
feat(release): revalidate tag and exact checks immediately before npm…
efa6674 
… publication

Authorization could go stale between the early gate and the registry
mutation: the exact-source-gate and tag verification complete minutes
before npm-publish runs, and a required check re-run to red or a moved tag
in that window would still publish. npm-publish now carries the verified
tag object SHA through verify-tag outputs and re-proves both authorizations
in a dedicated step immediately before the first --publish step:
package-github-release.mjs revalidate-tag re-reads the remote tag from the
GitHub API and refuses a moved, replaced, deleted, unsigned, or lightweight
tag, and verify-release-commit-gate.mjs verify re-decides the exact-commit
gate on fresh check evidence. The job also stops persisting checkout
credentials and gains read-only actions/checks scope for the revalidation.

Refs OpenCoven#805

Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
feat(release): split read-only release verification from the write-en…
4bd6448 
…abled publication job

The GitHub Release workflow held contents: write for the entire pipeline —
including all verification — and its checkouts persisted git credentials.
It is now two jobs:

- verify-and-package (actions/checks/contents read, persist-credentials
  disabled) verifies the source run, signed tag, exact-commit required
  checks, npm provenance, and registry signatures, downloads the source
  artifacts, reconfirms the run attempt, and packages the deterministic
  assets into a workflow artifact. It cannot mutate anything.
- publish-release (contents: write only for release create/upload) downloads
  the packaged assets, digests the required-checks manifest from the verified
  source SHA as data (git show <release sha>:...) instead of trusting current
  main, and immediately before the release mutation re-decides the
  exact-commit gate on fresh evidence, revalidates the remote signed tag, and
  reconfirms the source run attempt — so stale authorization can never be
  spent on the mutation.

Refs OpenCoven#805

Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
feat(release): persist the tag object and gate receipt as a checksumm…
f9336bb 
…ed release asset

The acceptance evidence only lived in workflow artifacts, which expire and
are decoupled from the release itself. The verification job now fetches the
GitHub-verified annotated tag object and packages it together with the
exact-commit gate receipt as coven-v<version>-release-evidence.json — a
deterministic JSON bundle (schema coven.release-evidence/v1) that is
included in SHA256SUMS and uploaded with the release, so the release record
carries its own authorization evidence. The bundle refuses incoherent
inputs (wrong receipt schema, tag/commit mismatches, tag object drift), and
sync-release only accepts the evidence asset when the workflow declares it.

Refs OpenCoven#805

Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
docs(release): specify tag rulesets, audited bypass, and corrected pi…
523d7a8 
…nning and recovery guidance

Resolves the documentation findings from the release-governance review:

- Repository protection section now specifies the full maintainer-action
  surface: a branch ruleset for main (require PR, dismiss stale reviews,
  require last-push approval, required checks = the pr_gate set, enforce for
  administrators, block deletion/non-fast-forward, empty bypass_actors), a
  v* tag ruleset (creations restricted to release signers; update/deletion/
  non-fast-forward blocked for everyone), the contents:write ACL bound for
  release mutability (no native lock exists), and a bounded audited bypass
  process (administrator-only, time-boxed, org audit log, post-use review
  issue within one business day, exact-commit gate re-run before close).
- Corrects the mutable-action pinning claim: full-SHA pinning is enforced
  (and contract-tested) only for the release workflows; ci.yml still uses
  mutable tags and is listed as a tracked follow-up rather than claimed.
- Replaces the rerun-the-failed-workflow recovery wording with the
  channel-scoped forward-only policy: npm publication is never re-run for a
  shipped version; the GitHub-only workflow_dispatch rerun is the sanctioned
  recovery.
- Refreshes the exact-source acceptance, manifest governance, receipt, and
  coverage sections to match the selected-run job binding, completeness
  contract, point-of-mutation revalidation, and the evidence release asset.

Refs OpenCoven#805

Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@CompleteDotTech CompleteDotTech

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@CompleteDotTech