@lifeaitools/rdc-skills 0.34.1 → 0.35.0

package/scripts/solid-score.mjs

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * solid-score — SOLID + Clean Architecture scoring, language-plugin-based.
+ *
+ * This CLI is deliberately language-agnostic. It owns: argv parsing, config
+ * loading, git-diff orchestration, the boundary-rule check, and output
+ * formatting. It does NOT know what an AST node is — every fact about source
+ * code comes from whichever plugin in `lib/plugins/` claims the file
+ * (see lib/language-plugin.mjs for the contract). Day 1 ships one plugin
+ * (TypeScript/JavaScript, via ts-morph). Adding Python later means writing
+ * `lib/plugins/python.mjs` against the same contract — nothing in this file
+ * changes.
+ *
+ * It does not persist a baseline file. `--diff <ref>` scores each changed
+ * unit TWICE — once at <ref> via `git show`, once against the CURRENT
+ * WORKING TREE (uncommitted and untracked changes included, not just what's
+ * been committed) — and gates on the delta. `git diff --name-only <ref>`
+ * (no `...HEAD`) compares the ref directly against the working directory,
+ * which also means the "before" side (`git show <ref>:<path>`) and the file
+ * list are read from the exact same commit — no separate merge-base to fall
+ * out of sync with it.
+ *
+ * A SEPARATE, non-SOLID check rides alongside the five letters: Clean
+ * Architecture's dependency rule — an orchestrator module declared to own a
+ * set of ports must actually import and delegate to them, not reimplement
+ * their logic inline. Dogfooded proof this matters: `rdc-harness`'s `Harness`
+ * god-object scores 68.5/100 on the plain weighted SOLID sum (DIP alone
+ * doesn't catch it — a class with almost no dependencies of ANY kind scores
+ * fine on concrete-instantiation ratio) but fails the boundary check outright
+ * on all six of its declared ports.
+ *
+ * A per-consumer-repo config lives at `<repo>/.solid-score.yml` — this
+ * package ships no default boundary rules of its own; each repo declares
+ * its own orchestrator/port pairs.
+ *
+ * Usage:
+ *   node solid-score.mjs <path> [--config <file>] [--diff <ref>]
+ *     [--format text|json] [--parser tree-sitter|ts-morph]
+ *
+ * `--parser` selects the AST backend (default `tree-sitter`, see the
+ * PARSER_PLUGINS block below for why).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync, readdirSync, statSync, realpathSync } from 'node:fs';
+import { join, dirname, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { registerPlugin, pluginFor } from './lib/language-plugin.mjs';
+import { typescriptPlugin } from './lib/plugins/typescript.mjs';
+import { treesitterPlugin } from './lib/plugins/treesitter.mjs';
+import { scoreUnit } from './lib/solid-scoring.mjs';
+
+// AST backend selection — `--parser tree-sitter|ts-morph`, default
+// `tree-sitter` per direct operator instruction (Dave, 2026-08-20): the
+// fleet's own standalone, in-process, multi-language tree-sitter parser
+// (ported from CodeFlow's `packages/codeflow-parser/src/nativeParser.ts`,
+// see scripts/lib/plugins/treesitter.mjs's own header for the full port
+// citation) replaces the third-party TS-only ts-morph backend as the
+// default for this CLI. `--parser ts-morph` stays available as an escape
+// hatch/regression-comparison lever, not a silent removal — ts-morph
+// remains the backend the other 3 ts-morph tools (clean-code-score,
+// pattern-score, refactoring-score) use this pass; only SOLID moves.
+const PARSER_PLUGINS = { 'tree-sitter': treesitterPlugin, 'ts-morph': typescriptPlugin };
+
+const parserArgIndex = process.argv.indexOf('--parser');
+const parserName = parserArgIndex !== -1 ? process.argv[parserArgIndex + 1] : 'tree-sitter';
+if (!PARSER_PLUGINS[parserName]) {
+  throw new Error(`--parser must be one of ${Object.keys(PARSER_PLUGINS).join('|')}, got "${parserName}"`);
+}
+// Register only the SELECTED plugin — typescriptPlugin and treesitterPlugin
+// both claim the identical file-extension set (canHandle), so registering
+// both would make `pluginFor()` always resolve to whichever was registered
+// first regardless of `--parser`, silently ignoring the flag.
+registerPlugin(PARSER_PLUGINS[parserName]);
+// A future Python plugin registers here too — nothing else in this file changes.
+
+export const DEFAULT_CONFIG = {
+  weights: { srp: 0.20, ocp: 0.15, lsp: 0.15, isp: 0.20, dip: 0.30 },
+  thresholds: null, // not implemented — see skills/solid-validator/SKILL.md "Known gaps"; left null so a config setting it is visibly ignored rather than silently accepted
+  diff: { maxDecrease: 0, newUnitMin: 0 },
+  exclude: ['**/test/**', '**/*.test.*', '**/node_modules/**'],
+  boundaries: [], // [{ orchestrator: glob, requiredPorts: [glob, ...] }]
+};
+
+/**
+ * A config path that was explicitly PASSED and does not exist is a user
+ * error, not "use defaults" — an absent `--config` flag (no path at all)
+ * legitimately means "no config, use defaults". Before this fix the two
+ * were indistinguishable: a typo'd path silently produced `boundaries: []`
+ * and a clean exit 0, and every SKILL.md-documented invocation of this tool
+ * pointed at `.solid-score.yml`, a filename that existed in no repo tonight
+ * — so the Clean Architecture gate ran with zero configured rules on every
+ * documented call site.
+ */
+export function loadConfig(path) {
+  if (!path) return { config: structuredClone(DEFAULT_CONFIG), configPath: null, configLoaded: false };
+  if (!existsSync(path)) throw new Error(`--config ${path} does not exist`);
+  const raw = parseYaml(readFileSync(path, 'utf8'));
+  const config = {
+    ...structuredClone(DEFAULT_CONFIG), ...raw,
+    weights: { ...DEFAULT_CONFIG.weights, ...(raw.weights ?? {}) },
+    diff: { ...DEFAULT_CONFIG.diff, ...(raw.diff ?? {}) },
+  };
+  return { config, configPath: path, configLoaded: true };
+}
+
+const GLOB_STAR_TOKEN = '\u0001GLOBSTAR\u0001';
+
+/**
+ * Real glob-to-regex, not a globstar-strip substring check — a single `*`
+ * in a user config previously survived as a literal character and matched
+ * nothing. Built with string split/join rather than regex-literal replace
+ * to sidestep a tool encoding issue that corrupted a prior version of this
+ * function with embedded NUL bytes at the globstar/space substitution
+ * points — confirmed byte-for-byte with a raw scan before rewriting.
+ */
+function globToRegExp(glob) {
+  const specialChars = ['.', '+', '^', '$', '{', '}', '(', ')', '|', '[', ']'];
+  let escaped = glob;
+  for (const ch of specialChars) escaped = escaped.split(ch).join(`\\${ch}`);
+  const withGlobstar = escaped.split('**').join(GLOB_STAR_TOKEN);
+  const withStar = withGlobstar.split('*').join('[^/]*');
+  const final = withStar.split(GLOB_STAR_TOKEN).join('.*');
+  return new RegExp(`(^|/)${final}$|(^|/)${final}(/|$)`);
+}
+
+function isExcluded(relPath, exclude) {
+  return exclude.some((p) => globToRegExp(p).test(relPath));
+}
+
+/** Recursive file walk — no glob library, so no more languages than plugins to add here either. */
+function walk(dir, exclude, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    if (entry.isDirectory()) walk(full, exclude, out);
+    else if (!isExcluded(full.split(sep).join('/'), exclude)) out.push(full);
+  }
+  return out;
+}
+
+/** Score a file's text as it existed at a given git ref, without touching the working tree. */
+function scoreAtRef(repoRoot, filePath, ref, weights) {
+  const relPath = relative(repoRoot, filePath).split('\\').join('/');
+  let text;
+  try {
+    text = execFileSync('git', ['show', `${ref}:${relPath}`], { cwd: repoRoot, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch (err) {
+    // `git show` fails both when the file is genuinely new at `ref` AND for
+    // unrelated reasons (a path-form mismatch, a bad ref). Collapsing both
+    // into "it's new" hides the second case — the exact class of silent
+    // path-form bug found three times in this file already tonight. Only a
+    // "does not exist" message is treated as new; anything else is rethrown.
+    const msg = String(err.stderr ?? err.message ?? '');
+    if (msg.includes('does not exist in') || msg.includes('fatal: path') && msg.includes('does not exist')) return null;
+    throw err;
+  }
+  const plugin = pluginFor(filePath);
+  if (!plugin) return null;
+  return plugin.extractUnits(filePath, text).map((u) => scoreUnit(u, weights));
+}
+
+/**
+ * Does `orchestrator` import from every `requiredPorts` glob it's declared
+ * to own? Both fields are documented as globs; a rule that matches zero
+ * files is a config error (typo'd path, moved file) and MUST be reported —
+ * silently passing zero matches makes a misconfigured rule indistinguishable
+ * from a satisfied one.
+ */
+function checkBoundaries(files, boundaries, repoRoot) {
+  const findings = [];
+  const misconfigured = [];
+  for (const rule of boundaries) {
+    const orchestratorRe = globToRegExp(rule.orchestrator.split('\\').join('/'));
+    const matched = files.filter((f) => orchestratorRe.test(relative(repoRoot, f).split('\\').join('/')));
+    if (!matched.length) { misconfigured.push({ rule: rule.orchestrator, reason: 'matched zero files in the scanned set' }); continue; }
+    for (const f of matched) {
+      const plugin = pluginFor(f);
+      if (!plugin) continue;
+      const importPaths = plugin.importsOf(f);
+      for (const port of rule.requiredPorts) {
+        const portRe = globToRegExp(port);
+        const substringFallback = port.split('**')[0].replace(/^\.\//, '');
+        findings.push({ file: relative(repoRoot, f), requiredPort: port, satisfied: importPaths.some((p) => portRe.test(p) || p.includes(substringFallback)) });
+      }
+    }
+  }
+  return { findings, misconfigured };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────
+
+function arg(name, fallback = null) { const i = process.argv.indexOf(name); return i !== -1 ? process.argv[i + 1] : fallback; }
+
+/**
+ * Bash-tool / MSYS argv can hand this process a POSIX-shaped path
+ * (`/c/Dev/...`) even though this is native Windows node. The filesystem
+ * layer only resolves Windows-shaped paths — a POSIX path fails silently
+ * upstream of any error message. Normalize before use.
+ */
+function normalizePath(p) {
+  const m = /^\/([A-Za-z])\/(.*)$/.exec(p);
+  const windowsShaped = m ? `${m[1].toUpperCase()}:/${m[2]}` : p;
+  // A relative arg ("packages/core/src/index.mjs") must become absolute
+  // BEFORE any downstream comparison — the boundary check always builds its
+  // side of the match from repoRoot-absolute paths, so a relative target
+  // silently matches nothing.
+  const abs = resolve(process.cwd(), windowsShaped);
+  // realpathSync so a path reached through a symlink/junction compares
+  // equal to repoRoot (derived from `git rev-parse`, which reports the real
+  // path) — the same symlink-vs-original mismatch that broke the isMain
+  // check under `npm link` also applies to any target path reached that way.
+  try { return realpathSync(abs); } catch { return abs; }
+}
+
+async function main() {
+  const rawTarget = process.argv[2]?.startsWith('--') ? process.cwd() : (process.argv[2] ?? process.cwd());
+  const targetPath = normalizePath(rawTarget);
+  const configArg = arg('--config');
+  const { config, configPath, configLoaded } = loadConfig(configArg ? normalizePath(configArg) : null);
+  const diffRef = arg('--diff');
+  const format = arg('--format', 'text');
+
+  if (!existsSync(targetPath)) throw new Error(`target path does not exist: ${targetPath}`);
+  const isFile = statSync(targetPath).isFile();
+
+  // A plain (non-diff) score does not need a git repo at all — only resolve
+  // repoRoot when it's actually needed (diff mode, or a boundary check that
+  // needs repo-root-relative paths).
+  const needsGit = Boolean(diffRef) || (config.boundaries ?? []).length > 0;
+  let repoRoot = isFile ? dirname(targetPath) : targetPath;
+  if (needsGit) {
+    const cwdForGit = isFile ? dirname(targetPath) : targetPath;
+    repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: cwdForGit, encoding: 'utf8' }).trim();
+  }
+
+  let files;
+  if (diffRef) {
+    // `git diff --name-only <ref> -- <path>` (no `...HEAD`) compares `<ref>`
+    // directly against the WORKING TREE — committed history AND uncommitted
+    // changes both show up. Untracked new files show up in neither `git
+    // diff` form, so they're unioned in separately. Before this fix, only
+    // `<ref>...HEAD` (committed history alone) was scored — a dirty tree
+    // with real regressions scored zero files and exited 0.
+    const committed = execFileSync('git', ['diff', '--name-only', diffRef, '--', targetPath], { cwd: repoRoot, encoding: 'utf8' })
+      .split('\n').filter(Boolean);
+    const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '--', targetPath], { cwd: repoRoot, encoding: 'utf8' })
+      .split('\n').filter(Boolean);
+    files = [...new Set([...committed, ...untracked])]
+      .map((f) => join(repoRoot, f))
+      .filter((f) => !isExcluded(f.split(sep).join('/'), config.exclude));
+  } else if (isFile) {
+    files = [targetPath];
+  } else {
+    files = walk(targetPath, config.exclude);
+  }
+
+  const results = [];
+  const regressions = [];
+  const unresolvedLanguages = [];
+
+  for (const f of files) {
+    const plugin = pluginFor(f);
+    if (!plugin) { unresolvedLanguages.push(f); continue; } // reachable now — files are no longer pre-filtered by pluginFor before reaching this loop
+    const current = plugin.extractUnits(f).map((u) => scoreUnit(u, config.weights));
+
+    if (diffRef) {
+      const before = scoreAtRef(repoRoot, f, diffRef, config.weights);
+      for (const unit of current) {
+        if (unit.total === null) continue; // fully unmeasured — nothing to compare
+        const prior = before?.find((b) => b.unit === unit.unit);
+        if (!prior || prior.total === null) {
+          if (unit.total < config.diff.newUnitMin) regressions.push({ file: f, unit: unit.unit, reason: 'new_unit_below_min', total: unit.total, min: config.diff.newUnitMin });
+        } else if (prior.total - unit.total > config.diff.maxDecrease) {
+          regressions.push({ file: f, unit: unit.unit, reason: 'regression', before: prior.total, after: unit.total });
+        }
+      }
+    }
+    results.push({ file: relative(repoRoot, f).split('\\').join('/'), units: current });
+  }
+
+  const { findings: boundaryFindings, misconfigured: boundaryMisconfigured } = checkBoundaries(files, config.boundaries ?? [], repoRoot);
+  const boundaryViolations = boundaryFindings.filter((f) => !f.satisfied);
+
+  const output = {
+    results, regressions, boundaryFindings, boundaryViolations, boundaryMisconfigured, unresolvedLanguages,
+    config: { weights: config.weights, diff: config.diff, boundaryRuleCount: (config.boundaries ?? []).length },
+    configPath, configLoaded,
+    parser: parserName,
+  };
+
+  if (format === 'json') {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    for (const r of results) {
+      for (const u of r.units) {
+        console.log(`${r.file} :: ${u.unit} (${u.kind})  total=${u.total ?? 'UNMEASURED'}`);
+        for (const [k, v] of Object.entries(u.criteria)) console.log(`  ${k.toUpperCase()}: ${v.score.toString().padStart(3)}  [${v.confidence}]  ${v.detail}`);
+      }
+    }
+    if (boundaryViolations.length) {
+      console.log('\nCLEAN ARCHITECTURE BOUNDARY VIOLATIONS:');
+      for (const v of boundaryViolations) console.log(`  ${v.file}: missing required port import '${v.requiredPort}'`);
+    }
+    if (boundaryMisconfigured.length) {
+      console.log('\nBOUNDARY RULES MATCHING ZERO FILES (config error, not a pass):');
+      for (const m of boundaryMisconfigured) console.log(`  orchestrator '${m.rule}' — ${m.reason}`);
+    }
+    if (regressions.length) {
+      console.log('\nREGRESSIONS:');
+      for (const r of regressions) console.log(`  ${r.file} :: ${r.unit} — ${r.reason} ${JSON.stringify(r)}`);
+    }
+    if (unresolvedLanguages.length) {
+      console.log(`\n${unresolvedLanguages.length} file(s) matched no registered language plugin — skipped, not silently passed:`);
+      for (const f of unresolvedLanguages) console.log(`  ${relative(repoRoot, f)}`);
+    }
+    if ((config.boundaries ?? []).length === 0) {
+      console.log(configLoaded ? '\nNo boundary rules configured — Clean Architecture check has nothing to verify.' : '\nNo --config given — running with defaults, zero boundary rules. Pass --config <repo>/.solid-score.yml to enable the Clean Architecture check.');
+    }
+  }
+
+  const failed = regressions.length > 0 || boundaryViolations.length > 0 || boundaryMisconfigured.length > 0;
+  process.exit(failed ? 1 : 0);
+}
+
+// `import.meta.url` resolves through symlinks to the real path; a plain
+// `pathToFileURL(process.argv[1])` does not. Under `npm link` (a symlinked
+// global bin — exactly how this tool got installed) the two disagreed and
+// main() silently never ran, on every invocation, with exit 0 and no output.
+// realpathSync on both sides closes that gap.
+function realFileURL(p) {
+  try { return pathToFileURL(realpathSync(p)).href; } catch { return pathToFileURL(p).href; }
+}
+const isMain = process.argv[1] && import.meta.url === realFileURL(process.argv[1]);
+if (isMain) main().catch((err) => { console.error(err); process.exit(2); });

package/skills/architecture-reviewer/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: architecture-reviewer
+description: >-
+  Usage `rdc:architecture-reviewer <path> [--config <file>] [--diff <ref>]` —
+  Clean Architecture boundary/dependency-direction/layer-separation review.
+  Runs TWO mechanical scorers first — `rdc-architecture-score` (layer
+  classification, inward-dependency rule, framework coupling, missing
+  repository/port abstractions, HTTP/DB leaks into Use Cases, circular
+  layer dependencies) and `rdc-solid-score`'s orchestrator/port boundary
+  check — then dispatches judgment-level review for the ONE thing neither
+  can see: whether an abstraction boundary makes architectural SENSE for
+  this domain, not just whether it has the right shape. Call from
+  rdc:review step 8b+, or standalone before merging a new package/module.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# architecture-reviewer — Layering & Dependency-Direction Review
+
+## Why this is now mostly mechanical, not judgment-dispatch
+
+This skill used to run ONE mechanical check (`rdc-solid-score`'s named
+orchestrator/port boundary rule) and push everything else — framework
+imports leaking into inner layers, DB/HTTP access inside Use Cases, missing
+repository interfaces, layer-mixing, circular layer dependencies — into a
+dispatched judgment pass, on the theory that "mechanical facts don't exist
+yet for this domain."
+
+That premise was checked against the actual source it was adapted from and
+found wrong. `architecture-toolkit`'s own
+[`.claude/skills/review-arch.md`](https://github.com/OnSightTeam/architecture-toolkit)
+does not dispatch judgment for any of this — it shells out to
+`node dist/cli.js --agents=architecture <paths>`, a fully deterministic CLI.
+There is no LLM judgment step in the source project for Clean Architecture
+boundary/dependency/layer detection at all: it is glob-based layer
+classification plus regex import/text matching, because that is what the
+Dependency Rule actually needs — WHICH FILE, WHICH FOLDER, WHICH IMPORT
+TARGET — not an AST, and not an opinion.
+
+`scripts/lib/architecture-scoring.mjs` ports that detection logic (see its
+header for full provenance — three files fetched and read in full from
+`github.com/OnSightTeam/architecture-toolkit`, MIT). It runs as
+`rdc-architecture-score` alongside the pre-existing `rdc-solid-score`
+boundary check, which is a DIFFERENT, complementary mechanism (an
+explicitly-declared `{orchestrator, requiredPorts}` rule per repo, not
+layer classification) and stays exactly as it was.
+
+What is genuinely LEFT as judgment — the one thing neither scorer can do —
+is deciding whether an abstraction boundary makes architectural SENSE for
+this specific domain: a `Harness`-shaped class that reimplements logic its
+own sibling packages already own, a `shared`/`utils` module quietly
+accumulating business logic, a port whose shape leaks an implementation
+detail, a package importing more siblings than its stated job justifies.
+None of those are a shape a glob/regex scanner can match — they require
+reading INTENT against the code that implements it. That is Step 2 below,
+and it is now the ONLY judgment step.
+
+## When to Use
+
+- Any PR that adds or restructures a package boundary
+- Before merging a new orchestrator/use-case class
+- Called from `rdc:review` step 8b+ alongside the SOLID score gate
+- When a reviewer suspects "this could have just called the existing thing"
+
+## Arguments
+
+- `rdc:architecture-reviewer <path>` — full review of the target
+- `rdc:architecture-reviewer <path> --config <file>` — non-default layer
+  classification (see `lib/architecture-scoring.mjs`'s `DEFAULT_LAYERS` for
+  the shape; a repo that doesn't name its folders `entities`/`use-cases`/
+  `adapters`/`frameworks` needs its own `.architecture-score.yml`)
+- `rdc:architecture-reviewer <path> --diff <ref>` — new/changed code only
+  (scope the file list to the diff before invoking either scorer)
+
+## Mechanical Rule Catalog — `rdc-architecture-score`
+
+Every row cites the exact `architecture-toolkit` file:line it is ported or
+adapted from (full citations live in `lib/architecture-scoring.mjs`'s
+per-rule comments — read them before trusting a finding's severity).
+
+| Rule ID | What it detects | Severity | Confidence basis |
+|---|---|---|---|
+| `dependency-direction` | An inner-layer file imports a more-outer layer (Entities importing UseCases, UseCases importing Frameworks, etc.) | Critical | `high` when the import RESOLVES to a real scanned file with a known layer; `low` when only the import specifier text is keyword-matched (the toolkit's own, weaker, method) |
+| `framework-coupling` | A non-Frameworks-layer file imports a known framework/library (express, react, mongoose, prisma, aws-sdk, pg, …) | Critical (Entities) / High (everything else non-Frameworks) | `high`, except `medium` for the three generic-word indicators (`http`, `fetch`, `request`) the toolkit's own list carries, which real false-positive on an unrelated local variable or Node's builtin `node:http` |
+| `missing-abstraction` (5 subtypes) | `missing-repository-interface` (UseCase `new`s a concrete Repository/Gateway/DataSource) · `missing-input-port` (Controller `new`s a concrete UseCase, no Port interface declared) · `http-request-in-usecase` (`request.`/`req.` referenced in a UseCase file) · `direct-db-access-in-usecase` (`db.`/raw SQL in a UseCase/Interactor/Service) · `data-structure-leak` (a Controller returns/types a value as an Entity) | High/Critical per subtype | `high` for the first three (unambiguous regex shape); `medium`/`low` for db-access and data-structure-leak (broader textual patterns, real false-positive risk — disclosed per-subtype) |
+| `mixed-concerns` (bonus, beyond the task's 4 required categories) | Business-rule vocabulary and infrastructure vocabulary both appear in one file | High | `low` — whole-file word-list co-occurrence, same heuristic class as `clean-code-analyzer`'s N2 |
+| `ui-business-logic-mixing` (bonus) | A 100+ char `calculate`/`validate`/`process` function body alongside UI indicators | Medium | `medium` |
+| `mixed-layer-imports` (bonus) | A file imports from 3+ distinct layers | Medium | `medium` |
+| `circular-layer-dependency` | A REAL cycle in the layer-import graph, built from RESOLVED file imports and walked with the SAME ADP algorithm `package-metrics.mjs` already uses for package-level cycles (`findCycles`, reused not reimplemented) — this is STRONGER than `architecture-toolkit`'s own circular check, which is a `"../../.."`-depth proxy that is neither necessary nor sufficient for an actual cycle (see `lib/architecture-scoring.mjs`'s header for why that half was deliberately NOT ported) | High | `high` — built only from resolved edges, not keyword guesses |
+
+**Layer classification is config-driven, not hardcoded.** `DEFAULT_LAYERS`
+covers the canonical four rings (`entities`/`domain`, `use-cases`/
+`usecases`/`application`, `adapters`/`controllers`/`presenters`/`gateways`,
+`frameworks`/`infrastructure`) by path glob, with a class/interface-name
+regex fallback (ported from the toolkit's own `detectLayer`). A file
+matching NEITHER is reported `layer: null` / unclassified — it is never
+silently defaulted to any specific layer (the toolkit's own `detectLayer`
+defaults an unmatched file to `Frameworks`; this port deliberately does
+not, because "we don't know" and "this is definitely the outermost ring"
+are different claims). A repo with different folder names supplies its own
+`layers:` in `--config <file>`.
+
+## Procedure
+
+1. **Run both mechanical scorers first — cheap, exhaustive, never skip:**
+   ```bash
+   rdc-architecture-score <path> [--config <file>] --format json
+   rdc-solid-score <path> --diff <ref> --config <repo>/.solid-score.yml --format json
+   ```
+   Read `results[].rules` from `rdc-architecture-score` for every finding
+   above; read `boundaryFindings` from `rdc-solid-score` for the
+   orchestrator/port rule — a DIFFERENT, complementary check (an
+   explicitly-declared `{orchestrator, requiredPorts}` rule per repo, not
+   layer classification). Report `unclassifiedFiles` honestly — a file
+   with no glob/name-hint match got NO layer-aware findings run against it,
+   which is not the same as "clean."
+
+   If the target repo has no `.solid-score.yml` `boundaries` section, or no
+   `.architecture-score.yml` `layers` override where the default four rings
+   don't apply, say so plainly — a review that silently skipped a
+   configurable check is incomplete, not clean.
+
+2. **Dispatch the ONE remaining judgment step — architectural SENSE, not
+   shape:**
+
+   ```
+   Agent({
+     subagent_type: "pr-review-toolkit:code-reviewer",
+     description: "architecture-reviewer judgment pass",
+     prompt: "Review `git diff <ref>...HEAD` (or the full target if no
+              --diff) for architectural boundary choices that are
+              technically LEGAL — no mechanical rule catches them — but
+              conceptually WRONG for this domain. The mechanical scorers
+              (rdc-architecture-score, rdc-solid-score) already caught
+              layer-direction violations, framework coupling, missing
+              repository/port abstractions, HTTP/DB leaks into Use Cases,
+              layer-mixing, and circular layer dependencies — do NOT
+              re-litigate those. Check ONLY these four, which require
+              reading INTENT against the implementation, not matching a
+              shape:
+              (1) a module that reimplements logic a sibling package
+              already owns instead of importing and delegating to it — the
+              `Harness`-shaped failure: a class with almost no external
+              dependencies of ANY kind can score fine on a generic
+              DIP/coupling metric while still being exactly this;
+              (2) a 'shared'/'common'/'utils' module accumulating actual
+              business logic rather than genuinely-shared primitives;
+              (3) a port/interface whose own shape leaks a concrete
+              implementation detail (a parameter that only makes sense for
+              one adapter);
+              (4) a new package importing more siblings than its stated
+              responsibility justifies.
+              Report each finding with severity (critical/high/medium/low),
+              file:line, the concrete violation, and what delegation/
+              boundary should exist instead. Return
+              ARCHITECTURE_REVIEW_COMPLETE with:
+              { critical_count, high_count, medium_count, low_count,
+                findings: [{severity, file:line, issue, suggested_boundary}] }."
+   })
+   ```
+
+3. **Merge all three into one report.** The two mechanical scorers'
+   findings are certain (a named rule failed, or a real graph cycle
+   exists); the judgment findings carry the subagent's confidence — do
+   not present them with equal certainty. Within the mechanical findings
+   themselves, honor each finding's own `confidence` field (see the
+   catalog table) — a `low`-confidence mechanical finding is real evidence
+   worth a look, not a certainty either.
+
+4. **Severity gate**, same shape as `rdc:review` step 8b:
+   - Any `critical`/`high` mechanical finding, `rdc-solid-score` boundary
+     violation, or `critical`/`high` judgment finding → verdict cannot be
+     CLEAN.
+   - `medium`/`low` findings from either source → recorded, verdict can
+     still be CLEAN.
+   - Zero findings across all three → `ARCHITECTURE_REVIEW: CLEAN`.
+
+5. **Report:**
+   ```
+   ## Architecture Review
+   ### Mechanical — rdc-architecture-score (layer/dependency/boundary)
+   | Rule | File | Severity | Confidence | Detail |
+   ### Mechanical — rdc-solid-score (orchestrator/port boundary)
+   | File | Required port | Satisfied |
+   ### Unclassified files (no layer-aware rule ran)
+   ### Judgment findings — architectural sense
+   | Severity | File:Line | Issue | Suggested boundary |
+   ## Verdict: CLEAN / HAS ISSUES
+   ```
+
+## Rules
+
+- Never skip step 1 to save time — both scorers are cheap and certain, and
+  each has independently dogfooded a real finding (see below).
+- The judgment pass is advisory-plus-severity, not a rubber stamp on the
+  mechanical passes; a clean mechanical result with high-severity judgment
+  findings is still HAS ISSUES.
+- Do not report a mechanical finding without its `confidence` field — a
+  `low`-confidence heuristic hit (e.g. `data-structure-leak`'s broad
+  `Entity`-substring match) is worth a look, never a certainty.
+- If neither the target repo nor `--diff` is given, refuse rather than
+  guess scope — an architecture review with an unstated scope is
+  unfalsifiable.
+
+## Dogfood evidence — real, not hypothetical
+
+Two DIFFERENT real targets confirm the mechanism works and is honest about
+its own limits:
+
+**A constructed positive-control fixture** (per
+`.claude/rules/prove-absence-positive-control.md`) — a 4-file Clean
+Architecture layout with a KNOWN violation of each required category —
+correctly produced ALL of: 2 `dependency-direction` criticals (Entities and
+UseCases each importing the Frameworks-layer file), 1 `framework-coupling`
+critical (`express` imported into Entities), 5 `missing-abstraction`
+findings across all 5 subtypes, and a real `circular-layer-dependency`
+finding (`Frameworks -> UseCases -> Frameworks`, from two files that
+genuinely import each other). This run also caught a real bug in the
+scorer's own glob matcher — `**/frameworks/**` failed to match a TOP-LEVEL
+`frameworks/db-client.mjs` path (no parent directory to supply the literal
+slash the naive translation required) — fixed before ship, see
+`lib/architecture-scoring.mjs`'s `globToRegExp` header for the full story.
+
+**Two real fleets that do NOT use Clean-Architecture folder/class-naming
+conventions** (`rdc-harness/packages`, 85 files; this repo's own `scripts/`,
+36 files) correctly report ZERO `dependency-direction`/`framework-coupling`/
+`missing-abstraction` findings — confirmed as a GENUINE absence, not a
+broken scanner, by an independent `grep -rE 'class\s+\w+(UseCase|Interactor|
+Controller)'` across both trees (zero hits, matching the scorer's own
+report). Both correctly report every scanned file as `unclassified` — real
+honesty, not a silent false-positive from defaulting to a layer. The
+layer-independent `mixed-concerns` heuristic still fires (34/54 hits
+respectively) at its disclosed `low` confidence, the same character as
+`clean-code-analyzer`'s N2 — worth a look, not a certainty.
+
+## Worked Example — `rdc-harness`'s `Harness` class, THREE sources now
+
+Real target, read in full: [`C:/Dev/rdc-harness/packages/core/src/index.mjs`](file:///C:/Dev/rdc-harness/packages/core/src/index.mjs)
+(398 lines, one exported class). This is now a THREE-source report, and it
+is a genuinely instructive case: `Harness`'s failure is NOT a Clean
+Architecture layer violation (the file uses no `entities`/`use-cases`/
+`adapters`/`frameworks` folder or class-naming convention at all — that's
+a different codebase style, package-oriented rather than layer-oriented),
+so `rdc-architecture-score` correctly abstains rather than fabricating a
+layer-based finding:
+
+```
+## Architecture Review — rdc-harness/packages/core/src/index.mjs
+
+### Mechanical — rdc-architecture-score
+UNCLASSIFIED (no layer glob or name-hint matched `index.mjs`) — zero
+layer-aware findings ran. This is an honest abstention, not a clean result:
+`Harness`'s failure mode is package-level (see below), not layer-level.
+
+### Mechanical — rdc-solid-score (orchestrator/port boundary)
+| File | Required port | Satisfied |
+| index.mjs (Harness) | 6/6 ports (transaction, delivery, deploy, orchestration,
+  boundary, work — one per sibling package) | false — 0/6 satisfied |
+
+### Judgment findings — architectural sense
+| Severity | File:Line | Issue | Suggested boundary |
+| high (judgment #1) | index.mjs:49-394 (whole class) | `Harness` reimplements
+  transaction handling (`#block`, `transaction.blocked` events), delivery
+  (`shipDev`), deploy (`deploy`, `requestProduction`, `recordDecision`), and
+  orchestration (`createRun`, `createTarget`) all in one class — the exact
+  `Harness`-shaped failure: 21 sibling packages exist (`packages/transaction`,
+  `packages/delivery`, `packages/deploy`, `packages/orchestration`,
+  `packages/boundary`, …) and `Harness` currently imports from none of them;
+  it reimplements their responsibilities inline instead of delegating. It
+  would still pass a generic SOLID/coupling metric because its only external
+  imports are `node:crypto` and `node:fs` — a narrow dependency *count*
+  hiding a wide responsibility *surface*. | Split into a thin `Harness`
+  facade that composes injected ports: `TransactionPort`, `DeliveryPort`,
+  `DeployPort`, `OrchestrationPort`, each backed by its already-existing
+  sibling package. |
+
+## Verdict: HAS ISSUES (0/6 ports satisfied, 1 high judgment finding)
+```
+
+This is a real result, not a hypothetical: `Harness` genuinely has zero
+imports from any of its 21 sibling packages (confirmed via
+`grep -r "from '.*packages/(transaction|delivery|deploy|orchestration|boundary)"`
+against `index.mjs` — zero hits), `rdc-solid-score` genuinely reports 0/6
+ports satisfied, and `rdc-architecture-score` genuinely reports the file
+unclassified — three independently-verified facts, not one narrative.