@popovych.co/witness 0.24.0 → 0.24.1

package/dist/config-file.js

@@ -1,5 +1,5 @@
 import { Lexer, isCollection, isMap, isScalar, parseDocument } from 'yaml';
-import { LEGACY_COMMENTS } from './legacy-comments.js';
+import { RELEASED_COMMENTS } from './released-comments.js';
 import { CHANGE_CLASSES, FIRST_LINE, GROUP_HEADINGS, SCHEMA_COMMENT, SETTINGS, getIn, inlineValue, } from './settings.js';
 import { sectionsOf } from './migration.js';
 const EMPTY = { top: [], above: new Map(), end: [] };
@@ -73,6 +73,9 @@ const CURRENT_COMMENTS = new Set([
     FIRST_LINE.slice(1).trim(),
     ...Object.values(GROUP_HEADINGS).map((h) => h.slice(1).trim()),
 ]);
+// What a released witness wrote and this one no longer does: derived from the one record, so a
+// reworded comment's old text can never be left out of it.
+const LEGACY_COMMENTS = new Set([...RELEASED_COMMENTS].filter((t) => !CURRENT_COMMENTS.has(t)));
 // Where a human line can be printed: every setting and section, and a per-class reviewer line.
 const PRINTABLE = new Set([
     ...SETTINGS.map((s) => s.path),
@@ -150,7 +153,7 @@ export function readComments(text) {
         const comment = token.trimEnd();
         const body = comment.slice(1).trim();
         const ownLine = src.slice(lineStarts[line], at).trim() === '';
-        if (LEGACY_COMMENTS.has(body) || CURRENT_COMMENTS.has(body)) {
+        if (RELEASED_COMMENTS.has(body) || CURRENT_COMMENTS.has(body)) {
             // A line of its own vanishes; one on a setting's line, or the first line, is replaced.
             if (ownLine && line !== 0 && LEGACY_COMMENTS.has(body))
                 legacy++;

package/dist/install.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { version } from './cli.js';
 import { tryGit } from './gitio.js';
 import { ok, refuse, v } from './refusal.js';
+import { SETTINGS } from './settings.js';
 import { NPX_LATEST, compareTriple, pinIn } from './version.js';
 // dist/install.js and src/install.ts both sit one level under the package root, so the
 // same '..' works built and under vitest — the pattern model.ts:14 already uses. This is
@@ -258,7 +259,8 @@ export function recordHarness(configText, name) {
         return { text: configText, changed: false, declared: found[1] };
     const suffix = configText.endsWith('\n') ? '' : '\n';
     return {
-        text: `${configText}${suffix}harness: ${name}   # the judge — which harness runs this repo's gate reviewers; declared wins\n`,
+        // The setting's own comment, as a fresh init writes it: one source of witness's comment text.
+        text: `${configText}${suffix}harness: ${name}   # ${SETTINGS.find((s) => s.path === 'harness').comment}\n`,
         changed: true,
     };
 }

package/dist/released-comments.js

@@ -0,0 +1,79 @@
+// Row 193 §4.5. Every comment text a released witness wrote into witness.config.yaml — the one
+// record of which comments are witness's. A comment line whose trimmed text is one of these is
+// witness's wherever it sits: `migrate` writes the current text on a setting's line and drops an
+// old one on a line of its own, since what it described now exists for real. An edited copy no
+// longer matches, so it is the human's. Append-only: rewording a comment in `src/settings.ts`
+// adds its new text here and leaves the old one, which is what keeps every file an older witness
+// wrote readable (tests/config-file.test.ts fails on a written text missing from the record).
+// What this witness no longer writes is derived (config-file.ts), never a second list to keep.
+export const RELEASED_COMMENTS = new Set([
+    // ── Before 0.21.0: each version of `init`'s template (git log -p --follow -- src/verbs/init.ts,
+    // the specflow era included; a continuation line is its own entry) and both of
+    // `recordHarness`'s texts (src/install.ts).
+    'any gate block may pin its own model (wins over the global pin), e.g.',
+    'conventions: [docs/code/architecture.md]   # → injected into code-reviewer at implement + ship (cache-keyed)',
+    'declared beats the ambient session (init --agent writes it once)',
+    'decompose: { reviewers: [slicing-critic], model: claude-opus-4-8 }',
+    'docs:                      # repo docs registry — enumerated keys, unknown keys refused',
+    "harness: pi               # the judge — which harness runs this repo's gate reviewers;",
+    'or: runner: full-suite + report: junit:**/reports/junit.xml',
+    'paths: { specs: docs/specs, plans: docs/plans }   # optional canon roots (defaults: specs, plans); git mv existing docs when changing',
+    'per change class; a plain list = all classes',
+    'reviewer model pin — exact id, aliases refused',
+    'reviewerTimeoutMs: 600000  # ms per reviewer invocation (machine auth/extension knobs live in .witness/config.local.yaml)',
+    'specflow.config.yaml — the whole surface',
+    'witness.config.yaml — the whole surface',
+    "the judge — which harness runs this repo's gate reviewers; declared wins",
+    'detection wins; this is the fallback',
+    // The end-of-line comments of the template's commented-out settings, which the template meant
+    // the human to uncomment (final review I3).
+    'optional canon roots (defaults: specs, plans); git mv existing docs when changing',
+    'repo docs registry — enumerated keys, unknown keys refused',
+    '→ injected into code-reviewer at implement + ship (cache-keyed)',
+    "the judge — which harness runs this repo's gate reviewers;",
+    'ms per reviewer invocation (machine auth/extension knobs live in .witness/config.local.yaml)',
+    // ── Since 0.21.0 the template is `src/settings.ts`: every setting's comment, the per-class
+    // `for a …` lines, the schema line, the first line and the group headings, in every release.
+    // Collected from the published tarballs 0.21.0, 0.21.1, 0.22.0, 0.23.0 and 0.24.0.
+    "% of the context window at which a session hands over to a fresh one · 1–100",
+    "code docs handed to code-reviewer at implement and ship · file list, [] = none",
+    "design docs handed to design-critic and design-reviewer · file list, [] = none",
+    "extra globs never scanned for criteria tags · [] = none",
+    "folder for approved designs, repo-relative · git mv the docs when you change it",
+    "folder for plans, repo-relative · git mv the docs when you change it",
+    "folder for specs, repo-relative · git mv the docs when you change it",
+    "for a chore",
+    "for a feature",
+    "for a fix",
+    "format version · witness migrate raises it; never edit by hand",
+    "gate rounds one target may run across budget resets, then it is parked · ≥ 1",
+    "how a spec's criteria run · a command with {id}, or full-suite",
+    "how ship merges its own PR under autonomy · merge | squash | rebase",
+    "let test runs in two worktrees overlap · true | false",
+    "model for the arbiter that settles stops and checks recaps under autonomy · exact id, no aliases",
+    "model for the arbiter that settles stops under autonomy · exact id, no aliases",
+    "model for this gate's reviewers AND for the agent that writes the code",
+    "model for this gate's reviewers · exact id, [provider/]id[:thinking], no aliases",
+    "model for this gate's reviewers · exact id, no aliases",
+    "model for this gate's reviewers · runs only on specs marked ui",
+    "ms green CI must hold still before an autonomous merge · 0–1800000",
+    "ms of session time one target may take in one run (16 h), then it is parked · ≥ 1",
+    "ms one reviewer, or the arbiter, may run before it is stopped (10 min) · ≥ 1",
+    "ms one spawned session may run before it is stopped (1 h) · ≥ 1",
+    "on = the CLI settles its own stops and merges green PRs · on | off · counts once committed",
+    "reviewers this gate runs · one list, or one list per class",
+    "reviewers this gate runs · one list, or one list per class (feature, fix, chore)",
+    "sessions drive runs at once, one per target · ≥ 1",
+    "sessions one target may take in one run, then it is parked · ≥ 1",
+    "steps an implement session takes when its context fill can't be read · ≥ 1",
+    "the branch witness ships into",
+    "the judge: the agent CLI that runs this repo's gate reviewers and arbiter · claude-code | pi",
+    "the junit report witness reads · junit:<glob>, or none · full-suite needs one",
+    "the lint command ship runs",
+    "the suite command ship runs · full-suite criteria run it too",
+    "upstream resets one target may take, then it is parked · ≥ 1",
+    "witness.config.yaml — every setting witness reads. Change a value in place; `witness migrate` keeps the file current.",
+    "── Behavior: how witness works here ─────────────────────────────────────────",
+    "── Setup: what this repo is ─────────────────────────────────────────────────",
+    "── Tuning: witness drive ────────────────────────────────────────────────────",
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "Evidence-gated spec-driven development pipeline for AI coding agents: brainstorm to PR in six stages, where specs are state, plans are motion, and no transition passes without evidence. Drives from Claude Code or Pi.",
   "keywords": [
     "spec-driven-development",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "witness",
   "description": "Spec-driven development with evidence gates: brainstorm → PR through six stages and five gates. Skills author, the pinned witness CLI writes state and witnesses evidence; gates stop where judgment is owed.",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "author": {
     "name": "Kostiantyn Popovych"
   },

package/plugin/commands/witness.md

@@ -12,7 +12,7 @@ Any other words in `$ARGUMENTS` are the human's ask: run `$WITNESS ask "<those w
 Resolve the CLI once:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1}"
 ```
 
 If the repo has no `witness.config.yaml`, run `$WITNESS init` first (one bootstrap commit), then proceed. If init or any verb refuses on a dirty tree, the human commits or cleans it — **never `git commit` yourself, anywhere, at any stage**: the CLI makes its own state commits, and the ship phase makes the sole code commit.

package/plugin/hooks/session-dashboard.sh

@@ -3,4 +3,4 @@
 # context). Silent everywhere that isn't a witness repo; failures swallowed:
 # session start must never hang or die on this.
 [ -f witness.config.yaml ] || exit 0
-${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1} 2>/dev/null || true

package/plugin/skills/witness-brainstorm/SKILL.md

@@ -16,7 +16,7 @@ recap, keeps a local draft, writes no document. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-decompose/SKILL.md

@@ -10,7 +10,7 @@ description: Slice a witness effort's confirmed recap into vertical spec slices,
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-design/SKILL.md

@@ -16,7 +16,7 @@ No text copied verbatim; the design-critic lens is new material. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-implement/SKILL.md

@@ -15,7 +15,7 @@ tests carry the parent spec's tag in their NAME. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-plan/SKILL.md

@@ -15,7 +15,7 @@ parent's criteria. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/plugin/skills/witness-ship/SKILL.md

@@ -15,7 +15,7 @@ model can. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.24.1}"
 ```
 
 - **Render the CLI's decision output verbatim and in full — every line, unmodified.** Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.

package/dist/legacy-comments.js

@@ -1,30 +0,0 @@
-// Row 193 §4.5. Every comment text a released witness wrote into witness.config.yaml: each
-// version of `init`'s template (git log -p --follow -- src/verbs/init.ts, the specflow era
-// included; a continuation line is its own entry) and both of `recordHarness`'s texts
-// (src/install.ts). A comment line whose trimmed text is one of these is witness's, wherever it
-// sits: `migrate` replaces it on a setting's line and drops it on a line of its own, since what
-// it described now exists for real. An edited copy no longer matches, so it is the human's.
-export const LEGACY_COMMENTS = new Set([
-    'any gate block may pin its own model (wins over the global pin), e.g.',
-    'conventions: [docs/code/architecture.md]   # → injected into code-reviewer at implement + ship (cache-keyed)',
-    'declared beats the ambient session (init --agent writes it once)',
-    'decompose: { reviewers: [slicing-critic], model: claude-opus-4-8 }',
-    'docs:                      # repo docs registry — enumerated keys, unknown keys refused',
-    "harness: pi               # the judge — which harness runs this repo's gate reviewers;",
-    'or: runner: full-suite + report: junit:**/reports/junit.xml',
-    'paths: { specs: docs/specs, plans: docs/plans }   # optional canon roots (defaults: specs, plans); git mv existing docs when changing',
-    'per change class; a plain list = all classes',
-    'reviewer model pin — exact id, aliases refused',
-    'reviewerTimeoutMs: 600000  # ms per reviewer invocation (machine auth/extension knobs live in .witness/config.local.yaml)',
-    'specflow.config.yaml — the whole surface',
-    'witness.config.yaml — the whole surface',
-    "the judge — which harness runs this repo's gate reviewers; declared wins",
-    'detection wins; this is the fallback',
-    // The end-of-line comments of the template's commented-out settings, which the template meant
-    // the human to uncomment (final review I3).
-    'optional canon roots (defaults: specs, plans); git mv existing docs when changing',
-    'repo docs registry — enumerated keys, unknown keys refused',
-    '→ injected into code-reviewer at implement + ship (cache-keyed)',
-    "the judge — which harness runs this repo's gate reviewers;",
-    'ms per reviewer invocation (machine auth/extension knobs live in .witness/config.local.yaml)',
-]);