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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,36 @@ bash scripts/agent-check.sh full

Follow `AGENTS.md` for authority-impact evidence, downstream acceptance, and the applicable contribution workflow.

These commands validate local repository contracts and the portable automation
profile; they do not launch a Coven daemon. Required current-checkout
compatibility and the scheduled canary remain work under #31. Use the
[delivery strategy](docs/strategy.md) for sequencing and owner-specific
acceptance rather than repeating a completed historical plan.

## Solo-maintainer merge policy

You can land an approved change without inventing a second reviewer. The
maintainer [authorized this policy](https://github.com/OpenCoven/coven-threads/issues/31#issuecomment-5642501227)
for the solo-maintainer repository on 2026-09-12 (UTC).

Use a pull request, record the human approval and its scope on GitHub, resolve
review conversations with their actual disposition, and satisfy the required
checks against an up-to-date branch before merging. Agents need explicit human
authorization; a passing check, model review, or persona is not approval.
Material changes outside the approved scope need renewed authorization.

Ruleset `22910327` requires no approving review and disables latest-push and
extra unattributed-change approvals. It retains pull requests, resolved review
threads, stale-review dismissal, four strict required GitHub Actions checks,
and deletion/non-fast-forward protection, with no bypass actors. GitHub
enforces those controls, but does not enforce the conversational human-approval
process or provide independent review.

See the [governance ledger](docs/phases.md#repository-governance-baseline-active-boundary-enforcement-outstanding)
for exact checks and rollback. Reassess independent review when another
maintainer joins. This repository merge policy does not change protected-write
authority or waive the design gates below.

## Design gates

The Phase-0 design freeze is complete. Phase-5 remediation, Nova's independent coherence review, and Val's freeze remain outstanding. Agents may prepare evidence; they cannot replace either human decision.
16 changes: 11 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# coven-threads

**Status (2026-09-09):** Engineering phases 0–4 are **frozen**. Phase 5 is **active**, with four unresolved implementation blockers and independent Nova/Val gates still outstanding. Coven `v0.4.3` includes the earlier daemon integration and pins Threads to `c102844`; release ancestry does not prove full Phase-5 conformance or current-checkout compatibility. See [the delivery ledger](docs/phases.md) for evidence, draft fixes, and the real-daemon work graph.
**License:** stated as Apache-2.0 (planned) in the design doc; the committed `LICENSE` file is currently MIT — a known discrepancy pending reconciliation (see `docs/STATUS-2026-07-15.md` §6).
**Status (2026-09-11):** Engineering phases 0–4 remain **frozen**. Phase 5 is **active**, with four unresolved remediation gates and independent Nova/Val decisions outstanding. Baseline protection now enforces reviews and four existing checks on `main`; required pinned-daemon acceptance is still missing. Coven `v0.4.3` includes the earlier integration, not proof of full Phase-5 conformance. Start with the [delivery strategy](docs/strategy.md), [evidence ledger](docs/phases.md), and [readiness review](docs/reviews/2026-09-11-landscape-and-readiness.md).
**License:** the committed `LICENSE` and Cargo package metadata specify MIT. The frozen design retains an older Apache-2.0 plan; reconciling that historical text requires a maintainer decision, not an inferred license change.
**Owners (design phase):** Sage 🌿 + Echo 🔮 co-drive; Nova 👑 + Sage on lane assignments; Cody ⚡ Phase 1+ crate lane

---

## What this is

`coven-threads` is OpenCoven's **authority-boundary gate layer**: the external, structural enforcement contract that sits *above* the `coven` Rust daemon's untrusted-client boundary, and *underneath* every familiar's protected memory surface.
`coven-threads` is OpenCoven's **protected-authority validator**, imported inside the trusted `coven` daemon. Threads defines typed validation contracts; the daemon owns authentication, protected writes, persistence, and recovery.

In the vocabulary of the Familiar Contract (RFC-0001) and the Ward v0.2 spec: this is the *gate-shaped receiver* on which Ward's four validation gates sit. Ward specifies **what** the gates check; `coven-threads` specifies **how** they are enforced, by an authority outside familiar cooperation.

Expand All @@ -30,6 +30,8 @@ User-facing docs live in [`docs/`](docs/README.md):
- [Automation Authority Profile](docs/automation-authority-profile.md) — operation-specific permit / approval / proposal / reject decisions, replay-safe approval evidence, and portable vectors.
- [Channels and strands](docs/channels-and-strands.md) — the four channels, the five strand kinds, WARD-C1–C7.
- [Phases](docs/phases.md) — what is frozen, what is implemented, what is active, what is blocked.
- [Delivery strategy](docs/strategy.md): ordered workstreams, owners, acceptance evidence, and release gates.
- [Readiness review](docs/reviews/2026-09-11-landscape-and-readiness.md): the dated documentation audit and engineering recommendations for #13, #31, #40, and #46.
- [FAQ](docs/faq.md) · [Glossary](docs/glossary.md)

The frozen design doc is [`specs/PHASE-0-DESIGN.md`](specs/PHASE-0-DESIGN.md); the docs describe it and never amend it.
Expand All @@ -52,7 +54,11 @@ replace its trust boundary or own filesystem and persistence effects. The
remaining work is complete route, predicate, and replay enforcement, not the
absence of any integration.

![The shipped Phase 2 enforcement flow: client request through Ward::evaluate, blocked proposals refused as a unit, the coven-threads gate validating each protected target fail-closed, and the three verdicts — Reject (403), DegradeToProposal (staged at ~/.coven/pending/), Permit (Ward::apply) — with every verdict appended to the append-only ward_audit table](docs/diagrams/enforcement.png)
![Historical Phase-2 enforcement flow, not current protected-proposal acceptance](docs/diagrams/enforcement.png)

This historical diagram includes a staging branch that must not be read as
protected-write authority. The current contract rejects proposals touching
protected surfaces; see the [authority model](docs/authority-model.md).

## The weaving metaphor

Expand Down Expand Up @@ -96,7 +102,7 @@ Honest labels; the detailed ledger is [docs/phases.md](docs/phases.md).
## Anti-goals

- **Not a general-purpose policy engine.** This is a *typed* authority layer for OpenCoven familiar surfaces. Reusability is a nice-to-have; typed correctness is the goal.
- **Not a runtime-portability format.** That's Phase 3's job. Phase 0 is enforcement design, not export.
- **Not a runtime implementation.** Threads owns the `.weave` portability contract and lossy one-way `.af` export. Coven owns runtime adoption and effects; an imported artifact grants no authority by itself.
- **Not `.af`-compatible.** Documented divergence, source-verified 2026-07-14: Letta's `CoreMemoryBlockSchema` has no protection field and runtime `read_only` is stripped at export — silent downgrade on import is exactly what WARD-C7 refuses. See [docs/faq.md](docs/faq.md#why-isnt-it-af-compatible).

## Related
Expand Down
28 changes: 14 additions & 14 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,19 +27,18 @@ pull requests and pushes to `main`. It needs no private stores, Beads database,
credentials, or downstream checkout. Third-party Actions retain immutable
commit pins and the existing explicit Rust toolchain parity checks.

**Separate privacy rollout (#39, #40):** the `Privacy policy guard` job runs on
**Separate privacy rollout (#39, #40; 2026-09-12 UTC):** the `Privacy policy guard` job runs on
pull requests and pushes to `main`, separately from secret scanning. The
maintainer-approved correction to the historical Phase-5 source reference
preserves provenance
without retaining the private runtime location; it changes no normative
authority decision and adds no scanner exemption.
preserves provenance without retaining the private runtime location; it changes
no normative authority decision and adds no scanner exemption.

Both guards passed at candidate `2a12c1ad6f813b636f49f1c17bbd3ff7cb65aaee`
in [CI run 34610860329](https://github.com/OpenCoven/coven-threads/actions/runs/34610860329).
That is evidence for the named revision, not every subsequent head. The landed
`Secret scanning` job remains unchanged. Privacy is not a required branch
check; activation requires a separate maintainer decision. Landing the job
does not change the ruleset.
#40 merged at `7168dae10f6b59bad8bc653b95f51911334ded74`, after
[combined-head CI](https://github.com/OpenCoven/coven-threads/actions/runs/34664678160)
passed at `2d17d0d4583801b1dfa831c7ca40a03930ceef80`. The correction and privacy
job are now on `main`. Privacy is not a required branch check; activation
requires a separate maintainer decision. The existing `Secret scanning` job
and required-check contexts are unchanged.

From the repository root:

Expand Down Expand Up @@ -97,10 +96,11 @@ not certify daemon authority, deployed behavior, branch protection, or human
review. Pull-request code can modify CI, so maintainer review and required-check
policy remain separate controls.

"Independent" means a separate privacy job, not an immutable checker that
PR authors cannot modify. A stronger enforcement policy must also govern the
calling workflow. Do not execute untrusted PR code in a privileged workflow
context as a shortcut.
"Independent" describes a separate privacy job, not a checker that PR authors
cannot modify. An immutable enforcement design must also govern the calling
workflow. Do not execute untrusted PR code in a privileged workflow context
as a shortcut. Current repository CI does not prove daemon authority or
current-checkout downstream compatibility; see the [delivery strategy](docs/strategy.md).

Policy provenance: adapted the categories and separate default-secret scan
from `OpenCoven/coven-memory` at
Expand Down
25 changes: 23 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,24 @@ findings.

If you are new here, read [concepts.md](concepts.md) first. Everything else assumes its vocabulary.

## Current status (2026-09-09)
## Current status (2026-09-12 UTC)

- **Phase 0 (design) — `[FROZEN]`.** The design doc `specs/PHASE-0-DESIGN.md` is frozen at v0.2 (2026-07-14, tag `v0.2-phase0-design`), with Nova sign-off and an RFC-0001 §5 round-trip verified.
- **Phases 1–2: `[FROZEN; IN RELEASE TAG]`; Phase 3: `[ENGINEERING FROZEN]`.** Coven `v0.4.3` includes the daemon integration and pins Threads to `c102844`. This is release-source provenance, not verification of deployed configuration or current-checkout compatibility. Phase 3 retains the decided `.weave` envelope and lossy one-way `.af` export semantics.
- **Phase 4: `[FROZEN]` (2026-07-17).** The four Cave surfaces and their recorded human gates are complete under `threads-986.17`. The daemon-adapter follow-up `threads-v3g` and degraded-familiar follow-up `threads-k9s` are closed. See the delivery ledger for merge evidence.
- **Phase 5: `[ACTIVE]`.** The earlier core, scheduler, Cave contract (`.7`), and RFC alignment (`.12`) implementation beads are closed. Four daemon-boundary blockers still prevent coherence sign-off. The shared harness and protected/terminal fixes are draft checkpoints, and neither Nova's review nor Val's freeze can be replaced by agent evidence. See [phases.md](phases.md) for the work graph and [the E2E contract](testing/e2e-contract.md) for closure requirements.

These docs describe the **frozen design**. Where implemented code goes beyond or refines the design, that is labeled explicitly. See [phases.md](phases.md) for the full breakdown.
Baseline `main` protection is active under the
[authorized solo-maintainer policy](../CONTRIBUTING.md#solo-maintainer-merge-policy).
The separate privacy job has landed, but is not a required check. The required
pinned-daemon check and scheduled canary are not wired. The Automation Authority Profile v1 is a
separate shipped schema/reference-validator contract, not evidence of daemon
adoption or a replacement for the Rust gate.

These docs describe frozen and active contracts without amending them. Use the
[delivery strategy](strategy.md) for sequencing, the [ledger](phases.md) for
delivery evidence, and the [dated readiness review](reviews/2026-09-11-landscape-and-readiness.md)
for findings and remaining acceptance obligations.

## Who this is for

Expand All @@ -33,6 +43,9 @@ These docs describe the **frozen design**. Where implemented code goes beyond or
| [automation-authority-profile.md](automation-authority-profile.md) | Operation-specific automation authority, approvals, proposal-only downgrade, replay/TOCTOU, privacy, and portable vectors. |
| [channels-and-strands.md](channels-and-strands.md) | The four channels of load, the five strand types, which strands each channel structurally requires, WARD-C1–C7. |
| [phases.md](phases.md) | Phase 0 → 5 with honest status labels: what is frozen, what is implemented, what is active, what is blocked. |
| [strategy.md](strategy.md) | Workstream order, canonical owners, closure evidence, and release prerequisites. GitHub issues and Beads retain task status. |
| [Readiness review](reviews/2026-09-11-landscape-and-readiness.md) | Dated landscape, documentation corrections, and engineering recommendations for the open review gates. |
| [E2E contract](testing/e2e-contract.md) | Real-daemon topology, eight required journeys, deterministic time, and blocker-closure evidence. |
| [faq.md](faq.md) | Anticipated questions, answered honestly with sources. |
| [glossary.md](glossary.md) | Every named term, one line each, alphabetical, with links to depth. |

Expand All @@ -50,3 +63,11 @@ WARD-C1–C7. `coven/docs/SAFETY-MODEL.md` describes the daemon boundary; it doe
not replace the source precedence above.

Diagrams in `diagrams/` are legibility aids derived from the design doc; they are not authoritative (see `diagrams/README.md`).

## Historical plans and reports

The [July status report](STATUS-2026-07-15.md), [ApplyAudit design](superpowers/specs/2026-07-19-apply-audit-migration-repair-design.md),
and [ApplyAudit implementation plan](superpowers/plans/2026-07-19-apply-audit-migration-repair.md)
preserve earlier checkpoints. Do not execute their completed tasks or treat
their old counts as current acceptance. Rendered diagrams, the PDF, and slides
are explanatory snapshots, not release evidence.
15 changes: 11 additions & 4 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Architecture

> Status: the enforcement flow on this page is `[DESIGNED]` (frozen, `specs/PHASE-0-DESIGN.md` §5) with the crate implementation in `coven-threads-core` and the daemon-side call site **merged to coven `main`** (PR https://github.com/OpenCoven/coven/pull/382, 2026-07-15). Daemons built from coven `main` route tier-0 protected-surface edits through this flow.
> Status: the Phase-0 contract is frozen, and the original daemon call site merged through OpenCoven/coven#382. The required flow below is not certification of every current route. Four Phase-5 remediation gates remain open; consult the [delivery ledger](phases.md).

Vocabulary reminder (bound in full in [concepts.md](concepts.md)): a **Thread** is an authority relationship *surface → writer*; a **Weave** is the enforced pattern of threads across a familiar; a **Strand** is a fiber inside a thread (hash, signature, manifest entry, audit trail, serialization marker); a **Channel** is the axis of load a thread must hold under.

Expand All @@ -20,7 +20,7 @@ The daemon imports Threads to validate requests against the typed authority stat

Two structural facts follow from this placement:

1. **`coven-threads` is a crate, not a service.** It is imported into the daemon and reachable *only* by the privileged daemon process — never by a familiar-controlled process. There is no socket to coven-threads, no separate process to restart, no config file a familiar could edit. This is how the layer satisfies RFC-0001 §5.1's three MUST-NOTs (a familiar must not modify the Ward file, must not restart the authority process, must not bypass gates): there is nothing familiar-reachable *to* modify, restart, or bypass.
1. **`coven-threads` is a crate, not a service.** Any program can call the public library, but a client-side result grants no authority. Only the trusted daemon's validation of authoritative inputs can govern its effects. There is no separate Threads socket or process. RFC-0001 §5.1's separation requirements depend on daemon authentication and deployment isolation, not on hiding the crate from familiar-controlled code.
2. **The wire format does not change.** Clients speak the same socket protocol before and after integration. The only client-visible difference (Phase 2) is a new possible outcome on mutation requests: `DegradeToProposal`.

## Relationship to RFC-0001 and to Ward
Expand All @@ -38,7 +38,7 @@ The design doc's framing: the boundary (§5.1) was spec'd and the daemon existed

![Enforcement flow](diagrams/enforcement.png)

*Client → daemon → coven-threads validator → weave load → strand check under channel → Permit / DegradeToProposal / Reject → `ward.audit`.*
*Historical Phase-2 diagram. Its staging branch is not permission to stage or approve protected targets. The steps below state the current required contract.*

The flow, step by step (design doc §5):

Expand Down Expand Up @@ -79,7 +79,7 @@ The placement rule from the top of this page carries straight through. `coven-th
- **`ProposalClassification`** — the append-only record produced at intake: the channel the mutation arrived on, affected surfaces and semantic regions, the floor path tier, the required approval path (highest ceremony of everything touched wins, all-or-nothing — matching existing Ward behavior), and the **`evidence_replay_hash`** committing to the gate evidence evaluated at classification.
- **`WindowCloseReason`** and the audit-detail shapes for the lifecycle rows below.

The **daemon** owns proposal classification and the delayed-apply scheduler — both landed in the coven daemon (PR #430, bead `threads-uqx.6`). This crate does not ship a scheduler; it defines the record the scheduler must honor.
The **daemon** owns proposal classification and the delayed-apply scheduler, initially merged through OpenCoven/coven#430 (`threads-uqx.6`). This crate defines the record the scheduler must honor. Initial delivery does not close the later route, identity, terminal, and recovery findings.

### The delayed-apply flow

Expand All @@ -98,6 +98,13 @@ The flow (spec decision 2 — delayed apply *only*):

`AutoRegression { veto: None }` has no veto period. `HumanApproval` and `HumanApprovalWithRationale` wait for explicit approval rather than a veto-window deadline. These non-windowed paths still require final live revalidation. The flow above describes the required contract, not proof that every daemon route currently satisfies it.

The [2026-09-11 readiness review](reviews/2026-09-11-landscape-and-readiness.md#phase-5-engineering-review)
identifies two specific acceptance gaps at the inspected draft: its supported
scheduled producer cannot produce `AutoRegression` with the built-in region
floors, and the diff/region replay hash does not itself bind identity
predicate evidence at classification. Later live checks and final-commit
binding do not, by themselves, close those obligations.

There is **no provisional apply, ever**: the daemon never applies first and rolls back on veto. And Gate 4 keeps its fail-closed posture unweakened — every path, windowed or not, ends in live daemon re-materialization before apply.

One conflation to refuse, because it was a HIGH finding in the independent coherence review: **Channel and ApprovalPath are orthogonal axes**, both first-class. Channel remains the frozen Phase-0 load/enforcement axis; ApprovalPath is the promotion ceremony; **never derive ApprovalPath from Channel** (spec decision 1). The binding is spelled out in [concepts.md](concepts.md#channel-vs-approvalpath-two-orthogonal-axes).
Expand Down
Loading
Loading