Skip to content

docs(cli): document the deterministic JSON help contract - #9

Open
CompleteDotTech wants to merge 10 commits into
mainfrom
agent/issue-774-feat-cli-add-progressive-help-disclosure
Open

docs(cli): document the deterministic JSON help contract#9
CompleteDotTech wants to merge 10 commits into
mainfrom
agent/issue-774-feat-cli-add-progressive-help-disclosure

Conversation

@CompleteDotTech

@CompleteDotTech CompleteDotTech commented Aug 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Context

  • Summary: Documents the deterministic JSON help contract (coven help --all --json) that feat(cli): add progressive public help OpenCoven/coven#834 shipped, and guards the contract documentation in the CLI docs discovery test.
  • Files changed: docs/development/cli-core-functionality.md (+37), docs/guides/automation-json.md (+8), scripts/cli-docs-test.mjs (+11/−2)

Issue

Refs OpenCoven#774

Issue OpenCoven#774 ("feat(cli): add progressive help disclosure and help contract") asks for three things: make default help concise, preserve all commands through a complete grouped view, and expose a deterministic JSON help contract. The executable side of that scope is already on main via OpenCoven#834 (concise curated coven --help, grouped coven help --all inventory, the coven help --all --json contract, scripts/export-cli-help-contract.mjs, and crates/coven-cli/tests/help_disclosure.rs), but the contract itself was documented nowhere, so automation had no stable field reference. This PR completes that remaining "expose" requirement. No Rust code changes are needed or included.

Implementation

  • Approach: add a "JSON help contract" section to docs/development/cli-core-functionality.md covering the schemaVersion: 1 payload shape, fixed group ordering, docsUrl constraints, byte-identical output guarantees, leak-free coverage, and the drift-fails-loudly rule enforced by crates/coven-cli/src/help.rs; surface the catalog to script authors in docs/guides/automation-json.md; extend scripts/cli-docs-test.mjs so the docs guard fails when the contract documentation regresses.
  • User-visible behavior: none at runtime; documentation and docs-guard only.
  • Compatibility notes: docs plus one test script; no runtime, API, or packaging changes. CI classification routes this to the npm/docs surface (no Rust lane).

Test plan

Ran locally (node v24, no Rust toolchain in the authoring environment):

  • node --test scripts/cli-docs-test.mjs (7 pass)
  • node --test scripts/export-cli-help-contract-test.mjs (8 pass)
  • node scripts/onboarding-docs-test.mjs
  • python scripts/check-secrets.py
  • python3 scripts/check-coven-privacy.py --staged (3 staged files)
  • git diff --check

Deferred to CI:

  • cargo fmt --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace --locked (exercises the untouched crates/coven-cli/tests/help_disclosure.rs)
  • npm onboarding smoke lanes (ubuntu/windows) that build the CLI and run scripts/test-cli-prepublish.mjs (which includes cli-docs-test.mjs and export-cli-help-contract-test.mjs)

Risk and Rollback

  • Risk level: low. Documentation and a test-guard extension only; no executable code paths change.
  • Rollback plan: revert the single commit.

Agent Handoff

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#774.

CI note: treated as a checkless PR per the CI contract: more than 10 minutes after opening, this PR head (8095b52) has zero check runs and zero workflow runs in CompleteDotTech/coven (Actions enabled on the fork, pull_request trigger present in .github/workflows/ci.yml, and the fork has no Actions run history at all). No CI verdict is claimed; the checked local checks above are the only executed validation, and the Rust compile proof remains deferred to the upstream re-target.

@CompleteDotTech CompleteDotTech self-assigned this Aug 30, 2026
@CompleteDotTech
CompleteDotTech marked this pull request as ready for review August 30, 2026 15:54
@CompleteDotTech CompleteDotTech mentioned this pull request Aug 30, 2026
Merged
10 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
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
CompleteDotTech force-pushed the agent/issue-774-feat-cli-add-progressive-help-disclosure branch from e73cfb9 to 4a488c5 Compare August 30, 2026 17:47
@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
CompleteDotTech force-pushed the agent/issue-774-feat-cli-add-progressive-help-disclosure branch from 4a488c5 to a7fc5ae Compare August 30, 2026 17:49
@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-774-feat-cli-add-progressive-help-disclosure branch from a7fc5ae to 8364106 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-774-feat-cli-add-progressive-help-disclosure branch from 8364106 to 329e5da 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-774-feat-cli-add-progressive-help-disclosure branch from 329e5da to d4e63b3 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-774-feat-cli-add-progressive-help-disclosure branch from d4e63b3 to fcec155 Compare August 30, 2026 18:15
CompleteDotTech and others added 2 commits August 30, 2026 14:25
@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
docs(cli): document the deterministic JSON help contract
df6574f 
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-774-feat-cli-add-progressive-help-disclosure branch from fcec155 to df6574f Compare August 30, 2026 18:26
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