instar 1.3.1193 → 1.3.1194

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1193",
+  "packageVersion": "1.3.1194",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "f0abeb280648b0f2918db12357309dcd45d2e6adfff2c41063df273544496145",
+  "sha256": "682c4fe7ea234c958ab4c7c34ca753fc73b5758a613693ca0b86f2d608bf6a32",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1193"
+  "packageVersion": "1.3.1194"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
   "articleCount": 90,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1193"
+  "packageVersion": "1.3.1194"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1193",
+  "version": "1.3.1194",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/lint-machine-local-justification.js

@@ -565,22 +565,49 @@ function main() {
   const files = argv.filter((a) => !a.startsWith('--'));
   const targets = files.length ? files : listSpecFiles();
 
+  // ── The DENOMINATOR, reported beside the verdict (2026-08-23) ──────────
+  //
+  // WHY. On 2026-08-21 this gate was found to have been matching its section
+  // heading EXACTLY while spec authors had begun numbering theirs. It saw 91 of
+  // 149 posture-carrying specs and silently skipped 58 — printing "clean" about
+  // a corpus it had never read. Nobody made a mistake; the population drifted
+  // under the instrument, and there is no diff showing the moment it broke.
+  //
+  // The matcher was widened, which fixes THAT drift. This fixes the READING,
+  // which is the part that generalises: "clean" is a sentence nobody questions,
+  // and "clean — 0 findings across 149 spec(s), 91 carrying a posture section"
+  // is one somebody does. A shrinking denominator beside a reassuring word is
+  // the cheapest thing that would have surfaced the original bug without anyone
+  // auditing the matcher, and it costs a line.
+  //
+  // `unreadable` is counted rather than swallowed for the same reason: a file
+  // that could not be read is not a file with no findings.
   const allFindings = [];
+  let scanned = 0;
+  let withPosture = 0;
+  let unreadable = 0;
   for (const file of targets) {
     let text;
     try {
       text = fs.readFileSync(file, 'utf8');
     } catch {
+      unreadable += 1;
       continue;
     }
+    scanned += 1;
+    if (findPostureSection(text)) withPosture += 1;
     const { findings } = gradeMachineLocalMarkers(text);
     for (const f of findings) allFindings.push({ file: path.relative(ROOT, path.resolve(file)), ...f });
   }
+  const population = { scanned, withPosture, unreadable, findings: allFindings.length };
+  const denominator =
+    `${scanned} spec(s) scanned, ${withPosture} carrying a posture section` +
+    (unreadable > 0 ? `, ${unreadable} UNREADABLE` : '');
 
   if (json) {
-    process.stdout.write(JSON.stringify({ findings: allFindings, strict }, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({ findings: allFindings, population, strict }, null, 2) + '\n');
   } else if (allFindings.length === 0) {
-    console.log('lint-machine-local-justification: clean — no undefended or malformed markers.');
+    console.log(`lint-machine-local-justification: clean — no undefended or malformed markers (${denominator}).`);
   } else {
     const header = strict
       ? 'lint-machine-local-justification: FINDINGS (strict — blocking):'
@@ -591,7 +618,7 @@ function main() {
       console.error(`      ${f.message}`);
     }
     console.error(
-      `\n  ${allFindings.length} finding(s). Standard A: docs/STANDARDS-REGISTRY.md ` +
+      `\n  ${allFindings.length} finding(s) — ${denominator}. Standard A: docs/STANDARDS-REGISTRY.md ` +
         `("An Instar Agent Is Always a Multi-Machine Entity").`,
     );
   }

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-23T19:43:01.712Z",
-  "instarVersion": "1.3.1193",
+  "generatedAt": "2026-08-24T00:25:20.165Z",
+  "instarVersion": "1.3.1194",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1193",
+  "packageVersion": "1.3.1194",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "f0abeb280648b0f2918db12357309dcd45d2e6adfff2c41063df273544496145",
+  "sha256": "682c4fe7ea234c958ab4c7c34ca753fc73b5758a613693ca0b86f2d608bf6a32",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1193"
+  "packageVersion": "1.3.1194"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
   "articleCount": 90,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1193"
+  "packageVersion": "1.3.1194"
 }

package/upgrades/1.3.1194.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-machine-local-justification.js` reports its population beside its verdict — specs scanned, specs carrying a posture section, and unreadable files — on the clean path, the findings path, and as `population` in `--json`. Unreadable files are counted rather than skipped silently.
+
+Zero behaviour change: no verdict, threshold or exit code moves.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+On 2026-08-21 this gate was found matching its section heading by exact text while authors had begun numbering theirs. It saw 91 of 149 posture-carrying specs, silently skipped 58 — including the replicated-store foundation, the mesh self-heal spec, the secure-pairing spec and the standards-registry spec — and printed `clean` about a corpus it had never read. Widening the matcher fixed that drift; this fixes the reading, which is the part that generalises to the next drift.
+
+40 tests, including the property the incident turned on: a one-file run and a two-file run must not print the same sentence. Also pinned: the denominator on the FINDINGS path (where a shrunken population is most dangerous — a reader sees findings and assumes the sweep was whole), and an unreadable file counted rather than swallowed.
+
+First live output: `135 finding(s) — 1818 spec(s) scanned, 133 carrying a posture section`.
+
+## Known Limits
+
+A denominator does not DETECT drift; it makes drift legible to a human reading the output. If nobody reads it, it buys nothing. An automated ratchet on the population would be the stronger control and is not built here.
+
+The historical comment says 149 posture-carrying specs; this measures 133. **Drift is ruled out** — three independent methods (this lint, a peer's `git grep`, and a third regex pass) all return 133, including at `c465a94ef`, the widening commit itself, with the count unmoved across the two commits since. The population is not shrinking under the gate. What produced 149 remains unmeasured and no claim is made between the candidates.
+
+No other gate in this repository was audited for the same defect, and nothing enumerates the gates that print a reassuring word with no scale.

package/upgrades/lint-reports-its-denominator.eli16.md

@@ -0,0 +1,44 @@
+# Saying how much was checked, not just that it passed — Plain-English Overview
+
+## The problem in one breath
+
+A safety check in this project spent an unknown period reporting "clean" about documents it had never opened. It found the section it cared about by matching a heading word-for-word, and authors had started numbering their headings. It quietly saw 91 documents out of 149 and skipped 58 — including some of the most important ones — and said the same reassuring word it says when everything really is fine.
+
+## What already exists
+
+That matching bug was fixed on the 21st. The check now finds numbered headings properly.
+
+## What this adds
+
+The check now says **how much it looked at**, not only what it found.
+
+Before: `clean`
+After: `clean — 0 findings across 149 documents, 91 carrying the section we grade`
+
+## Why that matters more than it sounds
+
+Fixing the matcher fixes that one drift. It doesn't fix the next one. The set of documents can shrink again for reasons nobody records, because no author does anything wrong — and the verdict stays the single most comforting word available.
+
+"Clean" is a sentence nobody questions. "Clean, 91 of 149" is a sentence somebody does. A shrinking number next to a reassuring word is the cheapest thing that would have caught the original problem without anyone going and auditing the checker, and it costs one line.
+
+## The safeguards
+
+**Nothing can newly fail.** Every verdict and exit code is identical; only the wording changes.
+
+**A file that couldn't be opened is counted, not skipped.** A document that failed to load is not a document with no problems — silently dropping it is the same defect one level down.
+
+**The tests pin the point, not the wording:** a run over one document and a run over two must not print the same sentence. That's the property the whole incident turned on.
+
+## What ships when
+
+Immediately. Nothing to decide, no setting, no risk.
+
+## What you actually need to decide
+
+Nothing — and the one loose number has since been chased down, which is worth reporting because it is the change doing its job.
+
+On the first run the new count (133) disagreed with a number written in an old comment (149). The worrying reading was that sixteen documents had quietly lost the section nobody was checking. **That is now ruled out.** Two other people measured it different ways and both got 133 — including at the exact moment the old comment was written. Nothing has been slipping away.
+
+What nobody has worked out is where 149 came from. A different branch, a different way of counting, or a number that was never right. Three possibilities, none of them picked, because guessing between them would be the same habit this change exists to break.
+
+One small thing worth keeping: my own quick check first said 131, not 133. The difference was capital letters — two documents write "Posture" rather than "posture". Two measurements disagreeing is information; averaging them or taking the nicer one would have been exactly the mistake.

package/upgrades/side-effects/lint-reports-its-denominator.md

@@ -0,0 +1,89 @@
+# Side-Effects Review — the marker lint reports its population beside its verdict
+
+**Version / slug:** `lint-reports-its-denominator`
+**Date:** `2026-08-23`
+**Author:** `echo`
+**Second-pass reviewer:** `peer session (echo-fb, W24) — the structural remedy is theirs; the worked example is mine`
+
+## Summary of the change
+
+`scripts/lint-machine-local-justification.js` now prints how many specs it scanned and how many carried a posture section, on both the clean and the findings path, and exposes the same counts as `population` in `--json`. Files it could not read are COUNTED, not skipped silently.
+
+## Why — the incident this is the reading-side fix for
+
+On 2026-08-21 this gate was found matching its section heading by exact text while spec authors had begun numbering theirs (`## 8. Multi-machine posture`). It saw **91 of 149** posture-carrying specs and silently skipped **58** — including the replicated-store foundation, the mesh self-heal spec, the secure-pairing spec, and the standards-registry spec itself — while printing `clean` about a corpus it had never read.
+
+From the fix's own comment: *"Nobody had to make a mistake; you just had to number your heading."*
+
+Widening the matcher fixed **that** drift. It does not fix the next one. The population can shrink again for reasons no diff records, because no author does anything wrong — and the verdict stays the single most reassuring word available. `clean` is a sentence nobody questions. `clean — 0 findings across 149 spec(s), 91 carrying a posture section` is one somebody does.
+
+## Decision-point inventory
+
+None. This changes only what the gate SAYS. Every verdict, threshold and exit code is byte-identical.
+
+## 1. Over-block
+
+Impossible: no code path can newly fail. `--strict` still exits non-zero on exactly the same condition (`allFindings.length > 0`).
+
+## 2. Under-block
+
+Unchanged, and worth being precise: a denominator does not detect drift. It makes drift **legible to a human who reads the output**. If nobody reads it, it buys nothing. It is deliberately not sold as a detector — an automated ratchet on the population would be the stronger control and is not built here.
+
+## 3. Level-of-abstraction fit
+
+Three counters in the CLI's existing loop. No new file, no new invocation, no new dependency. It is one line of output.
+
+## 4. Signal vs authority compliance
+
+Compliant and unchanged. The lint is a report-first signal; this makes the signal more honest about its own reach.
+
+## 4b. Judgment-point check
+
+None. Three integers.
+
+## 5. Interactions
+
+- `findPostureSection` is now called once more per file to count coverage. Pure, no I/O, negligible.
+- The `--json` shape GAINS a `population` key. Additive; nothing reads it yet.
+- The self-wiring contract does not pin this script, so nothing else moves.
+
+## 6. External surfaces
+
+None.
+
+## 6b. Operator-surface quality
+
+The operator never runs this. The audience is whoever reads a CI log — and the incident proves that reader was previously given a reassuring word with no scale attached.
+
+## 7. Multi-machine posture
+
+`unified` — trivially. A pure counter in a stateless CLI.
+
+## 8. Rollback cost
+
+Three counters and a string. Reverting restores a verdict with no scale attached, which is the condition the incident occurred under.
+
+## Conclusion
+
+Ship. Zero behaviour change, one line of output, and it addresses the reading-side half of a defect that cost this repository 39% of its posture coverage for an unknown period.
+
+## Evidence pointers
+
+- 40 tests, including: the denominator appears on the clean path AND the findings path (the failing path is where a shrunken population is most dangerous — a reader sees findings, assumes the sweep was whole, and never asks how far it reached); the JSON `population` shape; an unreadable file COUNTED rather than swallowed; and the property the incident turned on — **a one-file run and a two-file run must not print the same sentence**.
+- First real output on the live corpus: `135 finding(s) — 1818 spec(s) scanned, 133 carrying a posture section`.
+
+## The discrepancy this surfaced on its first run — and what three instruments then established
+
+The historical comment records **149** posture-carrying specs; this measures **133**. That gap was reported as fully unresolved when this branch was first pushed. It has since been narrowed by two further measurements, and the narrowing is recorded here rather than folded silently into the original text.
+
+**DRIFT IS RULED OUT — the alarming reading is disconfirmed.** A peer session (echo-fb, W24) measured by an independent method (`git grep`, not this lint's regex) and got 133 at HEAD *and* 133 at `c465a94ef`, the widening commit itself, with only two commits touching `docs/specs` in between and the count unmoved. I then reproduced that with a third method: 133 at `c465a94ef`, 133 at `upstream/main`, control on an invented token 0, control on a common token 1811 of 1818.
+
+So the count was **already 133 when the comment claiming 149 was written**. Sixteen specs did not silently lose their posture section.
+
+**A 2-file disagreement between my third method and the other two, resolved rather than averaged.** My first pass returned 131. The difference is case: my throwaway regex was case-sensitive on the second word, while the lint's matcher carries `/i`. The two specs are `matrix-cell-operator-cancel.md` and `playwright-profile-registry.md`, whose headings capitalise "Posture". 133 is correct and matches the lint. Recorded because a two-instrument disagreement is information, and resolving it by preference would have been the error this whole change is about.
+
+**Still unmeasured: what produced 149.** A different branch, a method nobody has guessed, or a figure that was never right. Three candidates, none distinguished, and no claim made between them. What is now measured is the part that mattered — the population is not shrinking under the gate.
+
+## Class-Closure Declaration (display-only mirror)
+
+The class is "a verdict reported without its scale." Closed for this gate. NOT closed generally — no other gate in this repository was audited for it, and nothing enumerates the gates that print a reassuring word with no denominator. That sweep is the real work and is not done here.