@jamie-tam/forge 6.0.0

package/skills/support-runtime-reachability/scripts/check.test.mjs

@@ -0,0 +1,244 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { check } from './check.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fxRoot = path.join(here, '__fixtures__');
+
+function fx(caseDir) {
+  return path.join(fxRoot, caseDir);
+}
+
+function findExport(result, name) {
+  const e = result.exports.find((x) => x.name === name);
+  if (!e) throw new Error(`expected export '${name}' in result, got: ${result.exports.map((x) => x.name).join(', ')}`);
+  return e;
+}
+
+test('case-01: route mounted via app.use is reachable', () => {
+  const result = check({ files: ['src/handlers/cases.ts'], root: fx('case-01-passes-app-use') });
+  assert.equal(result.exports.length, 1);
+  const e = findExport(result, 'casesRouter');
+  assert.equal(e.kind, 'const');
+  assert.equal(e.annotation, null);
+  assert.ok(e.production_callers.length >= 1, 'expected at least one production caller');
+  assert.ok(
+    e.production_callers.some((c) => c.pattern === 'mount'),
+    'expected an app.use mount caller',
+  );
+  assert.equal(result.stats.orphans_unannotated, 0);
+});
+
+test('case-02: route imported but never mounted is orphan', () => {
+  const result = check({ files: ['src/handlers/cases.ts'], root: fx('case-02-orphan-no-app-use') });
+  const e = findExport(result, 'casesRouter');
+  assert.equal(e.production_callers.length, 0);
+  assert.equal(e.annotation, null);
+  assert.equal(result.stats.orphans_unannotated, 1);
+});
+
+test('case-03: hook imported but never invoked is orphan', () => {
+  const result = check({ files: ['src/hooks/useTwilio.ts'], root: fx('case-03-orphan-import-only') });
+  const e = findExport(result, 'useTwilioDevice');
+  assert.equal(e.production_callers.length, 0);
+  assert.equal(result.stats.orphans_unannotated, 1);
+});
+
+test('case-04: JSX component rendered is reachable', () => {
+  const result = check({ files: ['src/components/MyComp.tsx'], root: fx('case-04-jsx-component-rendered') });
+  const e = findExport(result, 'MyComp');
+  assert.ok(
+    e.production_callers.some((c) => c.pattern === 'jsx'),
+    'expected JSX caller',
+  );
+});
+
+test('case-05: JSX component not rendered is orphan', () => {
+  const result = check({ files: ['src/components/Orphan.tsx'], root: fx('case-05-jsx-component-not-rendered') });
+  const e = findExport(result, 'Orphan');
+  assert.equal(e.production_callers.length, 0);
+});
+
+test('case-06: class instantiated via new is reachable', () => {
+  const result = check({ files: ['src/lib/Service.ts'], root: fx('case-06-class-instantiated') });
+  const e = findExport(result, 'Service');
+  assert.equal(e.kind, 'class');
+  assert.ok(
+    e.production_callers.some((c) => c.pattern === 'new'),
+    'expected new caller',
+  );
+});
+
+test('case-07: class never instantiated is orphan', () => {
+  const result = check({ files: ['src/lib/Lonely.ts'], root: fx('case-07-class-not-instantiated') });
+  const e = findExport(result, 'Lonely');
+  assert.equal(e.production_callers.length, 0);
+});
+
+test('case-08: default export imported and called is reachable', () => {
+  const result = check({ files: ['src/handler.ts'], root: fx('case-08-default-export-imported-and-called') });
+  const e = findExport(result, 'handler');
+  assert.equal(e.kind, 'default');
+  assert.ok(e.production_callers.length >= 1, 'expected production caller for default export');
+});
+
+test('case-09: default export with no caller is orphan', () => {
+  const result = check({ files: ['src/handler.ts'], root: fx('case-09-default-export-orphan') });
+  const e = findExport(result, 'handler');
+  assert.equal(e.production_callers.length, 0);
+});
+
+test('case-10: aliased named export resolves via alias', () => {
+  const result = check({ files: ['src/lib.ts'], root: fx('case-10-aliased-named-export') });
+  const e = findExport(result, 'bar');
+  assert.equal(e.kind, 'reexport');
+  assert.ok(e.production_callers.length >= 1, 'expected caller via alias');
+});
+
+test('case-11: re-export chain forwards to consumer', () => {
+  // The slice diff includes the internal export; the consumer imports from the index re-export.
+  const result = check({ files: ['src/lib/internal.ts'], root: fx('case-11-re-export-chain') });
+  const e = findExport(result, 'doStuff');
+  // The consumer (main.ts) imports from './lib' (index), not directly from internal. The check
+  // should recognize this via the index file's re-export OR the consumer's call.
+  assert.ok(
+    e.production_callers.length >= 1,
+    `expected caller via re-export chain, got: ${JSON.stringify(e.production_callers)}`,
+  );
+});
+
+test('case-12: test-only callers do not count as production', () => {
+  const result = check({ files: ['src/util.ts'], root: fx('case-12-test-only-caller') });
+  const e = findExport(result, 'helperOnly');
+  assert.equal(e.production_callers.length, 0);
+  assert.ok(e.test_callers.length >= 1, 'expected the test caller to land in test_callers');
+});
+
+test('case-13: gated-pending annotation is reported', () => {
+  const result = check({ files: ['src/future.ts'], root: fx('case-13-gated-pending-annotation') });
+  const e = findExport(result, 'futureHandler');
+  assert.deepEqual(e.annotation, {
+    kind: 'gated-pending',
+    value: 'phase-2-wiring',
+    raw: '// gated-pending: phase-2-wiring',
+  });
+  assert.equal(e.production_callers.length, 0);
+  assert.equal(result.stats.orphans_unannotated, 0); // annotated, not unannotated orphan
+});
+
+test('case-14: untraceable annotation with rationale is reported', () => {
+  const result = check({ files: ['src/decorated.ts'], root: fx('case-14-untraceable-annotation') });
+  // Named default export: `export default function GET(...)`.
+  const e = findExport(result, 'GET');
+  assert.equal(e.kind, 'default');
+  assert.equal(e.annotation?.kind, 'untraceable');
+  assert.equal(e.annotation?.value, 'framework-mounted (Next.js app router)');
+});
+
+test('case-15: untraceable with empty rationale reports empty value', () => {
+  const result = check({ files: ['src/lazy.ts'], root: fx('case-15-untraceable-empty') });
+  const e = findExport(result, 'lazy');
+  assert.equal(e.annotation?.kind, 'untraceable');
+  assert.equal(e.annotation?.value, ''); // agent decides this is malformed
+});
+
+test('case-16: Python module exports filter underscore names', () => {
+  const result = check({ files: ['src/lib.py'], root: fx('case-16-python-module') });
+  const names = result.exports.map((e) => e.name).sort();
+  assert.deepEqual(names, ['PublicClass', 'public_fn']);
+
+  const fn = findExport(result, 'public_fn');
+  assert.equal(fn.kind, 'def');
+  assert.ok(fn.production_callers.length >= 1, 'expected python from-import caller');
+
+  const cls = findExport(result, 'PublicClass');
+  assert.equal(cls.kind, 'pyclass');
+  assert.equal(cls.production_callers.length, 0); // never instantiated
+});
+
+test('case-17: router.use mount counts as production caller', () => {
+  const result = check({ files: ['src/routes/cases.ts'], root: fx('case-17-router-use') });
+  const e = findExport(result, 'casesRouter');
+  assert.ok(
+    e.production_callers.some((c) => c.pattern === 'mount'),
+    'expected router.use mount caller',
+  );
+});
+
+test('case-18: same-name caller without import is not counted (FP mitigation)', () => {
+  const result = check({ files: ['src/lib/foo.ts'], root: fx('case-18-shadowed-name-fp') });
+  const e = findExport(result, 'shared');
+  assert.equal(
+    e.production_callers.length,
+    0,
+    `expected zero callers for shadowed name without import, got: ${JSON.stringify(e.production_callers)}`,
+  );
+});
+
+test('case-19: same name imported from a different module is not credited', () => {
+  // Slice exports `handler` from src/handlers/cases.ts. main.ts imports
+  // `handler` from src/handlers/users.ts (a different module). Without
+  // path-provenance verification this would be a false PASS.
+  const result = check({
+    files: ['src/handlers/cases.ts'],
+    root: fx('case-19-same-name-different-module'),
+  });
+  const e = findExport(result, 'handler');
+  assert.equal(
+    e.production_callers.length,
+    0,
+    `expected zero callers (cross-module same-name FP), got: ${JSON.stringify(e.production_callers)}`,
+  );
+});
+
+test('case-23: dynamic `import (...)` with whitespace before paren still excluded from skip-mode', () => {
+  // `import ('./x')` is valid JS and still dynamic. The static import below
+  // must continue to register the caller.
+  const result = check({ files: ['src/lib.ts'], root: fx('case-23-dynamic-import-with-space') });
+  const e = findExport(result, 'realCaller');
+  assert.ok(
+    e.production_callers.length >= 1,
+    `expected static import to be detected after whitespace-before-paren dynamic import, got: ${JSON.stringify(e.production_callers)}`,
+  );
+});
+
+test('case-22: dynamic `import()` does not suppress later static import detection', () => {
+  // Earlier versions skipped to EOF after a leading `import('...')` because the
+  // skip-mode never saw a `from` clause. Real caller `actualCaller(...)` must
+  // still be detected.
+  const result = check({ files: ['src/lib.ts'], root: fx('case-22-dynamic-import-then-caller') });
+  const e = findExport(result, 'actualCaller');
+  assert.ok(
+    e.production_callers.length >= 1,
+    `expected static import after dynamic import() to still register, got: ${JSON.stringify(e.production_callers)}`,
+  );
+});
+
+test('case-21: mixed default+named import (`import x, { foo } from m`) credits both', () => {
+  const result = check({ files: ['src/lib.ts'], root: fx('case-21-mixed-default-and-named') });
+  const meta = findExport(result, 'meta');
+  const def = findExport(result, 'makeThing'); // named default
+  assert.equal(def.kind, 'default');
+  assert.ok(meta.production_callers.length >= 1, 'expected named meta to have caller');
+  assert.ok(def.production_callers.length >= 1, 'expected default to have caller via mixed import');
+});
+
+test('case-20: aliased import `import { x as y }; y()` is credited as caller', () => {
+  // Production caller imports under a local alias and invokes via the alias.
+  // The check must scan for the local alias name, not the original.
+  const result = check({
+    files: ['src/handlers/cases.ts'],
+    root: fx('case-20-aliased-import-usage'),
+  });
+  const e = findExport(result, 'handler');
+  assert.ok(
+    e.production_callers.length >= 1,
+    `expected aliased call to be a production caller, got: ${JSON.stringify(e.production_callers)}`,
+  );
+  assert.ok(
+    e.production_callers.some((c) => c.pattern === 'invocation'),
+    'expected invocation pattern',
+  );
+});

package/skills/support-skill-validator/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: support-skill-validator
+description: "Use when skills, rules, or commands have been edited to verify no contradictions, frontmatter conformance, or I/O gaps."
+---
+
+# Support: Skill Validator
+
+## Overview
+
+As the forge harness grows -- skills added, rules promoted from gotchas, commands modified -- contradictions and gaps can creep in. This skill performs systematic validation to catch inconsistencies before they cause confusion or incorrect behavior.
+
+**Core Principle:** A system that contradicts itself is worse than no system at all. Every directive must be unambiguous, every I/O chain must be connected, and every responsibility must have exactly one owner.
+
+## When to Use
+
+| Trigger | Validation Scope | Performance Target |
+|---|---|---|
+| `/validate` command | Full scan (all 5 checks) | Under 30 seconds |
+| `/evolve` modifies a skill | Pre-apply check (modified skill vs all others) | Under 10 seconds |
+| Session start | Lightweight I/O graph check only | Under 3 seconds |
+| Manual request | Full scan or targeted check | Depends on scope |
+| After gotcha promotion | Promoted rule vs existing rules and skills | Under 10 seconds |
+
+## When to load references
+
+- **`references/validation-checks.md`** — full procedure for each of the 5 checks (directives, I/O graph, overlaps, gates, drift), with examples. Load this when actually running a scan.
+- **`references/false-positives.md`** — known false-positive patterns and report-writing guidance. Load before writing a report so noise doesn't drown real findings.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | All `SKILL.md` files + all `rules/*.md` files + all `commands/*.md` files |
+| **Produces** | Validation report (structured, actionable) |
+| **Feeds into** | `/evolve` command (fix contradictions before applying changes) |
+| **Updates** | Nothing directly -- produces a report for human/AI action |
+
+### Input Files
+
+```
+skills/
+  */SKILL.md                -> All skill definitions
+rules/
+  common/*.md               -> Always-on rules
+  {language}/*.md           -> Language-specific rules
+references/
+  common/*.md               -> On-demand references
+commands/
+  *.md                      -> Command definitions
+agents/
+  *.md                      -> Agent definitions
+```
+
+### Output Format
+
+```
+VALIDATION REPORT
+=================
+Timestamp: {ISO 8601}
+Scope: {full | targeted | lightweight}
+Files Scanned: {count}
+
+CONFLICTS ({count}):
+  {list of conflicts with file references and line context}
+
+OVERLAPS ({count}):
+  {list of responsibility overlaps}
+
+I/O GAPS ({count}):
+  {list of missing producers, orphaned outputs, circular deps}
+
+GATE COVERAGE ({count of issues}):
+  {list of undocumented gate exemptions}
+
+DRIFT ({count}):
+  {list of post-modification inconsistencies}
+
+SUMMARY:
+  Errors: {count}     (must fix before proceeding)
+  Warnings: {count}   (should fix, may cause confusion)
+  Info: {count}       (minor, for awareness)
+```
+
+## The Five Validation Checks
+
+| # | Check | Catches | Severity range |
+|---|---|---|---|
+| 1 | **Directive Conflicts** | MUST vs NEVER contradictions across SKILL.md, rules, commands | ERROR – WARNING |
+| 2 | **I/O Graph Integrity** | Missing producers, orphaned outputs, cycles in the produces→requires graph | INFO – ERROR |
+| 3 | **Responsibility Overlaps** | Multiple skills/rules claiming the same responsibility | WARNING – INFO |
+| 4 | **Gate Completeness** | Missing or vague quality gates on command transitions | ERROR – WARNING |
+| 5 | **Post-Evolve Drift** | New inconsistencies introduced by a recent skill/rule modification | ERROR – INFO |
+
+Full procedure, examples, and the I/O graph severity baseline for each check live in **`references/validation-checks.md`** — load that before running any check. Always pair with **`references/false-positives.md`** before writing the report.
+
+## Validation Severity Levels
+
+| Level | Meaning | Action Required |
+|---|---|---|
+| **ERROR** | Definite contradiction, broken pipeline, or missing producer that demonstrably blocks a downstream consumer (named skill, named artifact, observed failure path) | Must fix before the system can be relied upon |
+| **WARNING** | Potential issue, ambiguity, or undocumented exception that a reasonable reader would misinterpret | Should fix to prevent confusion |
+| **INFO** | Asymmetric metadata, intentional omission, layered enforcement, or correct-but-could-be-clearer | Fix when convenient, or document as intentional |
+
+**Key rule:** Optional-by-rule fields (per `references/common/skill-authoring.md` — `Requires`/`Produces`/`Feeds into` are "Usually" not "Always") cannot generate ERROR or WARNING by their absence alone. They generate ERROR/WARNING only when their absence breaks a *named* downstream consumer.
+
+## Integration Points
+
+### /validate Command (Full Scan)
+
+Run all 5 checks. Output the full VALIDATION REPORT (above). Target: under 30 seconds.
+
+```
+User: /validate
+Running full validation...
+Scanning: {N} skills, {N} common rules, {N} references, {N} language rule sets, {N} commands, {N} agents
+
+VALIDATION REPORT
+=================
+[...]
+
+SUMMARY:
+  Errors: 0
+  Warnings: 3
+  Info: 1
+
+No blocking errors. System is consistent.
+Warnings should be reviewed when convenient.
+```
+
+### /evolve Command (Pre-Apply Check)
+
+Before `/evolve` applies any skill modification:
+
+1. Receive the proposed change
+2. Apply the change to a temporary copy
+3. Run targeted validation (Check 1 + Check 5)
+4. If errors found: BLOCK the change, present the conflicts
+5. If only warnings: WARN but allow (with user confirmation)
+6. If clean: ALLOW the change
+
+```
+/evolve proposes modifying build-tdd...
+
+Pre-apply validation:
+  [PASS] No directive conflicts
+  [PASS] I/O graph intact
+  [PASS] No new overlaps
+  [PASS] Gate coverage maintained
+  [PASS] No drift issues
+
+Change is safe to apply.
+```
+
+### Session Start (Lightweight Check)
+
+On session start, run only Check 2 (I/O Graph Integrity):
+
+- Fast (reads I/O contracts only, not full file content)
+- Catches broken connections from manual edits
+- Reports only errors, suppresses warnings/info
+- Target: under 3 seconds
+
+```
+Session start I/O check: All clear ({N} skills, 0 gaps)
+```
+
+### After Gotcha Promotion
+
+When `support-gotcha` promotes a gotcha to a rule:
+
+1. Receive the new rule text
+2. Run Check 1 (does new rule contradict existing rules?)
+3. Run Check 3 (does new rule overlap with existing skill responsibilities?)
+4. Report results before the promotion is finalized
+
+## Red Flags -- The Validator Itself Needs Validation
+
+| Situation | Action |
+|---|---|
+| Validator reports 0 issues on a known-inconsistent system | Validator has a bug -- manual review needed |
+| Validator reports 50+ errors | Likely false positives -- calibrate severity thresholds |
+| Same finding appears in every report | Either a real systemic issue or a false positive pattern |
+| Validator conflicts with itself | Meta-problem -- review validator logic |
+| Report is longer than 100 lines | Too verbose -- summarize and link to details |
+
+## Quick Reference
+
+| Check | What It Catches | Severity Range |
+|---|---|---|
+| **1. Directives** | MUST vs NEVER contradictions | ERROR - WARNING |
+| **2. I/O Graph** | Missing producers, orphaned outputs, cycles | INFO - ERROR (see Severity Baseline in `references/validation-checks.md`) |
+| **3. Overlaps** | Multiple owners for same responsibility | WARNING - INFO |
+| **4. Gates** | Missing or vague transition gates | ERROR - WARNING |
+| **5. Drift** | Post-modification inconsistencies | ERROR - INFO |

package/skills/support-skill-validator/references/false-positives.md

@@ -0,0 +1,59 @@
+# False positives and effective reports
+
+Two pieces of validator hygiene: knowing when a "finding" isn't a real defect, and writing reports that surface real issues without drowning them in noise.
+
+---
+
+## Handling False Positives
+
+Not every flagged issue is a real problem. The validator should:
+
+1. **Check for documented exceptions**
+   - If a file contains an explicit "Exception:" or "Note:" about the flagged issue, downgrade to INFO
+   - Example: `/hotfix` documents that it skips brainstorming -- this is not a missing gate
+
+2. **Check for layered enforcement**
+   - Rules setting standards + skills enforcing them is correct design, not overlap
+   - Flag as INFO (acknowledged), not WARNING
+
+3. **Check for context-specific directives**
+   - "NEVER deploy without tests" (general) vs "Skip E2E tests for documentation-only PRs" (specific context)
+   - The specific context exception does not contradict the general rule
+   - Flag as INFO if contexts are clearly different
+
+4. **Maintain a known-exceptions file**
+   - `.claude/validation-exceptions.md` can list known acceptable findings
+   - Validator checks this file before reporting
+   - Each exception must explain WHY it is acceptable
+
+5. **Check for intentional methodology-only skills**
+   - Per `references/common/skill-authoring.md`, I/O Contract is OPTIONAL — pure methodology skills can omit it
+   - A skill (e.g., `build-tdd`) may have no `## I/O Contract` section by design when:
+     - The agent it dispatches is self-contained (carries its own protocol inline)
+     - The calling command (e.g., `/feature`) owns task scope and artifact paths
+     - Adding a contract would only duplicate orchestration that lives elsewhere
+   - Flag as **INFO** with the note "I/O Contract intentionally omitted — pure methodology skill"
+   - **Never report this as ERROR or WARNING.** A blocking severity here is a validator bug, not a skill defect.
+
+6. **Check for asymmetric `Feeds into` declarations**
+   - `Feeds into` is "Usually", not mandatory (per `skill-authoring.md`)
+   - If skill A says `Feeds into: B` but B doesn't list A's artifact in `Requires`, this is **INFO**, not WARNING
+   - Escalate only if you can name an actual workflow where B fails because the artifact is missing
+
+---
+
+## Writing Effective Validation Reports
+
+### Do
+- Reference specific files and quote the conflicting text
+- Suggest concrete resolutions
+- Classify severity correctly (ERROR only for true contradictions)
+- Group related findings together
+- Include line context so the reader can find the issue
+
+### Do Not
+- Flag every minor wording difference as a conflict
+- Report style differences as errors (INFO at most)
+- Flood the report with INFO items that obscure real issues
+- Suggest resolutions that require rewriting entire skills
+- Report the same issue multiple times from different angles