@descent-vtt/spec-harness 0.0.0 → 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "spec-tools",
+  "owner": {
+    "name": "DescentVTT",
+    "url": "https://github.com/DescentVTT"
+  },
+  "description": "The spec-* tools for agents: briefs, guards, audits and rulings.",
+  "plugins": [
+    {
+      "name": "spec-harness",
+      "source": "./",
+      "description": "Rounds of agent work under a brief.",
+      "version": "0.1.0"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "spec-harness",
+  "version": "0.1.0",
+  "description": "Rounds of agent work under a brief: context, a guard on every write, escalations a person signs, an audit at the end. Needs @descent-vtt/spec-harness and @descent-vtt/spec-brief 0.2.0 or later installed in the project.",
+  "author": {
+    "name": "DescentVTT",
+    "url": "https://github.com/DescentVTT"
+  },
+  "homepage": "https://github.com/DescentVTT/spec-harness",
+  "license": "MIT",
+  "keywords": [
+    "brief",
+    "guardrails",
+    "spec",
+    "agents"
+  ]
+}

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "spec-harness": {
+      "command": "npx",
+      "args": [
+        "--no-install",
+        "spec-harness",
+        "mcp"
+      ]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.1.0
+
+The first release of spec-harness, the agent-facing member of the spec-*
+tools: what an agent needs to start a round of work under a brief a person
+approved, a guard on every write, escalations a person rules on and signs, an
+audit when the round ends, and probes that prove a defect before it is filed.
+It calls no model and has no runtime dependencies. It needs spec-brief 0.2.0
+or later, and uses spec-guard 0.12.0 and spec-graph 0.9.0 or later when they
+are installed; an older one is reported with its minimum and never run.
+
+This version was staged on npm by CI from its tag, with provenance, and
+released by a maintainer with a second factor. 0.0.0 on npm is a placeholder
+without code, published by hand to claim the name, and is deprecated
+([ADR-0011](docs/adr/0011-releases-are-staged-by-ci.md)).
+
+### Added
+
+- `context`: the brief in full, its scope as the guard reads it, signed
+  rulings, dependencies, the rules spec-guard holds the scope to, and the
+  documents the brief cites, within a budget.
+- `guard` and `hook claude` / `hook git`: protected files refused unless a
+  signed ruling allows them, writes outside the scope warned, asked about or
+  refused; paths compared as the filesystem spells them.
+- `escalate`, `rule`, `rulings`: requests kept outside the work tree; a ruling
+  is a row in the brief that counts when the commit that last changed it is
+  signed by a key the base branch's allowed signers list.
+- `audit`: what spec-brief's archive would say, the brief's goals and
+  premises through spec-guard, unverified rulings, and dependencies added.
+- `probe`: a brief's declared probes run in temporary worktrees, red at the
+  base for the declared reason and green at the head.
+- `premises`: every live brief's premises run through spec-guard, and one
+  that no longer holds reported as `stale-premise`, exit 1, for CI.
+- `init`: the family configured to agree; a plan until `--write`.
+- `doctor`: which siblings are installed, at which versions, and which brief
+  is named. The minimums are `peerDependencies` too: spec-brief required,
+  spec-graph and spec-guard optional.
+- `mcp`: start_round, check_path, request_escalation, audit_round and
+  list_rounds, with the workflow prompts, over both MCP protocol eras.
+- Skills for Claude Code and other Agent Skills readers: draft-brief,
+  split-goal, run-round, close-round; the repository is also a Claude Code
+  plugin marketplace.
+- spec-core at cbe2223, vendored with its licence, which the package ships.
+  A scope that writes `**` inside a name (`docs/**.md`) is refused with the
+  two ways to say what was meant, as spec-brief and spec-guard refuse it.

package/README.md

@@ -1,15 +1,133 @@
-# @descent-vtt/spec-harness 0.0.0
+# spec-harness
 
-A placeholder. It contains no code and does nothing.
+**Rounds of agent work under a brief a person approved: what the agent needs to start, a guard on every write, an escalation a person signs when the brief is not enough, and an audit when it ends.**
 
-npm attaches a trusted publisher only to a package that already exists, so
-this version was published by hand to hold the name. Every version with code
-in it is built and published by CI from a tag of
-[DescentVTT/spec-harness](https://github.com/DescentVTT/spec-harness), with
-provenance.
-
-Install 0.1.0 or later:
+spec-harness is the agent-facing member of the [spec-\* tools](https://github.com/DescentVTT/spec-core#the-family). It calls no model and writes no content - the agent is the model. It gives the agent the contract and the facts, and answers, the same way every time, whether the agent stayed inside the lines. No runtime dependencies, no account, no network.
 
 ```bash
 npm install --save-dev @descent-vtt/spec-harness @descent-vtt/spec-brief
+npx spec-harness init            # the plan: what it would configure, and why
+npx spec-harness init --write    # apply it
+```
+
+spec-brief 0.2.0 or later is required: the brief is the contract, spec-brief is its reader, and 0.2.0 is the first whose archive asks this package's plugin about signed rulings. spec-guard 0.12.0 and spec-graph 0.9.0 or later are used when they are installed, and their absence is reported, never assumed clean. A sibling installed below its minimum is never run: `doctor` and every command that needed it name the minimum ([ADR-0011](docs/adr/0011-releases-are-staged-by-ci.md)).
+
+## A round
+
+```text
+person approves brief 012 ─▶ agent on branch brief/012-rotate-tokens
+                                   │
+            spec-harness context ◀─┘  the brief, its scope, signed rulings,
+                   │                  the rules in force, the documents it cites
+                   ▼
+         agent edits ── hook: protected? refused, with the next step
+                   │          outside the scope? a warning after the write
+                   │
+                   ├── needs a protected file ─▶ escalate ─▶ person rules, signs
+                   ▼
+            spec-harness audit ─▶ spec-brief archive --dry-run ─▶ person archives
+```
+
+### `context [brief]`
+
+The brief in full - it is the contract - then what it implies: the files the round may write and must not change as the guard reads them, the rulings already signed, the briefs it depends on and whether they are done, the architecture rules spec-guard holds that code to, and the documents the brief links to, whole, until the packet reaches its budget (`context.budget`, 60,000 characters). Documents left out are named by path, not dropped.
+
+### `guard <path...>` and the hooks
+
+May the round write this? A path the brief protects is **refused** unless a signed ruling allows it; a path in `affectedFiles` is allowed; anything else is **outside the scope** - a warning by default, or a question to the person, or a refusal (`outOfScope`: `warn`, `ask`, `deny`). Paths are compared as the filesystem spells them, links resolved and case corrected, so `SRC/db/schema.ts` does not walk past a protection on `src/db/schema.ts` on Windows.
+
+`spec-harness hook claude` answers Claude Code's PreToolUse and PostToolUse hooks: a refusal before the write, with the reason and the next step; a warning after a write outside the scope. It never answers `allow`, which would skip the person's own permission prompt. `spec-harness hook git` is a pre-commit hook for any agent or none. A guard is a guardrail - an agent that writes through a shell passes it - so the audit and spec-brief's archive are the gates ([ADR-0005](docs/adr/0005-a-guard-is-a-guardrail.md)).
+
+**Which brief?** `--brief <id>`, then `SPEC_BRIEF`, then the branch name (`brief/{id}`, `brief-{id}`, `*/brief/{id}`, `*/brief-{id}`). Never guessed ([ADR-0004](docs/adr/0004-the-active-brief-is-named-not-guessed.md)).
+
+### `escalate`, `rule`, `rulings`
+
+```bash
+# the agent, when the round cannot be done without a protected file
+npx spec-harness escalate --path src/db/schema.ts \
+  --reason "Rotation needs a rotated_at column." \
+  --option "Allow: one additive column" --option "Refuse: rotation keeps no timestamp" \
+  --recommend "Allow; the column is additive."
+
+# the person
+npx spec-harness escalate --show E-012-1
+npx spec-harness rule E-012-1 --allow --note "Add rotated_at only."
+git commit -S -m "ruling R-012-1: allow" -- briefs/012_rotate-tokens.md
+```
+
+A ruling is a row in the brief's `## Rulings` table. It **counts** when the commit that last changed the row is signed by a key the **base branch's** `.github/allowed_signers` lists. An agent can write a row and compute any hash; it cannot produce the person's signature, and an edit to the row moves it to a commit that must be signed again ([ADR-0006](docs/adr/0006-a-ruling-is-a-signed-commit.md)). Use a FIDO2 key (`ed25519-sk`) where the agent runs as you: its signature needs a touch no process can supply.
+
+### `audit [brief]`
+
+One report: what spec-brief's archive would refuse or warn about, run with `--dry-run`; the brief's own assertions through spec-guard - a goal that fails, or a premise (under a heading such as *The Defect, Measured*) that still holds after the round meant to change it; rulings whose signatures do not verify; and every dependency the round added to `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `requirements*.txt`, NuGet project files or a `Gemfile`. A part that could not be measured is a finding, never a silence.
+
+### `probe [brief]`
+
+A defect is measured before it is filed. The brief carries its probe:
+
+````markdown
+```probe
+id: old-token-still-accepted
+setup: npm ci
+run: npx vitest run tests/probes/rotate.test.ts
+signature: expected 401, got 200
 ```
+
+```probe-file tests/probes/rotate.test.ts
+...
+```
+````
+
+`probe --at base` runs it in a temporary worktree at the base commit: every run must fail **for the declared reason** - the `signature` in the output, or a JUnit `test` failing - or the verdict is `vacuous` (no defect), `flaky` or `invalid`. `probe --at head` must be green: `fixed`. The evidence table it prints names the hash of the probe it measured with ([ADR-0007](docs/adr/0007-probes-declare-their-failure.md)).
+
+### `premises`
+
+Is every live brief still about something true? It runs spec-guard over the live briefs' assertions and reports each premise - an assertion under a section in `assertions.premises` - that no longer holds as `stale-premise`: the defect was fixed another way, or the code the brief describes is gone, and an agent sent to fix it would fix nothing. Goals are left to `audit`, since a goal fails until its round is done. Run it in CI: exit 1 when a premise is stale, exit 2 when spec-guard is not there to ask.
+
+### `mcp`
+
+`start_round`, `check_path`, `request_escalation`, `audit_round` and `list_rounds` over MCP on stdio, with the four workflow prompts. Both protocol eras are served. The architecture rules themselves stay with spec-guard's server.
+
+### `init`
+
+Configures the family to agree: spec-brief's directories, spec-graph reading the archive as history (so a brief depending on an archived one is not a stale premise), `.spec-harness.json` with the base branch, the Claude Code hooks, the MCP server, and with `--git-hook` a pre-commit hook. It prints the plan, merges into files that exist, and changes nothing without `--write`.
+
+### `doctor`
+
+Which sibling tools are installed, at which versions, and how each is run, the repository root, the branch, and the brief the flag, `SPEC_BRIEF` or the branch names. A sibling older than this release needs is `outdated`, with the minimum and the command that installs a newer one, and exit 1. A command named under `tools` is run as named, and its version is not checked. The first thing to run when a hook refuses something unexpectedly.
+
+## As a Claude Code plugin
+
+The repository is a plugin and a one-plugin marketplace: the four skills (`draft-brief`, `split-goal`, `run-round`, `close-round`), the hooks and the MCP server. It calls the `spec-harness` installed in your project.
+
+```text
+/plugin marketplace add DescentVTT/spec-harness
+/plugin install spec-harness@spec-tools
+```
+
+## Configuration
+
+`.spec-harness.json` at the repository root. Every key is optional; an unknown key stops the run with exit 2.
+
+| Key | Default | What it says |
+| --- | --- | --- |
+| `branches` | `brief/{id}`, `brief-{id}`, `*/brief/{id}`, `*/brief-{id}` | Branch names that carry the active brief's id. |
+| `outOfScope` | `"warn"` | A write outside `affectedFiles`: `warn`, `ask` or `deny`. |
+| `base` | the remote's default branch | What rounds are measured from, and where allowed signers are read. |
+| `rulings.section` | `"Rulings"` | The brief section holding the rulings table. |
+| `rulings.allowedSigners` | `".github/allowed_signers"` | The allowed-signers file, read from the base branch. |
+| `dependencies.manifests` | the list above | Manifest names whose added dependencies the audit reports. |
+| `context.budget` | `60000` | Characters a context packet may hold; cited documents fill what the rest leaves, and those that do not fit are named by path. |
+| `assertions.premises` | `The Defect, Measured`, `Premises`, `Preconditions` | Sections whose assertions state what was true before the round. |
+| `probes.runs`, `probes.timeout` | `2`, `600` | Runs per probe, and seconds per run. |
+| `tools` | found in `node_modules` | A sibling's command by name: `{ "spec-brief": ["node", "path/to/spec-brief.js"] }`. |
+
+**Exit codes:** `0` clean, `1` refused, found something, or waiting on a person, `2` the answer cannot be trusted.
+
+## Design
+
+The decisions and what they cost are in [`docs/adr/`](docs/adr/README.md); what the whole family shares is [spec-core's ADR-0005](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0005-the-family-contract.md).
+
+## License
+
+MIT

package/bin/spec-harness.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Thin launcher. All logic lives in dist/cli.js so the published binary stays a
+ * short shim that is trivially auditable.
+ */
+const entry = new URL('../dist/cli.js', import.meta.url);
+
+let cli;
+try {
+  cli = await import(entry.href);
+} catch (error) {
+  if (error?.code === 'ERR_MODULE_NOT_FOUND' && String(error.message).includes('dist')) {
+    process.stderr.write('spec-harness: build output is missing; run "npm run build" first, or install the published package.\n');
+    process.exit(2);
+  }
+  throw error;
+}
+
+process.exitCode = await cli.main();

package/dist/audit.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Did the round stay inside the lines?
+ *
+ * One report, from three sources and one question of its own:
+ *
+ * - spec-brief's archive, asked with `--dry-run`: open boxes, protected files
+ *   changed, files outside the scope, a tree that was not committed. The
+ *   archive is spec-brief's decision, so its reasons are carried as they are
+ *   - one defect, one finding - and the harness does not measure the scope a
+ *   second time.
+ * - spec-guard, over the brief's own assertions: the goals must hold now. A
+ *   premise - an assertion in a section that states what was true before the
+ *   round, such as "The Defect, Measured" - is expected to stop holding, and
+ *   one that still holds says the defect may still be there.
+ * - The rulings: each one whose signature does not verify is reported, since
+ *   an unverified ruling allows nothing.
+ * - And the one question nobody else asks: which dependencies the round
+ *   added. A dependency is code no reviewer read.
+ *
+ * A part that could not be measured is a finding, never a silence.
+ */
+import type { DependencyChange } from './manifests.js';
+import type { BriefRow, Finding, Severity } from './types.js';
+export interface AssertionOutcome {
+    readonly ok: boolean;
+    readonly description: string;
+    readonly message: string;
+    readonly line: number;
+    /** The brief section the directive sits in, or `null`. */
+    readonly section: string | null;
+    /** Every section it sits in, outermost first; `[section]` when not given. */
+    readonly enclosing?: readonly string[] | undefined;
+}
+export interface AuditInput {
+    readonly brief: BriefRow;
+    /** Why the round's changes could not be measured, when they could not. */
+    readonly unmeasured: string | null;
+    readonly dependencies: {
+        readonly changes: readonly DependencyChange[];
+        readonly unread: readonly string[];
+    };
+    readonly archive: {
+        readonly blocking: readonly Finding[];
+        readonly warnings: readonly Finding[];
+    } | {
+        readonly unavailable: string;
+    };
+    readonly assertions: readonly AssertionOutcome[] | {
+        readonly unavailable: string;
+    };
+    /** Section names whose assertions are premises. Compared without case, emphasis, a leading number or a trailing colon. */
+    readonly premiseSections: readonly string[];
+    readonly unverifiedRulings: readonly {
+        readonly id: string;
+        readonly reason: string;
+    }[];
+}
+export interface AuditReport {
+    readonly findings: readonly Finding[];
+    readonly counts: Readonly<Record<Severity, number>>;
+}
+/**
+ * Whether an assertion's section is a premise section. Compared as the
+ * rulings section is, and as spec-brief compares section names: a heading
+ * written `## 3. **The Defect, Measured:**` is still the premise section, and
+ * an assertion under it read as a goal would fail the round for retiring it.
+ */
+export declare function isPremise(sections: string | null | readonly string[], premises: readonly string[]): boolean;
+export declare function audit(input: AuditInput): AuditReport;

package/dist/audit.js

@@ -0,0 +1,93 @@
+/**
+ * Did the round stay inside the lines?
+ *
+ * One report, from three sources and one question of its own:
+ *
+ * - spec-brief's archive, asked with `--dry-run`: open boxes, protected files
+ *   changed, files outside the scope, a tree that was not committed. The
+ *   archive is spec-brief's decision, so its reasons are carried as they are
+ *   - one defect, one finding - and the harness does not measure the scope a
+ *   second time.
+ * - spec-guard, over the brief's own assertions: the goals must hold now. A
+ *   premise - an assertion in a section that states what was true before the
+ *   round, such as "The Defect, Measured" - is expected to stop holding, and
+ *   one that still holds says the defect may still be there.
+ * - The rulings: each one whose signature does not verify is reported, since
+ *   an unverified ruling allows nothing.
+ * - And the one question nobody else asks: which dependencies the round
+ *   added. A dependency is code no reviewer read.
+ *
+ * A part that could not be measured is a finding, never a silence.
+ */
+import { sameSection } from './reader.js';
+function finding(rule, severity, message, hint, file, line) {
+    return { rule, severity, message, hint, ...(file === undefined ? {} : { file }), ...(line === undefined ? {} : { line }) };
+}
+/**
+ * Whether an assertion's section is a premise section. Compared as the
+ * rulings section is, and as spec-brief compares section names: a heading
+ * written `## 3. **The Defect, Measured:**` is still the premise section, and
+ * an assertion under it read as a goal would fail the round for retiring it.
+ */
+export function isPremise(sections, premises) {
+    const list = sections === null ? [] : typeof sections === 'string' ? [sections] : sections;
+    // A premise section's subsections are still premises: `### Before` under
+    // `## The Defect, Measured` states what was true before the round.
+    return list.some((section) => premises.some((premise) => sameSection(section, premise)));
+}
+export function audit(input) {
+    const { brief } = input;
+    const out = [];
+    if (input.unmeasured !== null) {
+        out.push(finding('unmeasured', 'warning', `the round's changes were not measured: ${input.unmeasured}`, 'pass --base <ref>, set "base" in .spec-harness.json, or audit on the round\'s branch before it merges', brief.file));
+    }
+    if ('unavailable' in input.archive) {
+        out.push(finding('archive-unchecked', 'warning', `what the archive would say is unknown: ${input.archive.unavailable}`, 'install spec-brief, or fix what stopped it', brief.file));
+    }
+    else {
+        for (const reason of [...input.archive.blocking, ...input.archive.warnings]) {
+            out.push(finding(`archive/${reason.rule}`, reason.severity, reason.message, reason.hint, reason.file, reason.line));
+        }
+    }
+    if (!Array.isArray(input.assertions)) {
+        const unavailable = input.assertions.unavailable;
+        out.push(finding('assertions-unchecked', 'warning', `the brief's assertions were not run: ${unavailable}`, 'install spec-guard, or fix what stopped it', brief.file));
+    }
+    else {
+        for (const outcome of input.assertions) {
+            const premise = isPremise(outcome.enclosing ?? outcome.section, input.premiseSections);
+            if (premise && outcome.ok) {
+                out.push(finding('premise-holds', 'warning', `a premise still holds after the round: ${outcome.description}`, 'the round set out to change what this premise states; check that it did, or move the assertion out of the premises', brief.file, outcome.line));
+            }
+            else if (premise) {
+                out.push(finding('premise-retired', 'note', `a premise no longer holds, as the round intended: ${outcome.description}`, 'nothing to do', brief.file, outcome.line));
+            }
+            else if (!outcome.ok) {
+                out.push(finding('goal-failed', 'error', `${outcome.description}: ${outcome.message}`, 'the round is not done until this holds', brief.file, outcome.line));
+            }
+        }
+    }
+    for (const ruling of input.unverifiedRulings) {
+        out.push(finding('ruling-unverified', 'warning', `ruling ${ruling.id} allows nothing: ${ruling.reason}`, 'a ruling counts when the commit that last changed its row is signed by a key in the base branch\'s allowed signers', brief.file));
+    }
+    for (const file of input.dependencies.unread) {
+        out.push(finding('manifest-unread', 'warning', `${file} changed and could not be read for dependencies`, 'check its dependencies by hand; the audit cannot', file));
+    }
+    for (const change of input.dependencies.changes) {
+        const where = `${change.file} (${change.section})`;
+        if (change.before === null) {
+            out.push(finding('new-dependency', 'warning', `the round added ${change.ecosystem} dependency "${change.name}"${change.after === '' ? '' : ` ${change.after}`} in ${where}`, 'say in the brief why it is needed, or remove it; a new dependency is code no reviewer read', change.file));
+        }
+        else if (change.after === null) {
+            out.push(finding('dependency-removed', 'note', `the round removed "${change.name}" from ${where}`, 'nothing to do', change.file));
+        }
+        else {
+            out.push(finding('dependency-changed', 'note', `the round moved "${change.name}" from ${change.before} to ${change.after} in ${where}`, 'nothing to do, if the brief meant it', change.file));
+        }
+    }
+    const counts = { error: 0, warning: 0, note: 0 };
+    for (const item of out)
+        counts[item.severity] += 1;
+    return { findings: out, counts };
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Did the round stay inside the lines?\n *\n * One report, from three sources and one question of its own:\n *\n * - spec-brief's archive, asked with `--dry-run`: open boxes, protected files\n *   changed, files outside the scope, a tree that was not committed. The\n *   archive is spec-brief's decision, so its reasons are carried as they are\n *   - one defect, one finding - and the harness does not measure the scope a\n *   second time.\n * - spec-guard, over the brief's own assertions: the goals must hold now. A\n *   premise - an assertion in a section that states what was true before the\n *   round, such as \"The Defect, Measured\" - is expected to stop holding, and\n *   one that still holds says the defect may still be there.\n * - The rulings: each one whose signature does not verify is reported, since\n *   an unverified ruling allows nothing.\n * - And the one question nobody else asks: which dependencies the round\n *   added. A dependency is code no reviewer read.\n *\n * A part that could not be measured is a finding, never a silence.\n */\n\nimport type { DependencyChange } from './manifests.js';\nimport { sameSection } from './reader.js';\nimport type { BriefRow, Finding, Severity } from './types.js';\n\nexport interface AssertionOutcome {\n  readonly ok: boolean;\n  readonly description: string;\n  readonly message: string;\n  readonly line: number;\n  /** The brief section the directive sits in, or `null`. */\n  readonly section: string | null;\n  /** Every section it sits in, outermost first; `[section]` when not given. */\n  readonly enclosing?: readonly string[] | undefined;\n}\n\nexport interface AuditInput {\n  readonly brief: BriefRow;\n  /** Why the round's changes could not be measured, when they could not. */\n  readonly unmeasured: string | null;\n  readonly dependencies: { readonly changes: readonly DependencyChange[]; readonly unread: readonly string[] };\n  readonly archive: { readonly blocking: readonly Finding[]; readonly warnings: readonly Finding[] } | { readonly unavailable: string };\n  readonly assertions: readonly AssertionOutcome[] | { readonly unavailable: string };\n  /** Section names whose assertions are premises. Compared without case, emphasis, a leading number or a trailing colon. */\n  readonly premiseSections: readonly string[];\n  readonly unverifiedRulings: readonly { readonly id: string; readonly reason: string }[];\n}\n\nexport interface AuditReport {\n  readonly findings: readonly Finding[];\n  readonly counts: Readonly<Record<Severity, number>>;\n}\n\nfunction finding(rule: string, severity: Severity, message: string, hint: string, file?: string, line?: number): Finding {\n  return { rule, severity, message, hint, ...(file === undefined ? {} : { file }), ...(line === undefined ? {} : { line }) };\n}\n\n/**\n * Whether an assertion's section is a premise section. Compared as the\n * rulings section is, and as spec-brief compares section names: a heading\n * written `## 3. **The Defect, Measured:**` is still the premise section, and\n * an assertion under it read as a goal would fail the round for retiring it.\n */\nexport function isPremise(sections: string | null | readonly string[], premises: readonly string[]): boolean {\n  const list = sections === null ? [] : typeof sections === 'string' ? [sections] : sections;\n  // A premise section's subsections are still premises: `### Before` under\n  // `## The Defect, Measured` states what was true before the round.\n  return list.some((section) => premises.some((premise) => sameSection(section, premise)));\n}\n\nexport function audit(input: AuditInput): AuditReport {\n  const { brief } = input;\n  const out: Finding[] = [];\n\n  if (input.unmeasured !== null) {\n    out.push(\n      finding(\n        'unmeasured',\n        'warning',\n        `the round's changes were not measured: ${input.unmeasured}`,\n        'pass --base <ref>, set \"base\" in .spec-harness.json, or audit on the round\\'s branch before it merges',\n        brief.file,\n      ),\n    );\n  }\n\n  if ('unavailable' in input.archive) {\n    out.push(finding('archive-unchecked', 'warning', `what the archive would say is unknown: ${input.archive.unavailable}`, 'install spec-brief, or fix what stopped it', brief.file));\n  } else {\n    for (const reason of [...input.archive.blocking, ...input.archive.warnings]) {\n      out.push(finding(`archive/${reason.rule}`, reason.severity, reason.message, reason.hint, reason.file, reason.line));\n    }\n  }\n\n  if (!Array.isArray(input.assertions)) {\n    const unavailable = (input.assertions as { unavailable: string }).unavailable;\n    out.push(finding('assertions-unchecked', 'warning', `the brief's assertions were not run: ${unavailable}`, 'install spec-guard, or fix what stopped it', brief.file));\n  } else {\n    for (const outcome of input.assertions) {\n      const premise = isPremise(outcome.enclosing ?? outcome.section, input.premiseSections);\n      if (premise && outcome.ok) {\n        out.push(\n          finding(\n            'premise-holds',\n            'warning',\n            `a premise still holds after the round: ${outcome.description}`,\n            'the round set out to change what this premise states; check that it did, or move the assertion out of the premises',\n            brief.file,\n            outcome.line,\n          ),\n        );\n      } else if (premise) {\n        out.push(finding('premise-retired', 'note', `a premise no longer holds, as the round intended: ${outcome.description}`, 'nothing to do', brief.file, outcome.line));\n      } else if (!outcome.ok) {\n        out.push(finding('goal-failed', 'error', `${outcome.description}: ${outcome.message}`, 'the round is not done until this holds', brief.file, outcome.line));\n      }\n    }\n  }\n\n  for (const ruling of input.unverifiedRulings) {\n    out.push(\n      finding(\n        'ruling-unverified',\n        'warning',\n        `ruling ${ruling.id} allows nothing: ${ruling.reason}`,\n        'a ruling counts when the commit that last changed its row is signed by a key in the base branch\\'s allowed signers',\n        brief.file,\n      ),\n    );\n  }\n\n  for (const file of input.dependencies.unread) {\n    out.push(finding('manifest-unread', 'warning', `${file} changed and could not be read for dependencies`, 'check its dependencies by hand; the audit cannot', file));\n  }\n  for (const change of input.dependencies.changes) {\n    const where = `${change.file} (${change.section})`;\n    if (change.before === null) {\n      out.push(\n        finding(\n          'new-dependency',\n          'warning',\n          `the round added ${change.ecosystem} dependency \"${change.name}\"${change.after === '' ? '' : ` ${change.after}`} in ${where}`,\n          'say in the brief why it is needed, or remove it; a new dependency is code no reviewer read',\n          change.file,\n        ),\n      );\n    } else if (change.after === null) {\n      out.push(finding('dependency-removed', 'note', `the round removed \"${change.name}\" from ${where}`, 'nothing to do', change.file));\n    } else {\n      out.push(finding('dependency-changed', 'note', `the round moved \"${change.name}\" from ${change.before} to ${change.after} in ${where}`, 'nothing to do, if the brief meant it', change.file));\n    }\n  }\n\n  const counts: Record<Severity, number> = { error: 0, warning: 0, note: 0 };\n  for (const item of out) counts[item.severity] += 1;\n  return { findings: out, counts };\n}\n"]}

package/dist/branch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Which brief a branch is working on, read from its name.
+ *
+ * A round runs on a branch, and naming the branch after the brief is the one
+ * convention every repository that runs agents on briefs already has. Reading
+ * it from there keeps the harness stateless: no file says which brief is
+ * active, so no file can say it wrongly (ADR-0004).
+ *
+ * A template is a branch name with `{id}` where the id goes and `*` for any
+ * run of characters other than `/`: `brief/{id}`, `*\/brief-{id}`. The id is
+ * the longest run of letters and digits at that point, and must be followed
+ * by the end of the name or a separator - so `brief/012-rotate-tokens` names
+ * 012, and `brief/012x` names 012x, never 012.
+ */
+/** Why a template cannot be used, or `null`. */
+export declare function templateError(template: string): string | null;
+/** The brief id a branch name carries under one template, or `null`. */
+export declare function idFromBranch(template: string, name: string): string | null;
+/** The first template that yields an id, in order. */
+export declare function briefIdFromBranch(templates: readonly string[], name: string): string | null;
+/**
+ * Whether two ids name the same brief: equal as written, or equal as numbers
+ * when both are all digits, since a branch says `brief/12` of a brief whose
+ * file says `012`.
+ */
+export declare function sameId(a: string, b: string): boolean;

package/dist/branch.js

@@ -0,0 +1,100 @@
+/**
+ * Which brief a branch is working on, read from its name.
+ *
+ * A round runs on a branch, and naming the branch after the brief is the one
+ * convention every repository that runs agents on briefs already has. Reading
+ * it from there keeps the harness stateless: no file says which brief is
+ * active, so no file can say it wrongly (ADR-0004).
+ *
+ * A template is a branch name with `{id}` where the id goes and `*` for any
+ * run of characters other than `/`: `brief/{id}`, `*\/brief-{id}`. The id is
+ * the longest run of letters and digits at that point, and must be followed
+ * by the end of the name or a separator - so `brief/012-rotate-tokens` names
+ * 012, and `brief/012x` names 012x, never 012.
+ */
+const SEPARATORS = new Set(['-', '_', '/', '.']);
+function isIdChar(ch) {
+    return /^[A-Za-z0-9]$/.test(ch);
+}
+/**
+ * The offsets in `name` at which a template prefix can end, by dynamic
+ * programming over prefix and name, so a template of many stars costs their
+ * product and never an exponent.
+ */
+function prefixEnds(prefix, name) {
+    // reach[j]: the prefix read so far can end at name offset j.
+    let reach = new Array(name.length + 1).fill(false);
+    reach[0] = true;
+    for (const token of prefix) {
+        const next = new Array(name.length + 1).fill(false);
+        if (token === '*') {
+            let open = false;
+            for (let j = 0; j <= name.length; j += 1) {
+                if (reach[j])
+                    open = true;
+                if (open)
+                    next[j] = true;
+                if (name.charAt(j) === '/')
+                    open = false;
+            }
+        }
+        else {
+            for (let j = 0; j < name.length; j += 1)
+                if (reach[j] && name.charAt(j) === token)
+                    next[j + 1] = true;
+        }
+        reach = next;
+    }
+    const ends = [];
+    reach.forEach((ok, j) => {
+        if (ok)
+            ends.push(j);
+    });
+    return ends;
+}
+/** Why a template cannot be used, or `null`. */
+export function templateError(template) {
+    const count = template.split('{id}').length - 1;
+    if (count !== 1)
+        return `"${template}" must contain {id} exactly once`;
+    if (!template.endsWith('{id}'))
+        return `"${template}" must end with {id}; whatever follows the id is the branch's own`;
+    return null;
+}
+/** The brief id a branch name carries under one template, or `null`. */
+export function idFromBranch(template, name) {
+    if (templateError(template) !== null)
+        return null;
+    const prefix = template.slice(0, -'{id}'.length);
+    for (const start of prefixEnds(prefix, name)) {
+        let end = start;
+        while (end < name.length && isIdChar(name.charAt(end)))
+            end += 1;
+        if (end === start)
+            continue;
+        if (end < name.length && !SEPARATORS.has(name.charAt(end)))
+            continue;
+        return name.slice(start, end);
+    }
+    return null;
+}
+/** The first template that yields an id, in order. */
+export function briefIdFromBranch(templates, name) {
+    for (const template of templates) {
+        const id = idFromBranch(template, name);
+        if (id !== null)
+            return id;
+    }
+    return null;
+}
+/**
+ * Whether two ids name the same brief: equal as written, or equal as numbers
+ * when both are all digits, since a branch says `brief/12` of a brief whose
+ * file says `012`.
+ */
+export function sameId(a, b) {
+    if (a === b)
+        return true;
+    return /^\d+$/.test(a) && /^\d+$/.test(b) && BigInt(a) === BigInt(b);
+}
+//# sourceMappingURL=branch.js.map

package/dist/branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch.js","sourceRoot":"","sources":["../src/branch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which brief a branch is working on, read from its name.\n *\n * A round runs on a branch, and naming the branch after the brief is the one\n * convention every repository that runs agents on briefs already has. Reading\n * it from there keeps the harness stateless: no file says which brief is\n * active, so no file can say it wrongly (ADR-0004).\n *\n * A template is a branch name with `{id}` where the id goes and `*` for any\n * run of characters other than `/`: `brief/{id}`, `*\\/brief-{id}`. The id is\n * the longest run of letters and digits at that point, and must be followed\n * by the end of the name or a separator - so `brief/012-rotate-tokens` names\n * 012, and `brief/012x` names 012x, never 012.\n */\n\nconst SEPARATORS = new Set(['-', '_', '/', '.']);\n\nfunction isIdChar(ch: string): boolean {\n  return /^[A-Za-z0-9]$/.test(ch);\n}\n\n/**\n * The offsets in `name` at which a template prefix can end, by dynamic\n * programming over prefix and name, so a template of many stars costs their\n * product and never an exponent.\n */\nfunction prefixEnds(prefix: string, name: string): number[] {\n  // reach[j]: the prefix read so far can end at name offset j.\n  let reach: boolean[] = new Array<boolean>(name.length + 1).fill(false);\n  reach[0] = true;\n  for (const token of prefix) {\n    const next = new Array<boolean>(name.length + 1).fill(false);\n    if (token === '*') {\n      let open = false;\n      for (let j = 0; j <= name.length; j += 1) {\n        if (reach[j]) open = true;\n        if (open) next[j] = true;\n        if (name.charAt(j) === '/') open = false;\n      }\n    } else {\n      for (let j = 0; j < name.length; j += 1) if (reach[j] && name.charAt(j) === token) next[j + 1] = true;\n    }\n    reach = next;\n  }\n  const ends: number[] = [];\n  reach.forEach((ok, j) => {\n    if (ok) ends.push(j);\n  });\n  return ends;\n}\n\n/** Why a template cannot be used, or `null`. */\nexport function templateError(template: string): string | null {\n  const count = template.split('{id}').length - 1;\n  if (count !== 1) return `\"${template}\" must contain {id} exactly once`;\n  if (!template.endsWith('{id}')) return `\"${template}\" must end with {id}; whatever follows the id is the branch's own`;\n  return null;\n}\n\n/** The brief id a branch name carries under one template, or `null`. */\nexport function idFromBranch(template: string, name: string): string | null {\n  if (templateError(template) !== null) return null;\n  const prefix = template.slice(0, -'{id}'.length);\n  for (const start of prefixEnds(prefix, name)) {\n    let end = start;\n    while (end < name.length && isIdChar(name.charAt(end))) end += 1;\n    if (end === start) continue;\n    if (end < name.length && !SEPARATORS.has(name.charAt(end))) continue;\n    return name.slice(start, end);\n  }\n  return null;\n}\n\n/** The first template that yields an id, in order. */\nexport function briefIdFromBranch(templates: readonly string[], name: string): string | null {\n  for (const template of templates) {\n    const id = idFromBranch(template, name);\n    if (id !== null) return id;\n  }\n  return null;\n}\n\n/**\n * Whether two ids name the same brief: equal as written, or equal as numbers\n * when both are all digits, since a branch says `brief/12` of a brief whose\n * file says `012`.\n */\nexport function sameId(a: string, b: string): boolean {\n  if (a === b) return true;\n  return /^\\d+$/.test(a) && /^\\d+$/.test(b) && BigInt(a) === BigInt(b);\n}\n"]}

package/dist/briefs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The briefs, as spec-brief reports them, and which one a round is working on.
+ *
+ * spec-brief owns the brief format and its configuration (its ADR-0003), so
+ * the harness reads briefs the way spec-brief does by asking it:
+ * `spec-brief list --archived --format json`. This module reads that
+ * document and nothing else; a shape it does not recognise is an error, never
+ * a best-effort reading of half the fields (ADR-0002).
+ */
+import type { BriefRow } from './types.js';
+/**
+ * The spec-brief JSON document versions this harness reads. Version 1 is the
+ * one spec-brief 0.1.0 prints; version 2 changed only `matrix`, which the
+ * harness never reads, so the `list` and `archive` documents are the same.
+ */
+export declare const SUPPORTED_SCHEMA_VERSIONS: readonly number[];
+export declare class SiblingOutputError extends Error {
+    constructor(message: string);
+}
+/** Reads the document `spec-brief list --format json` prints. */
+export declare function parseBriefList(document: unknown): BriefRow[];
+/** How the active brief was named, for messages. */
+export type ActiveSource = 'flag' | 'environment' | 'branch';
+export type ActiveBrief = {
+    readonly kind: 'found';
+    readonly brief: BriefRow;
+    readonly source: ActiveSource;
+} | {
+    readonly kind: 'none';
+    readonly reason: string;
+} | {
+    readonly kind: 'unknown';
+    readonly id: string;
+    readonly source: ActiveSource;
+} | {
+    readonly kind: 'archived';
+    readonly brief: BriefRow;
+    readonly source: ActiveSource;
+};
+/**
+ * The brief a round is working on: named by a flag, by `SPEC_BRIEF`, or by
+ * the branch - never guessed from which brief happens to be the only active
+ * one (ADR-0004).
+ */
+export declare function findActive(briefs: readonly BriefRow[], named: {
+    readonly flag?: string | undefined;
+    readonly environment?: string | undefined;
+    readonly branch?: string | null | undefined;
+}): ActiveBrief;