@ericrisco/rsc 1.0.5 → 1.0.7

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.5",
+  "version": "1.0.7",
   "counts": {
     "skills": 258
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/eval-lint.sh

@@ -7,6 +7,16 @@ set -euo pipefail
 #   >= 5 should_trigger entries
 #   >= 4 should_not_trigger entries
 #   >= 1 capability scenario
+#   every should_not_trigger route_to resolves (see below)
+#
+# route_to is the one that used to be decorative: the rubric listed "route_to names a
+# real skill" as a deterministic gate and nothing checked it, so evals accumulated
+# routes to skills that were never authored. Each value must now be one of:
+#   - a real catalog skill id (a directory under skills/ with a SKILL.md)
+#   - "none" — deliberately nothing to route to
+#   - "external:<name>" — a skill outside this catalog, on purpose. Some skills
+#     legitimately defer to tools that ship elsewhere; the prefix makes that a
+#     visible, greppable claim instead of a typo indistinguishable from drift.
 #
 # Uses python3 for real YAML parsing when available. If python3 is missing,
 # falls back to a basic structural grep check and SKIPs the deep validation
@@ -36,7 +46,7 @@ warned_skip=0
 validate_py() {
   cy="$1"
   CASES_YAML="$cy" MIN_TRIGGER="$MIN_TRIGGER" MIN_NOT_TRIGGER="$MIN_NOT_TRIGGER" \
-  MIN_CAPABILITY="$MIN_CAPABILITY" python3 - <<'PYEOF'
+  MIN_CAPABILITY="$MIN_CAPABILITY" VALID_IDS="$VALID_IDS" python3 - <<'PYEOF'
 import os, sys
 try:
     import yaml
@@ -72,7 +82,39 @@ st = count("should_trigger")
 sn = count("should_not_trigger")
 cap = count("capability")
 
+# --- route_to resolution -------------------------------------------------------
+# Accepts a real catalog id, "none", or "external:<name>". A value may be a list,
+# or a string holding several targets separated by comma / | / " or ".
+valid = set(filter(None, os.environ.get("VALID_IDS", "").split(",")))
+NOTHING = {"none", "n/a", "-", ""}
+bad_routes = []
+
+def targets(value):
+    items = value if isinstance(value, list) else [value]
+    out = []
+    for item in items:
+        for part in str(item).replace("|", ",").replace(" or ", ",").split(","):
+            out.append(part.strip().strip("`"))
+    return out
+
+for case in (data.get("should_not_trigger") or []):
+    if not isinstance(case, dict) or case.get("route_to") is None:
+        continue
+    for t in targets(case["route_to"]):
+        low = t.lower()
+        if low in NOTHING:
+            continue
+        if low.startswith("external:"):
+            if not low[len("external:"):].strip():
+                bad_routes.append('"external:" with no name')
+            continue
+        if valid and t not in valid:
+            bad_routes.append(t)
+
 reasons = []
+if bad_routes:
+    uniq = sorted(set(bad_routes))
+    reasons.append("route_to does not resolve: %s (use a real skill id, \"none\", or \"external:<name>\")" % ", ".join(uniq))
 if st < 0:
     reasons.append("should_trigger is not a list")
 elif st < mt:
@@ -112,8 +154,17 @@ validate_grep() {
 
 echo "eval-lint: scanning $SKILLS_DIR"
 echo "minimums: should_trigger>=$MIN_TRIGGER should_not_trigger>=$MIN_NOT_TRIGGER capability>=$MIN_CAPABILITY"
+echo "route_to must resolve: a catalog skill id, \"none\", or \"external:<name>\""
 echo
 
+# The set of real skill ids, built once from disk — the same surface the router sees.
+VALID_IDS=""
+for sp in "$SKILLS_DIR"/*; do
+  [ -f "$sp/SKILL.md" ] || continue
+  VALID_IDS="$VALID_IDS,$(basename "$sp")"
+done
+VALID_IDS="${VALID_IDS#,}"
+
 # Iterate skills deterministically; bash 3.2-safe (no mapfile).
 for skill_path in "$SKILLS_DIR"/*; do
   [ -d "$skill_path" ] || continue

package/scripts/install-apply.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { planInstall } from './install-plan.js';
@@ -112,9 +112,35 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
   writeState(paths.stateFile, state);
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
   writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
+  ignoreLocalState(cwd);
   return { ...state, backup };
 }
 
+// `.rsc/` holds local machine state — hook scripts, install markers, the sello's
+// seals, the automation-gap log. None of it belongs in a user's repository, and the
+// gap log in particular is prose about what happened in their project: a routine
+// `git add -A` would publish it. Nothing used to keep that out, so add the entry.
+//
+// Additive and idempotent by construction: append one line to an existing
+// .gitignore, never rewrite or reorder it, and never create the file in a directory
+// that is not a git repository.
+export function ignoreLocalState(cwd = process.cwd()) {
+  if (!existsSync(join(cwd, '.git'))) return null;
+  const gi = join(cwd, '.gitignore');
+  let text = '';
+  try { text = existsSync(gi) ? readFileSync(gi, 'utf8') : ''; } catch { return null; }
+  const already = text.split('\n').some((l) => {
+    const s = l.trim().replace(/\/$/, '');
+    return s === '.rsc' || s === '/.rsc';
+  });
+  if (already) return null;
+  const prefix = text === '' ? '' : (text.endsWith('\n') ? '' : '\n');
+  try {
+    appendFileSync(gi, `${prefix}\n# rsc local state (hooks, seals, logs) — machine-local, never committed\n.rsc/\n`);
+    return gi;
+  } catch { return null; }
+}
+
 export function listInstalled({ target, home, cwd = process.cwd() }) {
   const paths = targetPaths(target, home, cwd);
   return Object.keys(readState(paths.stateFile).skills);

package/scripts/skill-rubric.md

@@ -16,7 +16,7 @@ dishonest 9.
 | 3 | **Body craft & progressive disclosure** | 0.15 | **The smallest body that routes correctly** — ≤400 lines is a ceiling, not a target, and there is no minimum: a skill that does its job in 60 lines scores higher than the same skill padded to 200. Every `references/` file is pointed to inline from this body (an unlinked reference is never loaded, so it is dead weight). rsc voice, every fence language-tagged, a checklist/decision table only where the flow branches, an anti-patterns table present. |
 | 4 | **Correctness, grounding & freshness** | **0.25** | Every load-bearing claim is accurate and **current (2025–2026)**: real library/API versions, no hallucinated flags/endpoints. The spec cites **authoritative sources with dates**; nothing rests on stale or invented facts. This is the heaviest dimension by design. |
 | 5 | **Actionability** | 0.15 | Concrete and runnable: real numbers, paths, commands, decision rules — not adjectives. A practitioner could act from it without leaving the skill. |
-| 6 | **Evals quality** | 0.10 | ≥5 `should_trigger` (incl. non-obvious), ≥4 `should_not_trigger` each with a `route_to` that names a **real** sibling, ≥1 `capability` with a meaningful `must_include` rubric. The cases are genuine, not filler. |
+| 6 | **Evals quality** | 0.10 | ≥5 `should_trigger` (incl. non-obvious), ≥4 `should_not_trigger` each with a `route_to` that resolves — a **real** catalog id, `none`, or `external:<name>` (enforced by `eval-lint`), ≥1 `capability` with a meaningful `must_include` rubric. The cases are genuine, not filler. |
 | 7 | **Originality & safety** | 0.10 | rsc voice, not a clone of any external catalog (no borrowed urgency blocks / rationalization tables / `*-reviewer-prompt.md` conventions / verbatim flowcharts). `verify.sh` present iff there is a checkable artifact. No destructive or unsafe advice presented without guardrails. |
 
 **Weighted score** = Σ(subscore × weight), rounded to 1 decimal. **Ship gate: ≥ 8.5.**

package/skills/analyze/SKILL.md

@@ -101,6 +101,28 @@ Render it at the dial's verbosity. Do not log a decision to `decisions.md` — a
 | Siding with the plan when it contradicts the constitution | The constitution wins by definition — flag CRITICAL. If the principle itself is wrong, that is a `constitution` change the user makes, not a quiet override here. |
 | Guessing what a vague requirement meant | Guessing defeats the gate. Mark AMBIGUOUS and route to `clarify`; do not encode your guess. |
 
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Cross-read of spec/plan/tasks against the constitution; findings ranked.",
+  "artifact": "02-DOCS/wiki/sdd/analysis/<slug>.md",
+  "next_recommended": "implement",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["analyze"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Read adversarially across artifacts, not inside one.", "A finding without a location is an opinion."]
+  },
+  "evidence": ["report path exists", "blockers listed with artifact + location", "constitution conflicts named"]
+}
+```
+
 ## Next in the chain
 
 On `GATE: PASS` (or once the user consciously accepts the remaining MEDIUM/LOW findings), proceed to **`implement`** — execute the tasks with TDD discipline, delegating concrete test tooling to the relevant stack skill (`fastapi`, `nextjs`, `go`, `flutter`, `postgresdb`). On `GATE: BLOCKED`, route each CRITICAL/HIGH finding to its owning phase (`clarify`, `plan`, `tasks`, or `constitution`), let the user resolve, then re-run `analyze`. The gate only opens once.

package/skills/author-skill/references/eval-authoring.md

@@ -17,7 +17,7 @@ Everything lives in `evals/cases.yaml` (the cases) and `evals/README.md` (how to
 
 `scripts/eval-lint.sh` parses every `cases.yaml` and fails the build only on the **structural minimums**: that `evals/cases.yaml` exists, that `should_trigger`, `should_not_trigger`, and `capability` are present as lists, and that their item counts meet **≥ 5 / ≥ 4 / ≥ 1**. (Without python3+PyYAML it degrades to a presence-only key check.) Run it before shipping to catch a missing or undersized section.
 
-It does **not** read inside the entries. Whether each `should_not_trigger` carries a `route_to`, whether that `route_to` names a sibling that actually exists in this repo, whether your `should_trigger` set includes a genuinely non-obvious or non-English phrasing, and whether each `capability` scenario has a real `must_include` rubric of gradeable points — none of that is enforced by the linter. Those are **author and review responsibilities**: verify them by hand (and in the self-audit / code-review pass) before shipping. A green eval-lint means the shape is right, not that the cases are good.
+It also resolves every `route_to`: each value must be a real catalog skill id, `none`, or `external:<name>` for a skill that deliberately lives outside this catalog — a stale route now fails the build. What it still does **not** read: whether each `should_not_trigger` actually carries a `route_to`, whether your `should_trigger` set includes a genuinely non-obvious or non-English phrasing, and whether each `capability` scenario has a real `must_include` rubric of gradeable points. Those are **author and review responsibilities**: verify them by hand (and in the self-audit / code-review pass) before shipping. A green eval-lint means the shape is right, not that the cases are good.
 
 ## cases.yaml structure
 
@@ -33,7 +33,7 @@ should_trigger:
 
 should_not_trigger:
   - prompt: "A near-miss that looks close but belongs elsewhere."
-    route_to: "sibling-id"   # a skill that ACTUALLY exists in this repo, or "none"
+    route_to: "sibling-id"   # a real catalog id, "none", or "external:<name>" — checked by eval-lint
     why: "Why it is NOT this skill and why the sibling owns it."
   # … ≥ 4 total
 
@@ -53,7 +53,7 @@ capability:
 
 ## Writing good `should_not_trigger` cases
 
-These are where descriptions get sharpened. Each near-miss should be genuinely tempting — adjacent in topic but owned by a sibling. The `route_to` must name a skill that **exists in this repo**; a `route_to` pointing at a non-existent skill is a defect. Pick the siblings most likely to be confused with this one and write a case that disambiguates each.
+These are where descriptions get sharpened. Each near-miss should be genuinely tempting — adjacent in topic but owned by a sibling. The `route_to` must name a skill that **exists in this repo** — `eval-lint` fails the build otherwise. If the right owner genuinely ships outside this catalog, say so with `external:<name>` rather than inventing an id: the prefix makes the claim visible instead of indistinguishable from drift. Pick the siblings most likely to be confused with this one and write a case that disambiguates each.
 
 For `author-skill`, the natural confusables are `specify`/`plan` (building a feature, not a skill), `building-agents` (agent loops), `harness` (generic docs/wiki), and `init` (bootstrapping). Route each near-miss to whichever it truly belongs to.
 

package/skills/building-agents/evals/cases.yaml

@@ -24,7 +24,7 @@ should_not_trigger:
     route_to: "none"
     why: "One-shot throwaway prompt with no tools/eval/production path — the skill says just call the SDK directly."
   - prompt: "Tune Anthropic prompt caching and extended thinking in our anthropic-only client.py to cut latency on a file that only imports the anthropic SDK."
-    route_to: "claude-api"
+    route_to: "external:claude-api"
     why: "Single-vendor Anthropic-SDK internals tuning in a file that only imports anthropic defers to the dedicated Anthropic skill; this skill stays multi-provider."
   - prompt: "Write the pgvector schema and an HNSW-indexed nearest-neighbour SQL query, plus tuning advice — just the database side, no LLM calls."
     route_to: "postgresdb"

package/skills/clarify/SKILL.md

@@ -113,6 +113,28 @@ After baking back, the spec line becomes a bounded, testable behavior with accep
 
 The gate is passed when the spec, constitution and profile were all read (settled questions cited, not re-asked); all ten taxonomy categories were considered; only the build-changing gaps were put to the user, as dial-sized decisions with recommendations; every answer is baked into the spec body with observable acceptance criteria, logged under `## Clarifications` and bounded under `## Out of scope`; and the final re-read opened no new gap.
 
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Open points resolved; the spec is de-risked and ready to plan against.",
+  "artifact": "02-DOCS/wiki/sdd/specs/<slug>.md",
+  "next_recommended": "plan",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["clarify"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Ask only what changes the spec.", "An unanswered question is recorded, never invented."]
+  },
+  "evidence": ["answers folded back into the spec", "remaining open points listed with their owner"]
+}
+```
+
 ## Next in the chain
 
 Hand off to **`plan`** — turn the now-sharp spec into a technical implementation plan (architecture, interfaces, data flow, testing strategy, risks), deferring stack specifics to the relevant stack skill. The chain continues: clarify → **plan** → tasks → analyze → implement → verify → review → ship. `debug` is callable any time if what you are "clarifying" turns out to be a runtime fault, not a spec gap.

package/skills/constitution/SKILL.md

@@ -132,6 +132,28 @@ This skill's `02-DOCS` record is the constitution at `02-DOCS/wiki/sdd/constitut
 
 Every later rsc-sdd phase reads this file before it works. The harness maintains and improves the article over the life of the project; this skill is the place that ratifies and amends it.
 
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Constitution written with N numbered, testable rules the later phases inherit.",
+  "artifact": "02-DOCS/wiki/sdd/constitution.md",
+  "next_recommended": "specify",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["constitution"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Principles are inherited constraints, not choices to re-make.", "Every rule is testable or it is a preference."]
+  },
+  "evidence": ["constitution path exists", "rules numbered and testable", "decisions log appended"]
+}
+```
+
 ## Next in the chain
 
 The constitution is the guardrail; now describe what to build. Hand off to **`../specify/SKILL.md`** — turn a fuzzy intent into a spec (what & why, no implementation), grounded in these principles. The full chain: **constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → ship** (with `debug`, `worktrees`, `parallel` callable on demand). The dispatcher is `../sdd/SKILL.md`.

package/skills/course-storytelling/evals/cases.yaml

@@ -22,14 +22,14 @@ should_not_trigger:
     route_to: "marketing"
     why: "Sales/landing copy for the course is marketing's domain. The skill teaches; it never bolts a pitch on, and explicitly defers selling words to marketing."
   - prompt: "Audit module 14 of my course for gaps, redundancy, anachronisms, and outdated stack references, and give me a written report."
-    route_to: "review-content"
+    route_to: "external:review-content"
     why: "Diagnostic content-audit pass with a written report. The skill says run review-content first and bring findings here; it rebuilds, it does not audit."
   - prompt: "Design a color system, typography scale, and diagram style for my course slides."
     route_to: "design"
     why: "Pure visual system / pixels. The skill defers the visual layer to design; it owns narrative, not aesthetics."
   - prompt: "Fact-check whether the historical claims in my lesson about the origins of TCP are actually accurate, with sources."
-    route_to: "deep-research"
-    why: "Pure fact-checking/research of subject matter, not reframing teaching. The skill forbids inventing proof and defers verification to deep-research."
+    route_to: "research-ops"
+    why: "Pure fact-checking/research of subject matter, not reframing teaching. The skill forbids inventing proof and defers verification to a research pass — `research-ops` in this catalog, a deep-research tool where the environment provides one."
 
 capability:
   - scenario: "A learner profile already exists and is complete in 02-DOCS/wiki/teaching/. The user gives a flat, definition-only lesson on 'idempotency' for a mid-level backend course and asks to make it land."

package/skills/plan/SKILL.md

@@ -141,6 +141,28 @@ regardless. (`implement` re-checks this as a hard gate before its first commit.)
 - Concrete framework/ORM/test-runner mechanics → the stack skill (`../fastapi/SKILL.md`,
   `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`, `../postgresdb/SKILL.md`).
 
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Technical plan derived from the clarified spec, with the isolation decision made.",
+  "artifact": "02-DOCS/wiki/sdd/plans/<slug>.md",
+  "next_recommended": "tasks",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["plan"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["The plan answers HOW; the spec owns WHAT.", "Name the isolation choice before the build starts."]
+  },
+  "evidence": ["plan path exists", "each spec acceptance criterion has an approach", "risks and rollback stated"]
+}
+```
+
 ## Next in the chain
 
 Plan written, indexed, decisions logged → propose isolation (above), then hand off to

package/skills/review/SKILL.md

@@ -237,6 +237,28 @@ Review is mostly a conversation, but two artifacts persist into the harness wiki
 
 Index both in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic — the harness owns that map; this skill just keeps its rows honest.
 
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Adversarial review against spec/plan/constitution; verdict and blocking findings.",
+  "artifact": "02-DOCS/wiki/sdd/reviews/<slug>.md",
+  "next_recommended": "ship",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["review"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Rank or it is noise: blocker / should-fix / nit.", "A finding without a repro is a question, not a defect."]
+  },
+  "evidence": ["verdict stated (APPROVE | APPROVE WITH NITS | CHANGES REQUESTED)", "each blocker carries location + repro + fix"]
+}
+```
+
 ## Next in the chain
 
 When the diff carries an **APPROVE** / **APPROVE WITH NITS** verdict and every blocker is resolved, hand off to **ship** — close the branch via PR / merge / cleanup, with **git authorship as Eric, never Claude**. If the review came back **CHANGES REQUESTED**, the loop goes back to **implement** (fix), then **verify** (re-prove green), then back here for re-review. Don't ship a diff that hasn't earned its verdict.