musubix6 0.1.1 → 0.1.3

package/.github/skills/lean-agentic-coding/SKILL.md

@@ -17,6 +17,7 @@ Rule: **rigor scales with risk, context scales with the diff.**
 Unsure → pick the higher tier. Escalate mid-task if a T2 trigger appears; never downgrade silently.
 
 ## 1. Context budget (all tiers)
+- With `.sdd/specs`, run the bundled `lean-sdd-tdd/scripts/sdd.mjs context <feature|REQ|file>...` before reading specs; `--changed` requires every changed file to resolve. Complete feature specs, artifacts and declared prerequisites are returned within 16384 UTF-8 bytes (`--max-bytes N` overrides explicitly). Resolve errors/overflow by narrowing selectors, not by bulk-reading all specs; add explicit selectors for relationships static impact cannot infer. Reading context never replaces approval/evidence or narrows full validation; run the full gate before merge.
 - Read `AGENTS.md` (≤1 KB pointer file) and the single contract file only. Locate with grep/glob; `view` with line ranges; never read whole large files, lockfiles, coverage, `node_modules`, generated output.
 - Run commands with quiet flags and `| tail`/`head`; report only failures + counts. Use `scripts/gate.sh` for compact results.
 - Independent reads/searches in one parallel batch. Delegate to sub-agents only work needing separate context, and give them a bounded goal + stop condition + "return ≤200 words".

package/.github/skills/lean-sdd-tdd/SKILL.md

@@ -57,10 +57,49 @@ Batch: write all tests for a feature, then red each, implement, green each, **on
 - Release qualification is separate from exploratory dogfooding: use the fixed support/candidate matrix and two-run evidence rules in `docs/design-sdd-hardening.md` §3.5 when present; otherwise use the release-readiness workflow in `references/enforced-rules.md`. Two arbitrary exploratory waves are not release proof, and technical readiness never replaces human release approval.
 - Without Git, `gate --changed` explicitly falls back to full evidence/checks; manifest discovery, impact and C# stubs use filesystem discovery.
 
+## 3b. Early project diagnostics
+
+For an in-scope TS/JS project (root `tsconfig.json`, local TypeScript 5.9.x and
+ESLint 9.x with one root flat config), run `$S diagnostics --root <app> --json`.
+For standalone JS, run `$S diagnostics --root <app> --profile javascript --json`
+(local ESLint 9.x and one root flat config, no TypeScript/tsconfig).
+For Python, run `$S diagnostics --root <app> --profile python --json`
+(root `.venv`: Python 3.14.x, Ruff 0.17.1 and mypy 2.4.0).
+For Rust, run `$S diagnostics --root <app> --profile rust --json`
+(installed cargo/rustc 1.99.x, root Cargo.toml/Cargo.lock, one package,
+existing external Cargo home and offline dependencies).
+Select a profile explicitly for those stacks; omission means TypeScript,
+never autodetection. Run after each coherent code-edit batch and before claiming completion.
+`PASS`/0 means all required providers completed without errors; `FAIL`/1 means static
+errors were found; `INCOMPLETE`/2 means diagnosis could not finish. Report its
+reasons, never call a missing tool or an ignored-only target set clean.
+Repair only issues within the user's requested change scope; bound repair to
+three attempts and disclose remaining issues instead of looping indefinitely.
+Diagnostics are a snapshot, not Red, Green, approval or gate evidence.
+Do not weaken or replace targeted tests, expected-assertion Red, approvals or
+the final full gate because diagnostics passed. Never add diagnostics to gate
+automatically. Never require TypeScript for standalone JS/Python/Rust, ESLint for
+Python/Rust, or diagnostic tools for unsupported stacks.
+Providers share a cumulative 8-MiB native stdout/stderr budget and have
+60 seconds each, except cargo-check (180 seconds); worker output is separately capped.
+Python uses isolated startup, root config/native exclusions, no bytecode/cache,
+and null columns plus an info notice for mypy diagnostics on non-ASCII lines.
+JS/Python enumeration fails closed if a symlink target outside excluded directories
+cannot be resolved, even for an unrelated extension.
+Rust checks all targets with default features, offline and locked. The parent owns
+and removes private external target/build output after stopping workers; cleanup
+failure is INCOMPLETE. Normal external Cargo cache bookkeeping/archive extraction
+may persist; automatic cache GC is disabled. Do not promise sandboxing, network
+isolation, or cleanup after parent SIGKILL/power loss/self-detached descendants.
+The command does not install tools, fix sources or save evidence. Configurations,
+plugins, build scripts and proc macros execute trusted local code with possible
+arbitrary side effects. See both READMEs for selection/count/config details.
+
 ## 4. Review without humans
 T2 only: parallel sub-agents by risk axis (security · correctness/state · contract · test adequacy), each diff-only, ≤200-word replies, findings to one file per feature, `.sdd/review-<feature>.md` (never share one `review.md` across features: it goes stale when the next feature overwrites it) (one line each: id|sev|path:line|state). Re-review Open items + fix diff only; stop after two clean rounds, then lock/merge.
 
 ## 5. Token rules
+Before reading existing specs, run `$S context <feature|REQ|file>...` (or `--changed` when every changed file maps to specs). It returns complete selected specs, declared artifacts and recursive `plan.md` prerequisites, not a summary. Default stdout budget: 16384 UTF-8 bytes; override explicitly with `--max-bytes N`, use `--json` for automation. On errors/overflow, resolve selectors or narrow the task; never treat partial/missing context as sufficient, and never bulk-read all specs as a fallback. Static file impact cannot infer undeclared relationships: add explicit feature selectors when needed. Context is not approval/test evidence and does not narrow validation; keep the full gate before merge.
 Read the spec and the specific files only; `view` ranges; quiet commands; one parallel batch for independent reads; no plan recaps; cite `path:line`. Suggest `/new` at boundaries. End with ≤8 lines: tier · REQs · gate verdict · open findings · next.
 
 ## Deterministic tests

package/.github/skills/lean-sdd-tdd/references/config.md

@@ -21,9 +21,12 @@
 - Tracker r32 (#348, #352): check-definition snapshots include Cargo workspace/package manifests, feature/target admission, default/custom build scripts and local build helpers; TypeScript checks include the selected/default tsconfig, JSONC `extends` chains (including package configs), and project references. Definition drift retains strict/warn policy. Cargo test gates also require every annotated Rust test in the checked surface to appear as executed, regardless of scope policy; direct commands request JSON artifact messages to distinguish same-named targets. Wrappers must preserve observable test output (and JSON artifact messages for ambiguous targets); quiet/hidden, ignored or zero-execution results cannot prove coverage.
 - Tracker r32 (#349–#351): check provenance fingerprints PATH-selected executables and symlink targets, including ignored launchers (compared with Green rather than Git absence). The definition closure includes `.npmrc`, protected npm lifecycle wrappers, explicit `make -f`/`--file` inputs and local pytest plugins. Direct pytest runs use isolated, hook-free Python startup with explicit package directories; execution reports reject collection-only checks, missing annotated test identities and plugin-forged successful exit codes. Review definition changes and re-record with `tdd refactor`.
 
+- Early diagnostics (development checkout, not published npm 0.1.2): `node <skill>/scripts/sdd.mjs diagnostics --root <app> --json [--profile typescript|javascript|python|rust]`. Default TypeScript uses root tsconfig, local TypeScript 5.9.x and ESLint 9.x with one root flat config. JavaScript uses that ESLint/config only and recursively selects JS/JSX/MJS/CJS (excluding .git/node_modules/.venv and directory symlinks). Python uses only root .venv (isolated Python 3.14.x, Ruff 0.17.1, mypy 2.4.0), root configs and native exclusions; direct .py/.pyi counts exclude .git/.venv/directory symlinks, not imported diagnostics. Config priority is Ruff .ruff.toml > ruff.toml > pyproject[tool.ruff], mypy mypy.ini > .mypy.ini > pyproject[tool.mypy] > setup.cfg[mypy]; no applicable config means isolated defaults. mypy non-ASCII columns are null with info/location-unavailable. Rust requires installed cargo/rustc 1.99.x, root manifest/lock, one package and existing external Cargo home/offline dependencies; all targets/default features run offline+locked. Both Rust build directories are parent-owned external scratch, removed after workers stop; cleanup failure is INCOMPLETE. Normal external Cargo cache bookkeeping/archive materialization persists, with automatic GC disabled. Rust counts distinct metadata target roots/observed roots, not every module. Exit 0/1/2 means PASS/FAIL/INCOMPLETE for the entire required provider set; warnings alone do not fail. Each provider cumulatively limits native stdout+stderr to 8 MiB and time to 60 seconds (Rust 180); worker protocol output has its own 8-MiB cap. This trusted-code snapshot does not install/fix/save history or replace Red, tests, approvals or the final gate, and is not injected into gate. Plugins/build scripts/macros are not sandboxed; network effects and cleanup after parent SIGKILL/power loss/self-detached descendants are not guaranteed. See SKILL section 3b and both READMEs.
 - Install per-user (`~/.copilot/skills/lean-sdd-tdd`) when the target repo asserts its skill list (e.g. a test enumerating `.github/skills`); copying into `.github/skills` can break such tests. Run `node <skill>/scripts/sdd.mjs --root <repo> ...`.
 - Build the target first (`npm run build`) if its CLI tests need build artifacts, before `gate`.
 - `.sdd/config.json`: `scan:{include:[],exclude:["fixtures/**"]}` (globs; only comment-leading `@id` lines count; in Python, a line that starts a triple-quoted docstring or sits inside one also counts); `timeoutMs` globally or per check; check `changedCmd` with `{changedFiles}`/`{changedTests}` used by `gate --changed` (auto: `vitest related`, `jest --findRelatedTests`). `gate --changed` uses `changedTimeoutMs` (default 60s) so hub-file changes fail fast with `TIMEOUT`; narrow with `changedCmd` such as `["npx","vitest","run","{changedTests}","{changedScopes}"]` (scopes = package dirs). Always run the full `gate` (no `--changed`) before merge. Non-JS stacks get an auto `changedCmd` (no-pkg roots): Go `{changedGoPkgs}` (changed packages + reverse deps via `go list`), Rust `{changedCargoPkgs}` (`-p` changed crates + dependents via `cargo metadata`), Maven `{changedModulesCsv}` (changed modules + dependents + every upstream module they need, from the poms, so diamond dependencies resolve without `-am -amd`; falls back to the full run if the poms cannot be read), Go scoping also works in a repo without commits, Gradle `{changedGradleTasks}` (`:mod:cleanTest :mod:test` for changed modules plus dependents found from `project(':x')` references; not `buildDependents`, which misses later-evaluated dependents), CMake `{changedCtestRegex}` (`ctest -R` of changed test files). When a change cannot be scoped (go.mod/Cargo.*/root Gradle files, non-test C/C++ sources, CMake files, files outside any module) the full check runs and `! cmd …: cannot scope changes` is printed (for Rust: `cannot scope changes for the changed Cargo packages`). A `conftest.py` that defines only non-autouse fixtures the test never names (and no `pytest_*` hooks) is not an oracle of that test. `gate --changed` also scopes in tests whose recorded oracle files (e.g. a contract) changed. `impact` is file-granular (a note says so); the `tdd green` shared-implementation warning is per-`@implements`-block (ledger field `implBlocks`, #287; falls back to the whole file when the block cannot be delimited, and to file mtime for older ledger entries without the field). Hub detection (JS/TS relative-import graph): if > `hubThreshold` (0.25) of test files depend on the change, `hubFallbackCmd` runs (`{changedTests} {directTests}`); if that exceeds `hubMaxTests` (30) the check is skipped as INCOMPLETE instead of timing out. Workspace package names and tsconfig `paths` are followed. For hub changes the uncommitted diff is mapped to exported symbols (comment/whitespace-only ⇒ skipped; declarations mentioning the symbol are tainted transitively) so only tests that can reach them run; unknown diffs (non-exported/top-level code, `export *`) keep the whole hub set; an empty selection is INCOMPLETE, never an unscoped full run. Timeouts report `TIMEOUT`, not FAIL.
+- Source discovery: `scan.maxFileBytes` is a positive safe integer (default `16777216`, 16 MiB). Supported source files are scanned completely up to and including the limit. Larger included sources cause an explicit `REFUSED: source scan` (exit 1) before evidence writes, rather than disappearing from trace/gate/impact. Explicit include/exclude filters and ignored generated directories apply before the bound; non-source documents are unaffected. This is a per-file bound, not a cumulative memory or latency guarantee.
+- Repository self-validation uses `.sdd/config.json` and `npm test`, shared with CI/publish checks. The full-suite check has the existing CI's 100-minute execution allowance; this does not alter the individual compiler fixtures' existing 15-second limits. The initial 30-minute repository check was insufficient and its interrupted run was not counted as a pass. Annotated Node tests need unique literal ID-bearing titles; parameterized scenarios remain inside their single owned test, with all case rows and assertions retained.
 - `flaky: {retries?: 1, policy?: "fail"|"warn"}` (#303): a failed `test` check is re-run `retries` times (0 disables). A pass on re-run prints `cmd test FLAKY suspected …`: `fail` (default) keeps the gate FAIL, `warn` accepts it with the warning. Each flaky event is appended to `.sdd/tdd.jsonl` as `{type:"flaky",check,retry,policy,outcome}`. Retries reporting only skipped/todo/xfail tests, zero tests, or no assertions cannot recover the failure or append flaky evidence (#335); remaining retries may still recover with an executed pass. A consistent failure stays a plain failure. Write deterministic tests: no fixed `sleep`, injected clock/random, port 0, generous timeouts, isolate signal/kill tests.
 - `prepare: {cmd, outputs?, inputs?, timeoutMs?}` in config (auto-set from the `build` script by `init`): `gate` runs it before checks and caches by input hash (`.sdd/prepare-cache.json`); skipped when inputs and `outputs` are unchanged. `gate --changed` snapshots changed paths before preparation, so a preparation command that normalizes a lockfile cannot remove its workspace members or transitive consumers from check scope.
 - Gate input integrity (#342): both full and changed gates hash annotated files, specs/approval artifacts, the ledger, policy/config inputs, protected oracle data and known check definitions before running commands. Direct prepare/check wrapper files and their local imports use the same protected closure. Each prepare, check, scoped fallback and retry is checked immediately afterward; mutation, deletion or added specs/annotated files fails regardless of `scopePolicy`, and remaining commands are not run. Mutating preparation is not cached. Declared `prepare.outputs` can regenerate oracle/artifact outputs, but cannot exempt annotated files, specs, the ledger, policy inputs or command definitions. Ordinary generated build outputs and gate-owned flaky ledger appends remain supported. These are command-boundary integrity checks, not a sandbox: a command that mutates and restores an input entirely within its execution is not detected.

package/.github/skills/lean-sdd-tdd/scripts/diagnostics-eslint.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { diagnostic, providerFailure, providerResult, sortDiagnostics } from './diagnostics.mjs';
+import { loadLocal, selectTypeScript } from './diagnostics-typescript.mjs';
+import { sourceInputs } from './diagnostics-native.mjs';
+
+/** @id CODE-DIAGESL-001 @implements REQ-DIAGESL-001 REQ-DIAGESL-002 REQ-DIAGESL-003 REQ-DIAGESL-004 */
+/** @id CODE-DIAGJS-001 @implements REQ-DIAGJS-001 REQ-DIAGJS-002 REQ-DIAGJS-003 */
+export async function diagnoseESLint(root, { profile = 'typescript' } = {}) {
+  let output = providerResult('eslint');
+  try {
+    const { api: { ESLint }, version } = loadLocal(root, 'eslint', /^9\.\d+\.\d+$/);
+    output.version = version;
+    const configs = ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'].map(name => path.join(root, name)).filter(file => fs.existsSync(file));
+    if (configs.length !== 1) return providerFailure('eslint', 'Exactly one root ESLint flat config is required', output);
+    output.configPath = configs[0];
+    let inputs;
+    if (profile === 'javascript') inputs = sourceInputs(root, /\.(?:js|jsx|mjs|cjs)$/i, ['.git', 'node_modules', '.venv']).files;
+    else {
+      const { config, errors } = selectTypeScript(root);
+      if (!config || errors.length) return providerFailure('eslint', 'Invalid TypeScript config for ESLint input selection', output);
+      inputs = config.fileNames.filter(file => /\.(?:[cm]?[jt]s|[jt]sx)$/i.test(file) && !/\.d\.(?:[cm]?ts)$/i.test(file));
+    }
+    if (!inputs.length) return providerFailure('eslint', 'ESLint has no eligible input files', output);
+    const eslint = new ESLint({ cwd: root, overrideConfigFile: output.configPath, fix: false, cache: false, errorOnUnmatchedPattern: true });
+    let ignored = 0;
+    const targets = [];
+    for (const file of inputs) {
+      if (await eslint.isPathIgnored(file)) ignored++;
+      else targets.push(file);
+    }
+    if (!targets.length) return providerFailure('eslint', 'All ESLint input files are ignored or unconfigured', output);
+    for (const file of targets) {
+      const results = await eslint.lintFiles([file]);
+      if (results.length !== 1 || path.resolve(results[0].filePath) !== path.resolve(file)) throw new Error(`Unexpected ESLint results for ${file}`);
+      for (const value of results[0].messages) output.diagnostics.push(diagnostic('eslint', root, {
+        file: results[0].filePath, line: value.line ?? null, column: value.column ?? null,
+        code: value.ruleId ?? (value.fatal ? 'ESLINT_PARSE' : 'ESLINT_CONFIG'),
+        severity: value.severity === 2 ? 'error' : 'warning', message: value.message,
+      }));
+    }
+    output.status = 'complete';
+    output.reason = null;
+    output.files = { included: inputs.length, checked: targets.length, ignored };
+    output.diagnostics = sortDiagnostics(output.diagnostics);
+    return output;
+  } catch (error) {
+    return providerFailure('eslint', `ESLint diagnosis failed: ${error.message}`, output);
+  }
+}

package/.github/skills/lean-sdd-tdd/scripts/diagnostics-native.mjs

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
+import { TextDecoder } from 'node:util';
+
+/** @id CODE-DIAGCLI-003 @implements REQ-DIAGCLI-004 */
+export function nativeBudget({ timeoutMs = 60000, outputBytes = 8388608, clock = () => performance.now() } = {}) {
+  const started = clock();
+  let bytes = 0, failure = null;
+  return {
+    async run(command, args, { cwd, env = process.env, input } = {}) {
+      const remaining = timeoutMs - (clock() - started);
+      if (remaining <= 0) failure ??= `Native provider timed out after ${timeoutMs} ms`;
+      if (failure) return { code: null, signal: null, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), failure };
+      return new Promise(resolve => {
+        const stdout = [], stderr = [];
+        const child = spawn(command, args, { cwd, env, shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+        const abort = reason => {
+          failure ??= reason;
+          child.kill('SIGKILL');
+          child.stdout.destroy();
+          child.stderr.destroy();
+          child.stdin.destroy();
+        };
+        const timer = setTimeout(() => abort(`Native provider timed out after ${timeoutMs} ms`), remaining);
+        const capture = (chunk, output) => {
+          const available = Math.max(0, outputBytes - bytes);
+          bytes += chunk.length;
+          if (available) output.push(chunk.subarray(0, available));
+          if (bytes > outputBytes) abort(`Native provider output exceeds ${outputBytes} bytes`);
+        };
+        child.stdout.on('data', chunk => capture(chunk, stdout));
+        child.stderr.on('data', chunk => capture(chunk, stderr));
+        child.stdin.on('error', error => { failure ??= `Native input failed: ${error.message}`; });
+        child.on('error', error => { failure ??= `Native spawn failed: ${error.message}`; });
+        child.on('close', (code, signal) => {
+          clearTimeout(timer);
+          if (clock() - started >= timeoutMs) failure ??= `Native provider timed out after ${timeoutMs} ms`;
+          resolve({ code, signal, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), failure });
+        });
+        child.stdin.end(input);
+      });
+    },
+  };
+}
+export function nativeText(buffer) {
+  return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer);
+}
+export function jsonLines(buffer) {
+  const records = [];
+  let start = 0;
+  try {
+    while (start < buffer.length) {
+      const newline = buffer.indexOf(10, start);
+      const end = newline === -1 ? buffer.length : newline;
+      const line = nativeText(buffer.subarray(start, end));
+      if (line.trim()) records.push(JSON.parse(line));
+      start = end + 1;
+    }
+    return { records, error: null };
+  } catch (error) {
+    return { records, error: `Invalid native JSONL: ${error.message}` };
+  }
+}
+export function inside(root, file) {
+  const relative = path.relative(root, file);
+  return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+}
+export function sourceInputs(root, extensions, excluded = ['.git', '.venv']) {
+  const files = [], symlinkDirectories = [];
+  function walk(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const file = path.join(directory, entry.name);
+      if (excluded.includes(entry.name)) continue;
+      const stat = entry.isSymbolicLink() ? fs.statSync(file) : entry;
+      if (stat.isDirectory()) {
+        if (entry.isSymbolicLink()) symlinkDirectories.push(path.relative(root, file).split(path.sep).join('/'));
+        else walk(file);
+      } else if (stat.isFile() && extensions.test(entry.name)) files.push(file);
+    }
+  }
+  walk(root);
+  return { files, symlinkDirectories };
+}