harness-everything 0.34.0 → 0.36.0

package/ci/mechanism-pr334-r3-headings.test.js

@@ -0,0 +1,268 @@
+'use strict';
+
+// PR #334 round 3 — heading boundary regressions in section extraction.
+//
+// extractSection in doc-obligations.js recognized only column-zero ATX headings. A
+// CommonMark-valid Decision headings indented 1..3 spaces were invisible, so a real
+// Decision edit reported quality-review and conflict-check N/A. Related boundary
+// controls cover Setext Decision headings and tab-indented fence lookalikes.
+//
+// Authoritative rule: https://spec.commonmark.org/0.31.2/#atx-headings
+//   * 0-3 ASCII spaces of indentation, then 1-6 "#", then a space/tab or end of line;
+//   * 4 spaces or a leading tab is code indentation, not a heading;
+//   * a closing sequence must be preceded by a space/tab.
+//
+// Scope is bounded to Decision section boundaries. This is not a CommonMark parser.
+// Fence and code boundaries are exercised as regression controls.
+//
+// Every case runs the full deriveDocFacts -> deriveDocObligations pipeline. Expectations
+// come from the spec and the D6.5 normative-change rule, not from the implementation.
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const helper = require('./test-helper');
+
+const modulePath = path.join(__dirname, '..', 'harness-everything', 'scripts', 'doc-obligations.js');
+const fixtureDir = path.join(__dirname, 'fixtures', 'doc-obligations', 'derive');
+const CONFIG = JSON.parse(fs.readFileSync(path.join(fixtureDir, 'config.json'), 'utf8'));
+const ADR = 'docs/adr/GRPH-007.md';
+
+let deriveDocFacts;
+let deriveDocObligations;
+try {
+  ({ deriveDocFacts, deriveDocObligations } = require(modulePath));
+} catch (error) {
+  helper.check('pr334-r3-headings. derive module is available', false, error.message);
+}
+
+console.log('\n[pr334-r3-headings] ATX heading indentation in Decision section extraction...');
+
+function readFixture(caseName, side, file = 'GRPH-007.md') {
+  return fs.readFileSync(path.join(fixtureDir, caseName, side, 'docs', 'adr', file), 'utf8');
+}
+
+// Existing typo-decision fixture: one Decision body word changes "lint" -> "lnt".
+const TYPO_BASE = readFixture('typo-decision', 'base');
+const TYPO_CANDIDATE = readFixture('typo-decision', 'candidate');
+
+function adr(body) {
+  return ['---', 'id: GRPH-007', 'role: adr', 'status: accepted', '---', '# GRPH-007 Lint first', '', body, ''].join('\n');
+}
+
+function replaceOnce(text, from, to) {
+  assert.strictEqual(text.split(from).length, 2, `fixture text contains exactly one "${from}"`);
+  return text.replace(from, to);
+}
+
+function indentDecision(text, prefix) {
+  return replaceOnce(text, '## Decision', `${prefix}## Decision`);
+}
+
+function applicability(base, candidate, file = ADR) {
+  const result = deriveDocFacts({
+    base: { files: { [file]: base } },
+    candidate: { files: { [file]: candidate } },
+    config: CONFIG
+  });
+  const obligations = deriveDocObligations(result.facts);
+  return new Map(obligations.map(item => [item.capability, item.applicability]));
+}
+
+// The normative capabilities must agree with each other; doc-lint and link-check always apply to a governed edit.
+function assertDecisionEdit(name, base, candidate, want, file = ADR) {
+  const map = applicability(base, candidate, file);
+  assert.strictEqual(map.get('doc-lint'), 'applicable', `${name}: doc-lint`);
+  assert.strictEqual(map.get('link-check'), 'applicable', `${name}: link-check`);
+  assert.strictEqual(map.get('quality-review'), want, `${name}: quality-review`);
+  assert.strictEqual(map.get('conflict-check'), want, `${name}: conflict-check`);
+}
+
+function checkCase(name, run) {
+  try {
+    run();
+    helper.check(name, true);
+  } catch (error) {
+    helper.check(name, false, error && error.message ? error.message : String(error));
+  }
+}
+
+// Matrix 1: indentation of the real Decision heading. 0-3 spaces are headings; 4 spaces and a leading tab are code.
+for (const [label, prefix] of [['0 spaces', ''], ['1 space', ' '], ['2 spaces', '  '], ['3 spaces', '   ']]) {
+  checkCase(`pr334-r3 indent matrix: Decision heading with ${label} is a heading; Decision edit is normative`, () => {
+    assertDecisionEdit(label, indentDecision(TYPO_BASE, prefix), indentDecision(TYPO_CANDIDATE, prefix), 'applicable');
+  });
+}
+
+for (const [label, prefix] of [['4 spaces', '    '], ['a leading tab', '\t']]) {
+  checkCase(`pr334-r3 indent matrix: Decision heading with ${label} is code, not a heading; the edit is non-normative`, () => {
+    assertDecisionEdit(label, indentDecision(TYPO_BASE, prefix), indentDecision(TYPO_CANDIDATE, prefix), 'N/A');
+  });
+}
+
+// Matrix 2: fences. Existing fixtures keep their behavior; an indented fenced fake heading stays ignored.
+for (const caseName of ['decision-fence-backtick', 'decision-fence-tilde']) {
+  checkCase(`pr334-r3 fence control: ${caseName} fixture still treats the real Decision as normative`, () => {
+    assertDecisionEdit(caseName, readFixture(caseName, 'base', 'GRPH-010.md'), readFixture(caseName, 'candidate', 'GRPH-010.md'), 'applicable', 'docs/adr/GRPH-010.md');
+  });
+}
+
+checkCase('pr334-r3 fence: a 3-space indented fenced "## Decision" is ignored; the real Decision edit stays applicable (not unknown)', () => {
+  const base = adr('## Context\n\nWe need lint.\n\n   ```md\n  ## Decision\n   ```\n\n## Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('indented fence', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 fence: an indented tilde fence does not hide the following 3-space Decision heading', () => {
+  const base = adr('## Context\n\nWe need lint.\n\n   ~~~md\n# Example\n   ~~~\n\n   ## Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('indented tilde fence', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 fence: a tab-indented fence-looking line does not hide a following Decision heading', () => {
+  const base = adr('## Context\n\nWe need lint.\n\n\t```md\n  ## Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('tab-indented opener', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 fence: a tab-indented closer inside a real fence does not expose a fake Decision heading', () => {
+  const base = adr('## Context\n\nWe need lint.\n\n```md\n  \t```\n## Decision\n\nFake text.\n```\n\n## Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('tab-indented closer', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 fence: a backtick in a backtick-fence info string invalidates the opener, so Decision is visible', () => {
+  const base = adr(['## Context', '', '```js `', '', '## Decision', '', 'Run lint first.'].join('\n'));
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('malformed backtick info', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 fence: a tilde-fence info string may contain a backtick and still hides its fake Decision', () => {
+  const base = adr(['## Context', '', '~~~js `', '## Decision', 'Fake text.', '~~~', '', '## Decision', '', 'Run lint first.'].join('\n'));
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('tilde info backtick', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 setext: a suspected standalone Setext Decision yields unknown, never N/A', () => {
+  const base = adr('## Context\n\nWe need lint.\n\nDecision\n--------\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('Setext Decision', base, candidate, 'unknown');
+});
+
+checkCase('pr334-r3 setext: a multiline Setext paragraph ending in "Decision" stays unknown rather than a false Decision section', () => {
+  const base = adr('## Context\n\nWe need lint.\n\nContext prose\nDecision\n--------\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('multiline Setext title', base, candidate, 'unknown');
+});
+
+checkCase('pr334-r3 setext: a Setext-looking Decision inside a fence is ignored', () => {
+  const base = adr('## Context\n\nWe need lint.\n\n```md\nDecision\n--------\nFake text.\n```\n\n## Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('Setext in fence', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 setext: an unsupported Setext boundary inside Decision yields unknown instead of guessing its paragraph scope', () => {
+  const base = adr('## Decision\n\nRun lint first.\n\nNext\n---\n\nLater.');
+  const candidate = base.replace('Next\n---', 'Next steps\n---');
+  assertDecisionEdit('unsupported Setext boundary', base, candidate, 'unknown');
+});
+
+checkCase('pr334-r3 thematic break: a rule after the ATX Decision remains inside the section', () => {
+  const base = adr('## Decision\n\n---\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('thematic break after ATX', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 thematic break: a rule after a fenced block does not turn its closing fence into a Setext heading', () => {
+  const base = adr('## Decision\n\n```js\nexample();\n```\n---\nUse A.');
+  const candidate = base.replace('Use A.', 'Use B.');
+  assertDecisionEdit('thematic break after fence', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 setext: four-space-indented Setext-looking text is code, not a Decision heading', () => {
+  const base = adr('## Context\n\nWe need lint.\n\n    Decision\n    --------\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('Setext in code', base, candidate, 'N/A');
+});
+
+// Matrix 3: section termination and inclusion.
+checkCase('pr334-r3 termination: a 3-space subsection (### Consequences) is included in the Decision section', () => {
+  const base = adr('   ## Decision\n\nRun lint first.\n\n   ### Consequences\n\nLint is cheap.');
+  const candidate = base.replace('Lint is cheap.', 'Lnt is cheap.');
+  assertDecisionEdit('subsection', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 termination: a 3-space same-level heading (## Next) ends the Decision section; an edit there is non-normative', () => {
+  const base = adr('   ## Decision\n\nRun lint first.\n\n   ## Next\n\nLint later.');
+  const candidate = base.replace('Lint later.', 'Lnt later.');
+  assertDecisionEdit('same-level terminator', base, candidate, 'N/A');
+});
+
+checkCase('pr334-r3 termination: a 1-space higher-level heading (# Appendix) ends the Decision section; an edit there is non-normative', () => {
+  const base = adr('   ## Decision\n\nRun lint first.\n\n # Appendix\n\nLint notes.');
+  const candidate = base.replace('Lint notes.', 'Lnt notes.');
+  assertDecisionEdit('higher-level terminator', base, candidate, 'N/A');
+});
+
+checkCase('pr334-r3 termination: an empty "##" heading line ends the Decision section; an edit after it is non-normative', () => {
+  const base = adr('   ## Decision\n\nRun lint first.\n\n##\n\nLint notes.');
+  const candidate = base.replace('Lint notes.', 'Lnt notes.');
+  assertDecisionEdit('empty terminator', base, candidate, 'N/A');
+});
+
+checkCase('pr334-r3 termination: a 4-space indented "## Example" is code and does not end the Decision section', () => {
+  const base = adr('   ## Decision\n\nRun lint first.\n\n    ## Example\n\nLint sample.');
+  const candidate = base.replace('Lint sample.', 'Lnt sample.');
+  assertDecisionEdit('code-indented non-terminator', base, candidate, 'applicable');
+});
+
+// Matrix 4: duplicate Decision headings are ambiguous, whatever the indentation.
+checkCase('pr334-r3 duplicate: a column-0 Decision plus a 2-space Decision is unknown, never N/A or applicable', () => {
+  const base = adr('## Decision\n\nRun lint first.\n\n  ## Decision\n\nOther.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('duplicate', base, candidate, 'unknown');
+});
+
+// Matrix 5: closing sequences and separators, per the ATX rule. Only space/tab separators and preceding-space closings count.
+checkCase('pr334-r3 closing: a 2-space "## Decision ##" closing sequence is the Decision heading', () => {
+  const base = adr('  ## Decision ##\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('closing', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 closing: "## Decision#" has no preceding space, so the title is "Decision#" and Decision is absent', () => {
+  const base = adr('## Decision#\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('glued hash', base, candidate, 'N/A');
+});
+
+checkCase('pr334-r3 separator: a tab after the hashes ("##\\tDecision") is a valid separator', () => {
+  const base = adr('##\tDecision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('tab separator', base, candidate, 'applicable');
+});
+
+checkCase('pr334-r3 separator: a no-break space after the hashes is not a CommonMark separator, so it is not a heading', () => {
+  const base = adr('## Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('nbsp separator', base, candidate, 'N/A');
+});
+
+checkCase('pr334-r3 separator: "##Decision" with no separator is not a heading (control)', () => {
+  const base = adr('##Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('no separator', base, candidate, 'N/A');
+});
+
+checkCase('pr334-r3 level: seven hashes is not an ATX heading (control)', () => {
+  const base = adr('####### Decision\n\nRun lint first.');
+  const candidate = base.replace('Run lint first.', 'Run lnt first.');
+  assertDecisionEdit('seven hashes', base, candidate, 'N/A');
+});
+
+// Positive control: the column-0 typo-decision fixture is unchanged by this fix.
+checkCase('pr334-r3 control: the existing column-0 typo-decision fixture stays normative', () => {
+  assertDecisionEdit('typo-decision', TYPO_BASE, TYPO_CANDIDATE, 'applicable');
+});
+
+helper.finish();

package/ci/portability-lint.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Test-Source Portability Lint
+ *
+ * The Windows CI matrix has failed on fixture paths that macOS/Linux never
+ * reject: a filename containing ':' and '"' (mechanism-2ay, run 39043848220)
+ * and a Windows device-namespace path (mechanism-2au, run 38760213406).
+ * This lint moves that failure class from "after push" to this local gate.
+ *
+ * Scanned: every .js file under ci/ (fixture creators, check scripts, tests).
+ *
+ * Rules, all requiring a whitespace-free single-token literal so prose,
+ * regex sources and message templates stay out of the net:
+ *   WIN_DEVICE_PATH     the literal begins with the \\.\ or \\?\ device
+ *                       namespace prefix
+ *   WIN_RESERVED_NAME   the literal, or a path segment of it, is CON PRN
+ *                       AUX NUL COM1-9 LPT1-9, with or without an extension
+ *   WIN_INVALID_CHAR    a path-like literal contains one of : * ? " < > |
+ *                       (clock-like 12:34 fragments are not counted; only
+ *                       verified URL/Node-specifier schemes with a value
+ *                       after the colon and wildcard-led glob segments are
+ *                       exempt, so bad:name.md and bad*name.md are flagged)
+ *
+ * The exemptions are contextual, and ci/mechanism-37-portability-lint.test.js
+ * holds the positive/negative corpus that locks them down.
+ *
+ * Known limits, kept deliberately narrow over noisy coverage: it does not
+ * flag spaced fixture names, trailing dots/spaces, bare single tokens
+ * without a path separator or extension (except reserved names), or
+ * invalid characters inside prose-like strings. Those still rely on review
+ * and the Windows CI matrix. A finding here is a tripwire, not proof of a
+ * Windows failure.
+ *
+ * Remedy: use a portable fixture name, platform-guard the code path, or mark
+ * one deliberate case with `portability-lint: allow <reason>` on its line.
+ *
+ * Usage: node ci/portability-lint.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SELF = path.resolve(__filename);
+const SCAN_ROOT = path.resolve(__dirname);
+const SKIP_DIRS = new Set(['fixtures', 'node_modules', '__pycache__']);
+const EXTENSIONS = new Set(['.js', '.cjs', '.mjs']);
+const PRAGMA = /portability-lint:\s*allow/;
+const RESERVED_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+const INVALID_CHARS = /[:*?"<>|]/;
+const WILDCARD_CHARS = /[*?]/g;
+const CLOCK_FRAGMENT = /\d{1,2}:\d{2}(?::\d{2}(?:\.\d+)?)?/g;
+const DEVICE_NAMESPACE = /^(\\\\|\\)[.?](\\|$)/;
+// A scheme is only exempt with a real authority (`https://...`) or as a
+// known Node/tooling/repo-data specifier (`node:assert/strict`,
+// `pkg:npm/...`, `HEAD:refs/heads/main`, `legacy:GRAPH-1@docs/x.md`). A bare
+// word before the colon (`bad:name.md`) is a filename, not a scheme.
+const URL_WITH_AUTHORITY = /^[a-z][a-z0-9+.-]*:\/\//i;
+const SPECIFIER_SCHEME = /^(node|pkg|https?|git\+https?|ssh|file|mailto|data|github|fallback-task|HEAD|legacy|human):/i;
+const DRIVE_PREFIX = /^[A-Za-z]:/;
+// Strings that open like regex sources rather than filenames: a char-class
+// or inline-group opener after a leading slash, a leading inline group, or a
+// leading backslash escape such as \s or \d.
+const REGEX_SOURCE = /^(?:\(\?[:=!]|\/\[|\/\(\?|\\[sSdDwWbB])/;
+// Markup tags, <placeholder> roots, desync tails, and `${...}` templates are
+// data under test, never fixture names.
+const DATAISH_PREFIX = /^[<>{}\[\]$]/;
+// A wildcard-led segment (`*.md`, `**`) marks the token as a glob pattern.
+const GLOB_SEGMENT = /^[*?]/;
+const REGEX_PREFIX_CHARS = '([{,;:=!&|?+-*%<>~^';
+const REGEX_KEYWORDS = /(?:^|[^\w$])(return|typeof|case|in|of|new|delete|void|instanceof)\s*$/;
+
+function extractLiterals(source) {
+  const literals = [];
+  let line = 1;
+  let i = 0;
+  const n = source.length;
+  while (i < n) {
+    const ch = source[i];
+    if (ch === '\n') {
+      line += 1;
+      i += 1;
+      continue;
+    }
+    if (ch === '/' && source[i + 1] === '/') {
+      const next = source.indexOf('\n', i);
+      i = next === -1 ? n : next;
+      continue;
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      let j = i + 2;
+      while (j < n && !(source[j] === '*' && source[j + 1] === '/')) {
+        if (source[j] === '\n') line += 1;
+        j += 1;
+      }
+      i = j + 2;
+      continue;
+    }
+    if (ch === '/' && regexPosition(source, i)) {
+      // Skip regex literals so quotes and brackets inside them never desync
+      // the scanner into reading code as a string.
+      let j = i + 1;
+      let inClass = false;
+      while (j < n) {
+        const c = source[j];
+        if (c === '\n') break;
+        if (c === '\\') {
+          j += 2;
+          continue;
+        }
+        if (c === '[') inClass = true;
+        else if (c === ']') inClass = false;
+        else if (c === '/' && !inClass) {
+          j += 1;
+          break;
+        }
+        j += 1;
+      }
+      i = j;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      const startLine = line;
+      let value = '';
+      let j = i + 1;
+      let closed = false;
+      while (j < n) {
+        const c = source[j];
+        if (c === '\n') break;
+        if (c === '\\') {
+          if (j + 1 >= n) break;
+          value += source[j + 1];
+          j += 2;
+          continue;
+        }
+        if (c === quote) {
+          closed = true;
+          break;
+        }
+        value += c;
+        j += 1;
+      }
+      if (closed) {
+        literals.push({ line: startLine, value });
+        i = j + 1;
+        continue;
+      }
+      // Unterminated on this line: treat the quote as plain text, rescan.
+      i += 1;
+      continue;
+    }
+    i += 1;
+  }
+  return literals;
+}
+
+function regexPosition(source, i) {
+  let k = i - 1;
+  while (k >= 0 && (source[k] === ' ' || source[k] === '\t')) k -= 1;
+  if (k < 0 || source[k] === '\n') return true;
+  if (REGEX_PREFIX_CHARS.includes(source[k])) return true;
+  return REGEX_KEYWORDS.test(source.slice(Math.max(0, k - 12), k + 1));
+}
+
+function looksPathLike(value) {
+  const s = value.trim();
+  if (!s || s.length > 300) return false;
+  if (/[\\/]/.test(s)) return true;
+  return /\.[A-Za-z0-9]{1,8}$/.test(s); // bare filename with extension
+}
+
+function pathSegments(value) {
+  const body = DRIVE_PREFIX.test(value) ? value.slice(2) : value;
+  return body.split(/[\\/]+/).filter(Boolean);
+}
+
+function analyzeLiteral(literal) {
+  const findings = [];
+  const value = literal.value.trim();
+  if (!value) return findings;
+  if (DEVICE_NAMESPACE.test(value)) {
+    findings.push({
+      rule: 'WIN_DEVICE_PATH',
+      detail: `literal begins with the ${value.slice(0, 3)} device-namespace prefix`,
+    });
+    return findings;
+  }
+  if (DATAISH_PREFIX.test(value)) return findings;
+  if (/\s/.test(value)) return findings; // prose, templates, patch bodies
+
+  const segments = pathSegments(value);
+  const glob = segments.some((segment) => GLOB_SEGMENT.test(segment));
+
+  if (RESERVED_NAME.test(value)) {
+    findings.push({
+      rule: 'WIN_RESERVED_NAME',
+      detail: `literal "${value}" is a reserved Windows name`,
+    });
+  } else if (looksPathLike(value)) {
+    for (const segment of segments) {
+      if (RESERVED_NAME.test(segment)) {
+        findings.push({
+          rule: 'WIN_RESERVED_NAME',
+          detail: `segment "${segment}" is a reserved Windows name`,
+        });
+      }
+    }
+  }
+
+  if (
+    looksPathLike(value) &&
+    !URL_WITH_AUTHORITY.test(value) &&
+    !SPECIFIER_SCHEME.test(value) &&
+    !REGEX_SOURCE.test(value)
+  ) {
+    // The drive-letter colon is portable; everything after it is not.
+    const withoutDrive = DRIVE_PREFIX.test(value) ? value.slice(2) : value;
+    const withoutClocks = withoutDrive.replace(CLOCK_FRAGMENT, '');
+    const scanned = glob ? withoutClocks.replace(WILDCARD_CHARS, '') : withoutClocks;
+    const invalid = scanned.match(INVALID_CHARS);
+    if (invalid) {
+      findings.push({
+        rule: 'WIN_INVALID_CHAR',
+        detail: `literal "${value}" contains '${invalid[0]}'`,
+      });
+    }
+  }
+  return findings;
+}
+
+function collectFiles(dir, out) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+      collectFiles(path.join(dir, entry.name), out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!EXTENSIONS.has(path.extname(entry.name))) continue;
+    const full = path.join(dir, entry.name);
+    if (full === SELF) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+function main() {
+  console.log('=== 🧭 Harness test-source portability lint ===');
+
+  const files = collectFiles(SCAN_ROOT, []);
+  let literalCount = 0;
+  let findings = 0;
+
+  for (const file of files) {
+    const text = fs.readFileSync(file, 'utf8');
+    const lines = text.split('\n');
+    for (const literal of extractLiterals(text)) {
+      literalCount += 1;
+      const allowed =
+        PRAGMA.test(lines[literal.line - 1] || '') ||
+        PRAGMA.test(lines[literal.line - 2] || '');
+      if (allowed) continue;
+      for (const finding of analyzeLiteral(literal)) {
+        findings += 1;
+        const shown = literal.value.length > 80 ? `${literal.value.slice(0, 77)}...` : literal.value;
+        const rel = path.relative(path.resolve(SCAN_ROOT, '..'), file);
+        console.error(`❌ ${rel}:${literal.line} [${finding.rule}] ${finding.detail}`);
+        console.error(`   literal: ${shown}`);
+        console.error('   fix: portable fixture name, platform guard, or `portability-lint: allow <reason>`');
+      }
+    }
+  }
+
+  console.log(`Scanned ${files.length} file(s), ${literalCount} single-line literal(s).`);
+  if (findings > 0) {
+    console.error(`❌ portability lint found ${findings} finding(s) in the Windows-hostile class.`);
+    process.exit(1);
+  }
+  console.log('✅ no Windows-hostile paths in scanned test sources.');
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { extractLiterals, analyzeLiteral, looksPathLike, pathSegments };

package/docs/document-lifecycle.md

@@ -11,7 +11,8 @@ Documentation is a **consumer** of the #320 workflow/obligation abstractions. No
 | 0 — contract + RED fixtures | This file; fixtures under `ci/fixtures/doc-lifecycle/` |
 | 1a — `project-docs.json` loader | `multi-agent-workspace/scripts/project-docs-resolver.js` |
 | 2 — roles, IDs, aliases, legacy, supersession, index, D6.9 PRD revisions | `harness-everything/scripts/doc-lifecycle.js` |
-| 1b, 3 (`doc-change`, `requirement-sync`) | Not started: blocked by #320 family metadata, D1 obligation schema and D3 evidence states |
+| 3a — `doc-change` / `requirement-sync` pure derivation and evidence producer | `harness-everything/scripts/doc-obligations.js` (facts and obligations), `harness-everything/scripts/doc-evidence.js` (`checkDocObligations`). Pilot-local: not wired into workflow disposition yet. H3 and H4 have deterministic tests; H1 and H2 are deferred to 3c. Known limits: the attested-envelope fields are caller-asserted (`configDigest` is checked for presence only, not against the parsed config); `candidateDigest` covers only `docs/prd/`, so custom PRD roots and task-scope binding are not yet verified; deleted and renamed paths fail closed (#335) |
+| 1b, 3b–3c (provider suggestions, reconciliation, H1–H2 evaluation) | Not started: blocked by #320 family metadata, D1 obligation schema and D3 evidence states. Known gap: deleted and old rename paths cannot get candidate-bound evidence, so their MUSTs fail closed |
 | 4 — derived-view generators, `describes:` drift | Not started |
 
 ## Configuration (D5)
@@ -195,6 +196,61 @@ Anchors for cross-file diagnostics: `supersede-*`, `unresolved-ref`, `ambiguous-
 
 `invalid-prd-id`, `invalid-revision`, `duplicate-revision`, `missing-parent`, `multiple-baselines`, `revision-cycle`, `revision-fork`, `stale-draft-base`, `invalid-transition`, `approval-missing`, `approval-content-mismatch`, `revision-digest-mismatch`, `immutable-revision-modified`, `immutable-revision-deleted`, `req-dropped`, `incomplete-snapshot`, `invalid-req-clause`, `replacement-alias-overlap`, `replacement-cycle`. `not-observed` is an evidence disposition, not a diagnostic and not a pass.
 
+## D6.5 — `doc-change` applicability by diff facts (Decided; revised 2026-10-16)
+
+Not a single class enum. The diff yields **facts**; required checks are the **union** of what each fact triggers. If a fact cannot be determined, assume it is present (`unknown` never downgrades to trivial).
+
+| Fact (from diff) | Triggers |
+| --- | --- |
+| Any governed file touched | Lint (role/status/ID/alias); in-repo link check |
+| Text/format only (no fact below) | Nothing more |
+| New governed file | Update-over-create check; outline confirmation (MUST for PRD/ADR, SHOULD otherwise) |
+| Declared derived source affected | Regenerate + regenerate-equals |
+| **Normative field**: frontmatter `status`/`supersedes`, PRD REQ block/acceptance, ADR *Decision* section | Quality review (MUST); D6.4 conflict check |
+| Governed reference/guide content | Prose > 50% reminder (SHOULD) |
+| Code or REQ-citing test touched | `requirement-sync` evaluation (D6.6) |
+
+Decision extraction recognizes ATX boundaries with 0–3 leading spaces and ignores fenced or indented code. A suspected Setext Decision heading, or an unsupported Setext boundary within an ATX Decision section, yields `unknown`; paragraph/container context is not inferred.
+
+- Example: a typo in an ADR's *Context* section triggers only lint + links; the same typo in its *Decision* section is normative.
+- Claimed scope vs diff facts mismatch → claim/evidence contradiction (#320 D3), only where the diff supports it; visible, never a lock.
+- Commit still requires existing workflow authorization; no automatic commit.
+
+## D6.6 — Event-driven maintenance (Decided)
+
+**`requirement-sync` detection** (builds on D6.2: tests cite REQ IDs):
+
+| Observation | Disposition |
+| --- | --- |
+| A test citing `REQ-X` is added or its assertions change | **Candidate signal**, not proof → **MUST** update/supersede REQ-X in the PRD in the same change, or record a structured `no-req-change` (reason + cited evidence, e.g. unchanged acceptance, passing test result) |
+| An existing test's cited REQ identity set is added, removed, or retargeted, or the changed call cannot be associated with its prior identity | Applicability/scope `unknown`, never N/A; retain candidate REQ identities and the test path. If removal leaves no candidate identity, retain the prior REQ ID as a removed identity. A citation-only change is not by itself a `new-test` or `assertion-change` trigger |
+| A legacy file-level REQ tag is added, removed, or retargeted on a modified test file | Applicability/scope `unknown`, never N/A; retain the changed identity and test path, even when stripped comments leave assertion tokens unchanged |
+| A test title changes or reorders REQ IDs while preserving the same cited identity set, or an ordinary comment changes | No trigger → `requirement-sync` N/A |
+| Ordinary comment-only or whitespace-only edit that preserves the cited REQ identity set | Not a trigger → `requirement-sync` N/A |
+| REQ-citing test change whose assertion change cannot be determined | `unknown`; never a fail |
+| Triggered MUST, **attested envelope** (all of the following), cited REQ resolved, **not** revised, **no** valid `no-req-change` waiver | **Observed fail** (`req-sync-no-revision-or-waiver`). Not a Stop hook, lock, or completion policy |
+| Triggered MUST, `complete` inventory but envelope incomplete, mismatched, or unattested | `none` with `req-sync-envelope-unattested`. Never a fail |
+| Attested envelope = `complete` and `waiverInventoryComplete` both `true`; `baseDigest` equal to the baseline digest; `candidateDigest` equal to the digest of the candidate PRD set; `configDigest` present; non-empty cited REQ list | Caller-attested. The derivation copies it and never infers it. Not independent proof that the caller collected the inventory completely |
+| Unsupported or stale `no-req-change` waiver | Unverified (`unsupported-waiver`). It never satisfies the MUST. It does not by itself establish the failure, and an independently attested unmet obligation may still fail |
+| `no-req-change` without adequate evidence | `not-observed` / unverified; never an automatic pass. An invalid waiver is diagnosed and does not satisfy the MUST |
+| Cited REQ missing, ambiguous, or unresolved | `unresolved` with `req-unresolved`; never a pass, never an observed fail. "Ambiguous" means declared in two distinct current logical PRDs. Retained revisions of one PRD resolve to the current effective revision |
+| Incomplete execution record (no command, no provenance, non-integer `exitCode`) | `execution-record-incomplete`; never a pass |
+| Code changes, no REQ-citing test touched | `not-observed` (#320 D3 evidence state), not a failure; diff alone never proves behavior unchanged |
+| Agent claims REQ-X affected, no supporting evidence | Claim/evidence contradiction; reminder, no lock |
+
+| Event | Obligation | Strength | Enforced by |
+| --- | --- | --- | --- |
+| REQ touched (above) | `requirement-sync` | MUST | New rule |
+| `describes:` fingerprint drift | Reminder | SHOULD | D5 #4 |
+| Ticket closed | In-repo tickets: `status: done`; regenerate index. `tickets: "tracker"`: no in-repo ticket status is generated or inferred offline | MUST | D5 #1 + D6.3 lint |
+| ADR superseded | Old ADR `status: superseded` | MUST | D6.3 lint |
+| New defect | Goes to tracker or the declared `tickets` path | MUST | Lint reminder when a ticket is added under a `done` phase |
+| Report finished | `final`; `archived` once its work closes | SHOULD | Reminder |
+
+- All events are checked at the existing workflow's `verification` step; no standing maintenance loop.
+- Checks are pure and generators deterministic, so reruns are idempotent.
+- `requirement-sync` is the only genuinely new rule; the rest reuse D5 and D6.3 checks.
+
 ## Packaging
 
 Source checkout, Codex plugin and Claude plugin copy whole skill trees. Callers locate `doc-lifecycle.js` and the resolver relative to their own skill directory, never the source-tree root. A to-spec-only install must use the same resolver implementation (copied byte-identically and checked), and a broken shared module is an error, never a silent fallback to older host scanning.

package/docs/repository-contract.md

@@ -19,7 +19,7 @@ This page is generated from checked-in runtime and workflow sources. Do not edit
 | Workflow | Node.js versions | Explicit triggers | npm quality gates |
 | --- | --- | --- | --- |
 | `behavioral-evals.yml` | 24 | schedule, workflow_dispatch | n/a |
-| `ci.yml` | 22, 24 | workflow_call | `test`, `test:mutations`, `test:release:semantics`, `waza:check`, `test:consistency`, `test:references`, `test:release`, `test:collision`, `test:plugin:openai`, `test:plugin:submission`, `test:platform:compatibility` |
+| `ci.yml` | 22, 24 | workflow_call | `test`, `test:mutations`, `test:release:semantics`, `waza:check`, `test:consistency`, `test:references`, `test:release`, `test:collision`, `test:plugin:openai`, `test:plugin:submission`, `test:platform:compatibility`, `test:portability` |
 | `release.yml` | 24 | workflow_dispatch | n/a |
 
 ## Drift prevention

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.34.0
+  version: 0.35.0
 ---
 
 # Harness Everything