torve 0.1.0__py3-none-any.whl

torve/AGENTS.md

@@ -0,0 +1,39 @@
+<!-- torve:managed src/torve — rendered from the corpus; do not edit by hand -->
+
+## Decisions governing `src/torve/`
+
+### S-0055/D-23 — `LOCKED` (Standing decisions)
+
+Five layers — `base`, `domain`, `application`, `adapters`, `cli`, beside `gates` and `config` — with import directions enforced by import-linter over the whole package; the `layering` gate blocks
+
+- Paths: `src/torve/**` `pyproject.toml`
+- Consequence: The hexagon is visible in the tree and mechanically held
+- Touching these paths owes a divergence entry: `torve log owed <task> --touched <files>` before you finish
+
+### S-0055/D-27 — `ASSUMED` (Standing decisions)
+
+No module is named `models`, `utils`, `helpers`, `common` or `base` below the package root; modules are named for what they hold, and the `source-layout` gate reads it
+
+- Paths: `src/torve/**`
+- Consequence: Names that admit anything accumulate everything
+
+### S-0055/D-59 — `ASSUMED` (Standing decisions)
+
+Strict typing is a floor over `src/`: `mypy --strict` and `basedpyright` strict block CI and the acceptance fallback; tests, scripts and skills carry no type floor
+
+- Paths: `src/torve/**` `pyproject.toml`
+- Consequence: A substrate surface change fails at the type check
+
+## Invariants holding over `src/torve/`
+
+- **S-0055/I-1**: The five layer contracts hold over the whole package
+  - Paths: `src/torve/**` `pyproject.toml`
+  - Check: `uv run lint-imports --config pyproject.toml`
+- **S-0055/I-4**: The typing floor over src holds
+  - Paths: `src/torve/**`
+  - Check: `uv run mypy src && uv run basedpyright src`
+- **S-0055/I-5**: The suite is green
+  - Paths: `src/torve/**` `tests/**`
+  - Check: `uv run pytest`
+
+<!-- /torve:managed -->

torve/__init__.py

@@ -0,0 +1,10 @@
+"""Torve — deterministic gates for agent and human pull requests.
+
+Names resolve from their canonical modules: `torve.gates.runner.run_gates`,
+`torve.domain.task.Task`, and so on. There is no re-export table — the
+gates-only CI path never imports the runner, the store or an adapter because
+nothing here imports them, not because a lazy front door defers them
+(S-0015/the-front-door, S-0015/A-2).
+"""
+
+__version__ = "0.1.0"

torve/_migrations/AGENTS.md

@@ -0,0 +1,12 @@
+<!-- torve:managed migrations — rendered from the corpus; do not edit by hand -->
+
+## Decisions governing `migrations/`
+
+### S-0055/D-43 — `ASSUMED` (Standing decisions)
+
+Migrations are owner-grouped, forward-only SQL under `migrations/`; the substrate is pinned by `FORZE_VERSION`, which `torve doctor` enforces and `config_hash` digests
+
+- Paths: `migrations/**` `src/torve/application/migrate.py` `src/torve/cli/doctor.py`
+- Consequence: A substrate surface change fails at the pin bump, not in production
+
+<!-- /torve:managed -->

torve/_migrations/substrate/FORZE_VERSION

@@ -0,0 +1 @@
+0.10.0

torve/_migrations/substrate/postgres/0001_durable.sql

@@ -0,0 +1,42 @@
+-- Substrate: durable run store + step journal (forze, schema per the
+-- adapter docstrings of PostgresDurableRunStore / the step adapter).
+-- Owner: substrate — this file changes when forze is upgraded, never for
+-- torve's own reasons (S-0012/D-1). Forward-only (S-0012/D-4).
+--
+-- Do not trim columns: every read projects cancel_requested_at /
+-- cancel_refused_at, and a missing column makes lease renewal raise, which a
+-- heartbeat reads as lease lost.
+
+CREATE TABLE IF NOT EXISTS public.torve_durable_run (
+    run_id text NOT NULL,
+    name text NOT NULL,
+    status text NOT NULL,
+    idempotency_key text,
+    input jsonb,
+    output jsonb,
+    error text,
+    tenant_id uuid,
+    attempts integer NOT NULL DEFAULT 0,
+    leased_until timestamptz,
+    available_at timestamptz,
+    created_at timestamptz NOT NULL,
+    updated_at timestamptz NOT NULL,
+    cancel_requested_at timestamptz,
+    cancel_refused_at timestamptz,
+    PRIMARY KEY (run_id),
+    UNIQUE (idempotency_key)
+);
+
+CREATE INDEX IF NOT EXISTS torve_durable_run_status_created
+    ON public.torve_durable_run (status, created_at);
+CREATE INDEX IF NOT EXISTS torve_durable_run_created_desc
+    ON public.torve_durable_run (created_at DESC, run_id DESC);
+
+CREATE TABLE IF NOT EXISTS public.torve_durable_step (
+    run_id text NOT NULL,
+    step_id text NOT NULL,
+    result jsonb NOT NULL,
+    tenant_id uuid,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (run_id, step_id)
+);

torve/_migrations/torve/postgres/0001_events.sql

@@ -0,0 +1,40 @@
+-- Torve: the event log (S-0044/the-event-log). Owner: torve — this file changes for
+-- torve's own reasons, never for a forze upgrade (S-0012/D-1). Forward-only
+-- (S-0012/D-4).
+--
+-- The relation backs the `torve-events` document spec, so every column name
+-- is a field name on the aggregate's models and the two must move together;
+-- `id`, `rev`, `created_at` and `last_update_at` come from the document base
+-- rather than from anything torve declared.
+--
+-- Append-only is a property of the spec above this table — it declares no
+-- update command, so the adapter exposes no update port — and `rev` is here
+-- because the document base carries it, not because a row is ever revised.
+-- A correction is another event.
+
+CREATE TABLE IF NOT EXISTS public.torve_event (
+    id               uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    rev              integer     NOT NULL DEFAULT 1,
+    created_at       timestamptz NOT NULL DEFAULT now(),
+    last_update_at   timestamptz NOT NULL DEFAULT now(),
+    schema_version   integer     NOT NULL DEFAULT 1,
+    kind             text        NOT NULL,
+    partition        text        NOT NULL,
+    subject_type     text        NOT NULL,
+    subject_id       text        NOT NULL,
+    actor_kind       text        NOT NULL,
+    actor_id         text        NOT NULL,
+    payload          jsonb       NOT NULL DEFAULT '{}'::jsonb,
+    correlation_id   text,
+    causation_id     text
+);
+
+-- The log's two reads (S-0044/ports-and-what-binds-first): one subject's history, and one
+-- partition's tail. Both order by (created_at, id) — the timestamp is not a
+-- total order under concurrency and the id is the stable tiebreak, so the
+-- index carries both or the sort spills.
+CREATE INDEX IF NOT EXISTS torve_event_subject
+    ON public.torve_event (subject_id, created_at, id);
+
+CREATE INDEX IF NOT EXISTS torve_event_partition
+    ON public.torve_event (partition, created_at, id);

torve/_migrations/torve/postgres/0002_decisions.sql

@@ -0,0 +1,16 @@
+-- Torve: the decision graph's read (S-0047/the-read-that-does-not-fold-an-execution-log, S-0047/D-7). Owner: torve —
+-- this file changes for torve's own reasons, never for a forze upgrade
+-- (S-0012/D-1). Forward-only (S-0012/D-4).
+--
+-- Sources and decisions grow with the corpus; attempts, gates and burn grow
+-- with execution. `torve_event_partition` serves the board, which wants a
+-- partition's whole tail; this one serves the decision graph, which wants
+-- the corpus-sized slice of it and would otherwise fold an execution log to
+-- find a few hundred rows.
+--
+-- Ordered by (created_at, id) for the same reason 0001 is: the timestamp is
+-- not a total order under concurrency and the id is the stable tiebreak, so
+-- the index carries both or the sort spills.
+
+CREATE INDEX IF NOT EXISTS torve_event_subject_type
+    ON public.torve_event (partition, subject_type, created_at, id);

torve/_migrations/torve/postgres/README.md

@@ -0,0 +1,4 @@
+# Torve document tables (tasks_ref, attempts, gate_results, findings,
+# review_feedback) arrive with the attempts store; this history starts at the
+# first table. Creating the directory early keeps `torve migrate torve` a
+# stable no-op rather than an unknown target (S-0012/D-6).

torve/_skills/AGENTS.md

@@ -0,0 +1,50 @@
+<!-- torve:managed skills — rendered from the corpus; do not edit by hand -->
+
+## Decisions governing `skills/`
+
+### S-0055/D-36 — `ASSUMED` (Standing decisions)
+
+Skills ship as package data under `skills/` and are materialised role-scoped into the sandbox; a vendored skill lives under `.torve/skills-vendor/`; a name in both refuses, a name in neither is a configuration error
+
+- Paths: `skills/**` `.torve/skills-vendor/**` `src/torve/application/skills.py`
+- Consequence: What an agent knows is versioned and named, never ambient
+
+### S-0056/D-8 — `ASSUMED` (Structure for everything) — implementation: none
+
+`SKILL.md`, `AGENTS.md`, the colocated sections and the pack are unchanged: projections rendered from the model, read by harnesses and people
+
+- Paths: `skills/**` `src/torve/application/colocation.py`
+- Consequence: Nothing a harness reads changes shape
+
+### S-0057/D-4 — `LOCKED` (The specification is a directory)
+
+`torve spec` absorbs every `torve rfc` verb and `cli/rfc.py` is deleted; the gate is `spec-valid`; the skill is `spec-writer`; `rfc_emit.py` becomes `spec_emit.py`; new prose says specification or document
+
+- Paths: `src/torve/cli/spec.py` `src/torve/cli/spec.py` `src/torve/config/spec_emit.py` `skills/**` `.torve/gates.yaml`
+- Consequence: One namespace for the corpus; old prose and test file names keep the old word
+- Touching these paths owes a divergence entry: `torve log owed <task> --touched <files>` before you finish
+
+### S-0058/D-2 — `LOCKED` (One grammar and the anatomy)
+
+Every existing identifier converts once through a mapping committed as `.torve/archive/identifiers.yaml`, applied to the corpus, the archive, `src/`, `pages/`, `skills/`, the README, the local task files and the projections, with "RFC NNNN §n" converted to the section key at that position; a parity script gates the commit and is not committed
+
+- Paths: `.torve/specs/**` `.torve/archive/**` `src/**` `pages/**` `skills/**` `README.md`
+- Consequence: No legacy identifier stands anywhere the check reads; history keeps its words and resolves through the mapping
+- Touching these paths owes a divergence entry: `torve log owed <task> --touched <files>` before you finish
+
+### S-0058/D-10 — `ASSUMED` (One grammar and the anatomy)
+
+The skill and its template, the schemas `torve init` writes, the projections beside the code and the operating page follow the grammar and the anatomy in the same phase that changes them
+
+- Paths: `skills/**` `src/torve/application/colocation.py` `src/torve/cli/init.py` `pages/docs/operating.md`
+- Consequence: Nothing a harness or a person reads names an identifier the check refuses
+
+### S-0062/D-6 — `LOCKED` (Equipment is declared, and the harness is told how to take it)
+
+A skill a gate reads stays package data, versioned with the engine; `torve:` is the source that names one.
+
+- Paths: `src/torve/application/skills.py` `skills/**`
+- Consequence: the two skills this engine ships cannot drift against the gate that parses what they teach
+- Touching these paths owes a divergence entry: `torve log owed <task> --touched <files>` before you finish
+
+<!-- /torve:managed -->

torve/_skills/corpus-bootstrap/AGENTS.md

@@ -0,0 +1,3 @@
+<!-- torve:managed skills/corpus-bootstrap — rendered from the corpus; do not edit by hand -->
+
+<!-- /torve:managed -->

torve/_skills/corpus-bootstrap/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: corpus-bootstrap
+description: Drafting a brownfield adopter's standing-decisions baseline from the survey report — mostly ASSUMED, LOCKED only on defended boundaries, paths on every row, no phasing, one draft document for a human to edit, commit and accept.
+roles: [author]
+gate: spec-valid
+---
+
+> **Specialisation.** Derived from `agent-skills/corpus-bootstrap`, specialised for
+> artefacts that Torve parses. Divergence from upstream is expected and
+> intentional — **do not reconcile**. Improvements of general value flow
+> upstream, not the reverse.
+
+# Corpus Bootstrap — the baseline draft
+
+This skill is the second half of first contact with a repository that has no
+corpus. The engine's `torve survey` did the first half: it replayed the last
+landings through the gate battery and produced a read-only report of what
+would have fired and what stayed silent for want of a corpus. This skill —
+run in a supervised session, **never by the engine** — reads that report and
+the repository, and drafts the standing-decisions document that turns the
+report's silence into governance.
+
+The engine never reads this skill's output while it is a draft. It only ever
+reads the committed, human-accepted document, through the standing
+inheritance layer: from acceptance, every row whose declared paths intersect
+a contract's scope rides into that contract at mint time, and nothing else
+(S-0031/D-2). There is no engine surface for the baseline at all — which is the
+point: a skill can be supervised, edited and refused in a diff; an engine
+surface would drift.
+
+## Inputs and output
+
+- **Input:** the survey report (the JSON `torve survey --format json`
+  writes) and the repository working tree. The report is the evidence base;
+  the tree is where the boundaries live and where their globs are read from.
+- **Output:** one draft document in this corpus's format — frontmatter, an
+  H1, a Decisions section holding the decision table, no Phasing section —
+  written so a human can edit, commit and accept it in one review. The draft
+  is `status: draft`; acceptance is the human flipping it to `accepted` in
+  the same commit that signs it.
+
+## The extraction doctrine
+
+Four rules, in order of how much damage breaking them does:
+
+1. **Mostly ASSUMED.** A grade is a human judgement about reversal cost, and
+   a stranger's repository has no corpus — nobody has made that judgement.
+   Default every candidate row to `ASSUMED` and let the human's acceptance
+   edits do the real grading. An extraction that comes back mostly `LOCKED`
+   poisons the entry: the acceptance review reads it as a takeover and
+   refuses the whole document.
+
+2. **LOCKED only on defended boundaries.** A `LOCKED` row claims reopening is
+   expensive. The only evidence an extraction can cite for that is the
+   repository's own history showing the boundary being **defended**: a
+   firing followed by a correction landing, or a consistent clean record
+   with the boundary visible in the tree (the layout is deliberate because
+   the history holds it). A single firing in a short window is
+   `ASSUMED`-grade evidence — the boundary exists as a check, but nobody has
+   been shown defending it.
+
+3. **Paths on every row.** A row without declared paths is never standing —
+   the inheritance layer skips it and the row governs nothing. Every row
+   names the globs it governs, read from the actual tree, not invented.
+
+4. **No phasing.** The baseline is a set of standing rows, not work to
+   sequence. A Phasing section would make the engine mint tasks from a
+   baseline document — exactly the engine surface S-0031/D-2 refuses. The
+   baseline answers "how is this repository governed"; sequencing is another
+   document's job, and the draft has no `## Phasing` section.
+
+## Reading the survey
+
+The report is the evidence base; read it before the tree.
+
+- **Fired** (`outcome` in `fail`/`error`/`bypassed`) — a boundary was
+  crossed in history. Name the landing, then go to the tree: was the
+  crossing corrected later? That correction is the defended-boundary
+  evidence rule 2 wants.
+- **Clean** (`pass`/`flaky`) — measured nothing wrong. No row follows from a
+  clean gate alone; the boundary it measures is already being held.
+- **Skipped with `no_corpus: true`** — the gate did not run because no task
+  contract existed: the corpus's absence made visible. These are the rows
+  the baseline exists to write: a standing row that gives the gate
+  something to measure once work is minted.
+- **Skipped with `no_corpus: false`** — the runner's fail-fast "not run"
+  after an earlier blocking gate fired, or acceptance's structural no-commands
+  skip. Not a corpus gap; no row follows.
+- **The summary's `corpus_adds`** — the gates that never measured a single
+  landing and whose silence is the no-task skip. The report already names
+  them; every one of them becomes a candidate `ASSUMED` row.
+
+## The shape this skill records (S-0031/D-6)
+
+The baseline is **one document per adoption**, named
+the `S-NNNN/` directory in the corpus path (`.torve/specs/` by default),
+with `NNNN` the next free corpus number and the title "Standing decisions".
+Rationale: a first adopter has no areas taxonomy to split by, a single
+document keeps the acceptance ceremony to one commit, and the inheritance
+layer already selects rows by path intersection — several-by-area buys
+nothing until a corpus has enough rows to need it. The first real adoption
+settles this shape; this paragraph is the skill recording the shape it
+chose, and the recording is updated to what the adoption chose.
+
+## The hand-off
+
+The extraction produces a **draft**. The human then:
+
+1. Edits — grading, wording, the paths, anything the history suggests.
+2. Commits — the draft becomes a committed document.
+3. Accepts — `status: accepted`, the commit that makes the rows stand.
+
+Nothing the engine reads exists before that commit, and nothing the engine
+reads after it is this skill's doing: standing inheritance copies grade and
+paths at mint time and the battery convicts only work minted after — a
+ratchet, never a purge (S-0031/D-3).
+
+## References
+
+- `references/doctrine.md` — the extraction doctrine in detail: grading
+  evidence, path discipline, what the survey's four outcomes mean
+- `references/workflow.md` — the supervised-session procedure, inputs to
+  accepted document
+- `references/draft-template.md` — the corpus-format skeleton the draft is
+  written from
+- `fixtures/survey-report.json` — a sample survey report (input)
+- `fixtures/S-0001/` — the checkable output shape: the draft
+  the doctrine produces from the sample report

torve/_skills/corpus-bootstrap/fixtures/S-0001/decisions.yaml

@@ -0,0 +1,45 @@
+# yaml-language-server: $schema=../../schemas/decisions.json
+decisions:
+  - id: D-1
+    grade: LOCKED
+    text: >-
+      Credentials never enter the source tree; secrets are injected from the deployment
+      environment
+    paths: [src/**, .env.example]
+    consequence: >-
+      The repository's history defended this boundary: the survey's secrets gate fired
+      when a key landed in `src/leak.py` and the next landing removed it; crossing
+      it again is expensive to undo
+  - id: D-2
+    grade: ASSUMED
+    text: >-
+      Product code lives under `src/**`; operational scripts live under `scripts/**`
+    paths: [src/**, scripts/**]
+    consequence: >-
+      The survey's scope gate fired once on a root-level deploy script and stayed
+      clean on the other four landings; whether the layout is deliberate is the acceptance
+      edit's call
+  - id: D-3
+    grade: ASSUMED
+    text: >-
+      Test files are edited only under a task's licence; adding a test is an addition,
+      editing one needs scope
+    paths: [tests/**]
+    consequence: >-
+      The no-test-tampering gate never measured a single landing — no task existed
+      — so this row gives the gate a spec once work is minted
+  - id: D-4
+    grade: ASSUMED
+    text: >-
+      Work touching governed areas records its decisions in the task log
+    paths: [.torve/tasks/**, logs/**]
+    consequence: >-
+      The decisions-reported gate never measured a landing; this row is the corpus
+      layer that turns its no-task skip into something that can fire
+  - id: D-5
+    grade: ASSUMED
+    text: Execution logs carry the declared drift count
+    paths: [.torve/tasks/**, logs/**]
+    consequence: >-
+      The self-audit gate never measured a landing; this row names the log discipline
+      the gate reads

torve/_skills/corpus-bootstrap/fixtures/S-0001/document.yaml

@@ -0,0 +1,56 @@
+# yaml-language-server: $schema=../../schemas/document.json
+id: S-0001
+title: Standing decisions
+kind: design
+status: draft
+implementation: none
+depends_on: []
+informed_by: []
+supersedes: []
+superseded_by: null
+owner: <adopter>
+schema_version: 4
+summary: |-
+  The survey found two crossed boundaries and three gates that never measured
+  a single landing. The secrets boundary was defended: a key landed in
+  `src/leak.py` and the next landing removed it, so that row stands `LOCKED`.
+  The source-layout boundary was crossed once and left uncorrected in the
+  window, so its row stands `ASSUMED`. The three gates that never measured
+  anything for want of a corpus — test licensing, decision recording, and the
+  self-audit log — each get an `ASSUMED` row that gives them something to
+  measure once work is minted.
+motivation: ''
+current_state: ''
+goals: ''
+non_goals: ''
+design:
+  - key: the-survey-findings
+    md: |-
+      - **`secrets` fired** on landing `f901a7b` ("chore: wire stripe
+        credentials"): a new file `src/leak.py` carried an access key. Landing `d55fecb`
+        ("fix: rotate credentials out of the tree") deleted the file and added a
+        `.env.example` placeholder, and measured clean — the boundary was
+        defended in the window.
+      - **`scope` fired** on landing `8ef5b12` ("chore: deployment script at
+        repository root"): `scripts/deploy.sh` landed outside the manifest's
+        `src/**` and `.env.example` allow. No later landing corrected it in the
+        window, and the tree's `src/` home for product code holds across the
+        other four landings.
+      - **`no-test-tampering`, `decisions-reported`, `self-audit` skipped every
+        landing** with the no-task skip: no contract has ever existed in this
+        repository, so nothing gave them a spec to check against. The survey's
+        `corpus_adds` names exactly these three — the corpus's absence made
+        visible.
+  - key: decisions
+    md: |-
+      | # | Grade | Decision | Paths | Consequence |
+      | --- | --- | --- | --- | --- |
+      | S-0001/D-1 | `LOCKED` | Credentials never enter the source tree; secrets are injected from the deployment environment | `src/**` `.env.example` | The repository's history defended this boundary: the survey's secrets gate fired when a key landed in `src/leak.py` and the next landing removed it; crossing it again is expensive to undo |
+      | S-0001/D-2 | `ASSUMED` | Product code lives under `src/**`; operational scripts live under `scripts/**` | `src/**` `scripts/**` | The survey's scope gate fired once on a root-level deploy script and stayed clean on the other four landings; whether the layout is deliberate is the acceptance edit's call |
+      | S-0001/D-3 | `ASSUMED` | Test files are edited only under a task's licence; adding a test is an addition, editing one needs scope | `tests/**` | The no-test-tampering gate never measured a single landing — no task existed — so this row gives the gate a spec once work is minted |
+      | S-0001/D-4 | `ASSUMED` | Work touching governed areas records its decisions in the task log | `.torve/tasks/**` `logs/**` | The decisions-reported gate never measured a landing; this row is the corpus layer that turns its no-task skip into something that can fire |
+      | S-0001/D-5 | `ASSUMED` | Execution logs carry the declared drift count | `.torve/tasks/**` `logs/**` | The self-audit gate never measured a landing; this row names the log discipline the gate reads |
+tests: ''
+docs: ''
+out_of_scope: ''
+risks: ''