instar 1.3.1157 → 1.3.1159

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

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1157",
+  "packageVersion": "1.3.1159",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "94029728ae76297bbe85baa1e37fd5985de80887bb4432afa090612a0a6da69c",
+  "sha256": "64b362d2e7aed4d92d9e9948a954ae1c099930efc5972c89842953e81cfd36ff",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1157"
+  "packageVersion": "1.3.1159"
 }

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

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1157"
+  "packageVersion": "1.3.1159"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1157",
+  "version": "1.3.1159",
   "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-no-direct-url-log.js

@@ -11,6 +11,26 @@
  * Conservative by design: it flags the two concrete shapes we know leak, not
  * every URL log. The redactUrl module + its tests are exempt.
  *
+ * SCOPE, split by whether the match detects the prohibited FACT or a SPELLING
+ * of it (the distinction that decides which half is worth widening):
+ *
+ *   - CREDENTIALED_URL_LITERAL is the FACT. A `user:pass@` inside a URL literal
+ *     IS the leak, whatever it is called or where it is logged. So resolving a
+ *     split literal is a real closure, not a bigger net: as of 2026-08-15 the
+ *     line is scanned with adjacent string concatenations folded, because
+ *     `"https://user:" + "tok@host"` leaked exactly as much as the one-piece
+ *     form and was invisible. Folding joins only ADJACENT literals of the same
+ *     quote style and invents no text.
+ *
+ *   - RISKY_URL_VAR_LOG is a SPELLING. It matches five variable names logged
+ *     through `console.*`. Renaming the variable (`originUrl`, `endpoint`) or
+ *     using any other sink (`logger.info`) defeats it — both measured. Growing
+ *     the name list would make the net finer while leaving the judgment inside
+ *     the pattern, so it is deliberately NOT widened here. The right repair is
+ *     to demote it from decider to candidate-gatherer and put the weighing
+ *     downstream; that changes the check's authority and belongs in a spec, not
+ *     in a regex edit.
+ *
  * Exit 0 = clean. Exit 1 = at least one offending site (printed).
  */
 
@@ -29,6 +49,23 @@ const EXEMPT = [
 /** A literal `scheme://user:pass@` in a string that is being logged. */
 const CREDENTIALED_URL_LITERAL = /['"`][a-z][a-z0-9+.-]*:\/\/[^/@'"`\s]+:[^/@'"`\s]+@/i;
 
+/**
+ * Fold `"a" + "b"` (adjacent string literals, same quote style) into `"ab"` so a
+ * credentialed URL split across a concatenation is scanned as the string it
+ * actually builds. Only literal+literal joins are folded — a variable operand
+ * ends the fold, so nothing is invented and no non-literal is assumed.
+ */
+export function collapseConcatenation(line) {
+  let out = line;
+  for (let i = 0; i < 8; i += 1) {
+    const next = out.replace(/(['"])((?:\\.|(?!\1)[^\\])*)\1\s*\+\s*(['"])((?:\\.|(?!\3)[^\\])*)\3/g,
+      (_m, q1, a, _q2, b) => `${q1}${a}${b}${q1}`);
+    if (next === out) break;
+    out = next;
+  }
+  return out;
+}
+
 /** console.* logging a variable named like a clone/remote URL without redactUrl on the same line. */
 const RISKY_URL_VAR_LOG = /console\.(log|error|warn|info)\([^)]*\b(repoUrl|cloneUrl|remoteUrl|pushUrl|gitUrl)\b/;
 
@@ -45,14 +82,32 @@ function walk(dir, out = []) {
   return out;
 }
 
+/**
+ * The scan, callable. Returns the offender list instead of exiting, so the
+ * behaviour can be unit-tested.
+ *
+ * This module previously exported nothing, so running the whole scan at module
+ * scope and calling process.exit() was harmless. Adding an export above makes
+ * that live: importing it to test the fold would run the repo scan and kill the
+ * test process the moment the repo had a real violation. Hence the
+ * direct-invocation guard at the bottom.
+ */
+// `srcDir`/`rootDir` default to this repo, so the shipped CLI behaviour is
+// unchanged. They exist so the scanner can be driven over a throwaway tree in a
+// test WITHOUT planting a probe file inside `src/` — planting one there both
+// trips SourceTreeGuard (which refuses any delete inside the instar source
+// tree) and is visible to every other test running at the same time.
+export function scanForCredentialedUrlLogs(srcDir = SRC, rootDir = ROOT) {
 const offenders = [];
-for (const file of walk(SRC)) {
-  const rel = path.relative(ROOT, file);
+for (const file of walk(srcDir)) {
+  const rel = path.relative(rootDir, file);
   if (EXEMPT.includes(rel)) continue;
   const lines = fs.readFileSync(file, 'utf-8').split('\n');
   lines.forEach((line, i) => {
     const hasRedact = line.includes('redactUrl') || line.includes('redactUrlsInText');
-    if (CREDENTIALED_URL_LITERAL.test(line)) {
+    // The FACT half is tested against the folded line; the SPELLING half is
+    // tested against the raw line exactly as before (unchanged behaviour).
+    if (CREDENTIALED_URL_LITERAL.test(collapseConcatenation(line))) {
       offenders.push(`${rel}:${i + 1}  credentialed-URL literal: ${line.trim().slice(0, 100)}`);
     } else if (RISKY_URL_VAR_LOG.test(line) && !hasRedact) {
       offenders.push(`${rel}:${i + 1}  logs a clone/remote URL var without redactUrl(): ${line.trim().slice(0, 100)}`);
@@ -60,11 +115,18 @@ for (const file of walk(SRC)) {
   });
 }
 
-if (offenders.length > 0) {
-  console.error('[lint-no-direct-url-log] credentialed-URL logging detected:');
-  for (const o of offenders) console.error(`  - ${o}`);
-  console.error('\nRoute the URL through redactUrl()/redactUrlsInText() from src/core/redactUrl.ts before logging.');
-  process.exit(1);
+return offenders;
+}
+
+// Only scan + exit when RUN, never when imported (see the note above).
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  const offenders = scanForCredentialedUrlLogs();
+  if (offenders.length > 0) {
+    console.error('[lint-no-direct-url-log] credentialed-URL logging detected:');
+    for (const o of offenders) console.error(`  - ${o}`);
+    console.error('\nRoute the URL through redactUrl()/redactUrlsInText() from src/core/redactUrl.ts before logging.');
+    process.exit(1);
+  }
+  console.log('[lint-no-direct-url-log] ✓ no credentialed-URL logging found');
+  process.exit(0);
 }
-console.log('[lint-no-direct-url-log] ✓ no credentialed-URL logging found');
-process.exit(0);

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-15T03:30:44.745Z",
-  "instarVersion": "1.3.1157",
+  "generatedAt": "2026-08-15T04:46:02.884Z",
+  "instarVersion": "1.3.1159",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

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

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1157",
+  "packageVersion": "1.3.1159",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "94029728ae76297bbe85baa1e37fd5985de80887bb4432afa090612a0a6da69c",
+  "sha256": "64b362d2e7aed4d92d9e9948a954ae1c099930efc5972c89842953e81cfd36ff",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1157"
+  "packageVersion": "1.3.1159"
 }

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

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1157"
+  "packageVersion": "1.3.1159"
 }

package/upgrades/1.3.1158.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-no-direct-url-log.js` now folds adjacent string-literal
+concatenations before testing its credentialed-URL pattern, so a
+`scheme://user:pass@host` literal split across a `+` is detected as the string it
+actually builds. The sibling variable-name pattern is unchanged.
+
+The module also gains a direct-invocation guard: it now exports its scan, and
+without the guard importing it would run the whole repo scan and `process.exit`.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- 3 new defect cases fail against the shipped fold behaviour; 13 controls pass
+  both ways. Source restored byte-identical after the mutation.
+- Four anti-over-block fixtures return identical verdicts under the shipped and
+  fixed lint — zero new false positives, measured rather than argued.
+- Real tree exit 0 before and after.

package/upgrades/1.3.1159.md

@@ -0,0 +1,40 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The two vitest globalSetup files that prepare the packed standards-registry asset
+(`tests/setup/build-dist.globalSetup.ts` and
+`tests/setup/ensure-registry-asset.globalSetup.ts`) decided whether to regenerate it
+on PRESENCE alone — `if (outputs.every(exists)) return`. An asset generated from an
+older revision of `docs/STANDARDS-REGISTRY.md` was therefore never regenerated.
+
+Both now consult a shared `registryAssetIsStale()` helper that compares the oldest
+output's mtime against the newest input's (`docs/STANDARDS-REGISTRY.md`,
+`docs/standards-registry-floor.json`, `package.json`) — the same shape the sibling
+`ensureDistBuilt()` twelve lines above already used.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- Measured 2026-08-15: in a checkout whose asset was generated at 17:59 from a source
+  three hours newer, `standards-registry-asset`, `standards-enforcement-auditor` and
+  `standards-coverage-route` failed with 8 assertions. Regenerating the asset alone
+  made all 77 pass.
+- `tests/unit/registry-asset-freshness.test.ts` — 9/9.
+- Negative controls, both fired: reverting the comparison fails THE DEFECT case
+  (1 failed / 8 passed); reverting one call site to the presence check fails the
+  wiring case, naming the file. Both sources restored byte-exact.
+- The wiring guard matches the MODULE SPECIFIER, not the imported identifier, so an
+  aliased import cannot defeat it — the alias blindness found in an invariant test
+  earlier this week.
+- `tsc --noEmit` exit 0; full lint chain exit 0 across 45 lints.

package/upgrades/side-effects/registry-asset-freshness.md

@@ -0,0 +1,76 @@
+# Side-effects review — registry asset freshness
+
+## The change
+
+Two vitest globalSetup files decided whether to regenerate the packed
+standards-registry asset by asking only whether its outputs EXIST. Both now share a
+`registryAssetIsStale()` helper that compares the oldest output's mtime against the
+newest input's. Test-only; no runtime surface.
+
+## Review answers
+
+1. **Over-block.** This is the dominant risk and it got the most care, because the
+   check runs at the START of every suite and an over-eager rule regenerates on every
+   run. Three conservative cases, each with its own test: equal mtimes are NOT stale;
+   no readable input is NOT stale; an empty output list is NOT stale. Measured cost of
+   a genuine regeneration is one generator invocation (~1s), and it self-limits — a
+   freshly written asset is newer than its inputs, so the next run skips.
+
+2. **Under-block.** mtime is a proxy for content, not content itself. A source edited
+   and reverted leaves a newer mtime and triggers one unnecessary regeneration
+   (harmless). A content-identical touch does the same. Conversely, a filesystem that
+   does not preserve mtimes, or a checkout that sets all mtimes equal, would report
+   fresh when stale. A content hash would be exact — the generator already writes a
+   `sha256` into its metadata — and that is the stronger version of this fix. NOT done
+   here: it means reading and hashing a 450KB document on every suite start, where the
+   mtime compare is four `stat` calls, and the sibling `ensureDistBuilt()` this mirrors
+   uses mtimes too. Stated rather than implied.
+
+3. **Level-of-abstraction fit.** Correct layer: the setup layer is where every test
+   file inherits the guarantee. The file's own history says this explicitly — a
+   per-file `beforeAll` bootstrap was found to be invisible to the next file that
+   needed it.
+
+4. **Signal vs authority.** Not a gate. It decides whether to run a generator; it
+   blocks nothing and rejects no input.
+
+5. **Interactions.** `ensureRegistryAsset()` must still run AFTER `ensureDistBuilt()`
+   (the generator imports from `dist/`). Unchanged — only the early-return predicate
+   moved. The exported `ensureRegistryAsset(root)` keeps its signature, so the
+   production-generator parity ratchet that imports it is unaffected.
+
+6. **External surfaces.** None. Test setup only; nothing ships to an agent or a user.
+
+7. **Multi-machine posture.** Machine-local BY DESIGN — a per-checkout build artifact.
+   There is nothing to replicate: each checkout generates its own copy, and the whole
+   defect was one checkout trusting its own stale copy.
+
+8. **Rollback cost.** Revert the commit. The helper is additive; the two call sites
+   return to a presence check.
+
+## Class closure — what this does NOT close
+
+- **Only these two sites.** A sweep of `tests/setup/` and `scripts/` for
+  regenerate-on-presence guards found exactly these two making a regeneration decision
+  on existence alone; the other `existsSync` hits are ordinary existence guards, not
+  regeneration decisions. The wiring test pins both and fails if either drifts, but it
+  knows only about setups that generate THIS asset.
+- **`src/data/builtin-manifest.json`** is named in the generator's own comment as
+  having a related defect (generated only into `src/data/` while its reader resolves
+  module-relative from `dist/data/`). Different feature, different defect, untouched.
+- **mtime is not content** — see review answer 2.
+
+## Evidence
+
+- `tests/unit/registry-asset-freshness.test.ts` — 9/9 green.
+- Negative controls, BOTH fired and both restored byte-exact: reverting the comparison
+  fails THE DEFECT case (1 failed / 8 passed — the 8 passing are the controls, which is
+  what makes them controls); reverting one call site to the presence check fails the
+  wiring case and names the file.
+- Observed live: running the new test in a fresh checkout regenerated the asset
+  ("88 articles → src/data + dist/data"). Under the presence check it would have
+  skipped, because the outputs existed.
+- The originating measurement: three test files / eight assertions failing against a
+  three-hour-stale asset; regeneration alone made all 77 pass.
+- `tsc --noEmit` exit 0 (run via the real binary — `npx tsc` here is intercepted by a
+  shim that exits 0 without typechecking). Full lint chain exit 0 across 45 lints.

package/upgrades/side-effects/url-log-lint-split-literal.md

@@ -0,0 +1,131 @@
+# Side effects — url-log lint resolves split credentialed literals
+
+## 1. Over-block
+
+The dominant risk: this lint fails builds, so flagging correct code is more
+expensive than missing a case (a noisy check gets switched off, and then it
+guards nothing).
+
+Bounded four ways:
+- the fold joins only ADJACENT string literals of the SAME quote style;
+- a variable operand ENDS the fold, so no runtime value is ever assumed;
+- the fold is bounded to 8 passes and returns the input unchanged if it cannot
+  make progress;
+- it can only ever JOIN existing literal text — a test pins that the folded line
+  is never longer than the input, so the fold cannot synthesise content.
+
+Measured, not asserted: four anti-over-block fixtures were run against BOTH the
+shipped lint and the fixed lint and returned identical verdicts. The real tree
+lints clean before and after.
+
+Note one verdict that looks like over-block and is not: a hardcoded
+`https://user:tok@host` literal is flagged even when the log call redacts it.
+That is pre-existing behaviour (the literal branch never consulted the redaction
+check) and it is correct — a credential hardcoded in source is a leak regardless
+of what happens at log time. Verified identical under the shipped lint.
+
+## 2. Under-block — what this does NOT close
+
+Stated by kind, because the two halves of this lint fail differently:
+
+- **The variable-name half is untouched and still defeatable.** `RISKY_URL_VAR_LOG`
+  matches five names through `console.*`. A renamed variable (`originUrl`) and a
+  different sink (`logger.info`) both evade it — measured. This is deliberate:
+  that pattern matches a SPELLING correlated with the behaviour rather than the
+  behaviour, so widening the list makes a finer net and no more of a policy. The
+  correct repair is to demote it from decider to candidate-gatherer with the
+  weighing downstream, which changes the check's authority and belongs in a spec.
+- Cross-line construction (a credentialed URL assembled over several statements)
+  is not resolved — that needs dataflow, not a line-scoped fold.
+- A credentialed URL arriving from config, argv, or another module is invisible
+  to any source-text check.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. A `user:pass@` inside a URL literal is an exact lexical fact about
+our own source, which is what a deterministic source lint is for. The runtime
+redaction funnel (`src/core/redactUrl.ts`) remains the authority for URLs whose
+credentials only exist at runtime; this lint does not and cannot replace it.
+
+## 4. Signal vs authority
+
+Unchanged. The lint holds the same blocking authority it already had, over a
+strictly more accurate view of the same prohibited fact. No new authority, no
+new decision class, no runtime surface.
+
+## 5. Interactions
+
+None. No other check reads this one's output. The direct-invocation guard is
+additive — it only changes behaviour on `import`, which nothing did before,
+because the module exported nothing until now.
+
+## 6. External surfaces
+
+None. CI-only. No runtime code path, no API, no user-visible behaviour.
+
+## 7. Multi-machine posture
+
+Not applicable — machine-local by design. This is a build-time check over source
+text in a checkout; it holds no state and replicates nothing.
+
+## 8. Rollback cost
+
+Revert the commit. The lint returns to its previous matching behaviour; nothing
+persists and no state migrates.
+
+---
+
+## Addendum — CI caught a guard conflict in the TEST, and the fix is a redesign not a workaround
+
+**What CI found.** `Unit Tests shard 1/4` failed on node 20 AND node 22 (same shard both versions, so
+not a flake): `SourceTreeGuardError: Refusing to run ... (requested dir:
+.../src/core/__urlLogLintProbe.ts, resolved git root: ...)`. The test planted a probe file inside
+`src/` so the real lint would scan it, then removed it through `SafeFsExecutor` — and SourceTreeGuard
+refuses ANY delete inside the instar source tree (the 2026-04-22 incident class).
+
+**Why it passed locally and failed in CI is the honest part:** I did not establish that, and I am not
+guessing at it. What I did establish is that the test design was wrong on its own terms regardless of
+which environment surfaces it.
+
+**Two defects in that design, and the second is the one I had not considered:**
+1. It performs a destructive operation inside the source tree — exactly what the guard exists to stop.
+   Routing it through the audited funnel satisfied the destructive-op lint and walked into a different
+   guard. Satisfying one guard is not evidence about another.
+2. A probe file sitting at `src/core/__urlLogLintProbe.ts` is **visible to every other suite running at
+   the same time**. That is shared mutable state in a shared tree, and it would have been a latent
+   flake source for other people's tests, not just mine.
+
+**The fix.** `scanForCredentialedUrlLogs()` now takes optional `srcDir`/`rootDir` that DEFAULT to this
+repo, so the shipped CLI behaviour is unchanged. The test scans a throwaway temp tree instead. Nothing
+is written into `src/` and nothing is deleted inside the source tree.
+
+### Review answers for this addendum
+
+1. **Over-block.** None new. The CLI path takes the defaults and is behaviourally identical — verified
+   by running it before and after the change (`exit 0` both times) and by the real-tree control below.
+2. **Under-block.** One thing genuinely got WEAKER and I am naming it rather than letting it pass: the
+   defect cases now drive the exported scanner, so they no longer exercise the CLI's
+   offender-printing + `process.exit(1)` path end to end. A new test keeps the exit-code path covered
+   in the passing direction (`the shipped CLI still exits 0 on the clean tree`), but the failing
+   direction of the CLI wrapper is uncovered. That wrapper is eight lines and unchanged by this PR.
+3. **New surface introduced.** The scanner now trusts a caller-supplied root. A caller could point it
+   at an empty directory and receive a clean verdict — but this is a lint's test seam, not a decision
+   authority, and the CLI never passes arguments. Named because "a scan over nothing reports clean" is
+   the exact defect I fixed in `lint-no-direct-destructive` earlier this window; here it is reachable
+   only by a caller that deliberately supplies the wrong root.
+4. **Signal vs authority.** Unchanged — still a deterministic detector with a build-failing exit code.
+5. **Interactions.** Removes an interaction rather than adding one: no more shared probe file inside
+   `src/` for concurrent suites to observe.
+6. **Multi-machine posture.** Machine-local by design — a lint script and its unit test.
+7. **Rollback cost.** Revert the commit; the parameters are additive with defaults.
+
+### Evidence
+
+- `tests/unit/url-log-lint-split-literal.test.ts` — **17/17 green** (16 before; +1 for the CLI exit path).
+- **Negative control re-run after the redesign, because rewriting HOW a test drives its subject can
+  quietly turn it into a check that cannot fail:** removing the fold from the decision makes exactly
+  the **3 defect cases fail**, 14 pass both ways. Source restored byte-exact (sha match, 0 markers).
+- Real-tree anti-over-block control is now STRONGER: it asserts `scanForCredentialedUrlLogs()` returns
+  `[]` under the real defaults, instead of asserting a temp tree with one inert line is clean.
+- `tsc --noEmit` exit 0 (run via the real binary — `npx tsc` here is a shim that exits 0 without
+  typechecking). Full lint chain exit 0.