@ericrisco/rsc 0.1.32 → 0.1.33

package/skills/roast-me/tools/extract_prompts.py

@@ -0,0 +1,520 @@
+#!/usr/bin/env python3
+"""Extract user prompts from AI assistant session files for prompt-quality analysis.
+
+Scans session files for one or more runtimes (Claude, Codex, Gemini) and
+extracts user prompts with contextual signals: whether an error followed,
+whether the agent auto-recovered, whether the user issued a correction.
+
+Writes a normalised JSON file to a temp path and prints:
+  1. The output path
+  2. A metadata summary
+
+Usage:
+    python3 extract_prompts.py [--days N] [--runtime auto|claude|codex|gemini]
+
+    --days N        Look back N days (default 7). Accepts bare numbers too.
+    --runtime ID    Which runtime to scan (default: auto = all installed runtimes).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Add the adapters package to sys.path so imports work regardless of cwd.
+# ---------------------------------------------------------------------------
+_TOOLS_DIR = Path(__file__).parent
+sys.path.insert(0, str(_TOOLS_DIR))
+from adapters.registry import get_adapters, list_runtime_ids
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MAX_PROMPTS = 300
+PROMPT_TEXT_LIMIT = 1500
+CORRECTION_TEXT_LIMIT = 500
+CONTEXT_BEFORE_LIMIT = 500
+
+CORRECTION_PATTERNS = re.compile(
+    r"\b(no[,.]?\s|wrong|instead|actually|don'?t|shouldn'?t|stop|not that|"
+    r"I said|I meant|I asked|that'?s not|please don'?t|why did you|"
+    r"you should have|that was wrong|incorrect|try again|redo|"
+    r"that broke|you broke|revert|undo)\b",
+    re.IGNORECASE,
+)
+
+# Model tier classification (provider-neutral labels).
+# Maps substrings found in model IDs to tier names.
+MODEL_TIER_MAP: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"fable|mythos", re.I), "heavy"),
+    (re.compile(r"opus|gpt-4(?!.*mini)", re.I), "heavy"),
+    (re.compile(r"sonnet|gpt-4.*mini|gemini-1\.5-pro|gemini-2", re.I), "balanced"),
+    (re.compile(r"haiku|gpt-3\.5|gemini-1\.5-flash|gemini-flash", re.I), "light"),
+]
+
+MODEL_TIER_RANK = {"light": 0, "balanced": 1, "heavy": 2, "unknown": 1}
+
+SIMPLE_PATTERNS = [
+    re.compile(p, re.IGNORECASE) for p in [
+        r"^\s*(yes|ok|go ahead|looks good|lgtm|sure|do it|yep|correct|perfect)\s*[.!]?\s*$",
+        r"^\s*(commit|push|merge|ship it|deploy)\s*$",
+        r"^\s*(read|show|list|ls|find|check)\b.{0,80}$",
+        r"^\s*(format|lint|fix.*style)\b",
+        r"^\s*(what does|explain|what is|how does)\b.{0,120}$",
+    ]
+]
+
+COMPLEX_PATTERNS = [
+    re.compile(p, re.IGNORECASE) for p in [
+        r"\b(design|architect|plan|strategy|migration|roadmap)\b",
+        r"\b(debug|race\s*condition|memory\s*leak|performance)\b",
+        r"\b(implement|build|create)\b.{30,}",
+        r"\b(refactor|rewrite|overhaul)\b.*\b(entire|all|whole)\b",
+    ]
+]
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def truncate(s: str, limit: int) -> str:
+    if not s or len(s) <= limit:
+        return s or ""
+    return s[:limit] + "..."
+
+
+def classify_tier(model_id: str) -> str:
+    """Map a model identifier string to a tier label."""
+    if not model_id:
+        return "unknown"
+    for pattern, tier in MODEL_TIER_MAP:
+        if pattern.search(model_id):
+            return tier
+    return "unknown"
+
+
+def classify_complexity(text: str) -> str:
+    for p in SIMPLE_PATTERNS:
+        if p.match(text):
+            return "simple"
+    for p in COMPLEX_PATTERNS:
+        if p.search(text):
+            return "complex"
+    return "moderate"
+
+
+COMPLEXITY_TO_TIER = {"simple": "light", "moderate": "balanced", "complex": "heavy"}
+
+# ---------------------------------------------------------------------------
+# Normalisation
+# ---------------------------------------------------------------------------
+
+def normalise_record(raw: dict[str, Any], position: int, total: int) -> dict[str, Any]:
+    """Convert a raw adapter record into a normalised PromptRecord."""
+    text = raw.get("prompt_text", "")
+    length = len(text)
+
+    has_xml_tags = bool(re.search(r"<\w[\w-]*>", text))
+    has_file_paths = bool(re.search(r"(/[\w./\-]+|~\/[\w./\-]+|\.\./)", text))
+    has_code_blocks = "```" in text
+
+    model_id = raw.get("model", "") or ""
+    tier = classify_tier(model_id)
+    complexity = classify_complexity(text)
+    recommended_tier = COMPLEXITY_TO_TIER[complexity]
+    was_overkill = MODEL_TIER_RANK.get(tier, 1) > MODEL_TIER_RANK.get(recommended_tier, 1)
+
+    return {
+        "runtime": raw.get("runtime", "unknown"),
+        "session_file": raw.get("session_file", ""),
+        "timestamp": raw.get("timestamp"),
+        "prompt_text": truncate(text, PROMPT_TEXT_LIMIT),
+        "prompt_length": length,
+        "prompt_position": position,
+        "total_prompts_in_session": total,
+        "has_xml_tags": has_xml_tags,
+        "has_file_paths": has_file_paths,
+        "has_code_blocks": has_code_blocks,
+        # These will be populated by post-processing when session context is available.
+        "followed_by_error": False,
+        "error_was_recovered": False,
+        "followed_by_correction": False,
+        "correction_text": "",
+        "error_tool": "",
+        "error_text": "",
+        "context_before": truncate(raw.get("context_before", ""), CONTEXT_BEFORE_LIMIT),
+        # Compute fields (best-effort from adapter)
+        "model": model_id,
+        "model_tier": tier,
+        "task_complexity": complexity,
+        "recommended_tier": recommended_tier,
+        "compute_was_overkill": was_overkill,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Session-aware processing (Claude-specific: reads full JSONL for context)
+# ---------------------------------------------------------------------------
+
+def process_claude_sessions(session_files: list[Path], cutoff: float) -> list[dict[str, Any]]:
+    """Full session-aware extraction for Claude Code JSONL files.
+
+    This matches the original extractor behaviour: reads each JSONL file
+    sequentially to detect errors, auto-recovery, and corrections in the turns
+    immediately following each user prompt.
+    """
+    from adapters.claude import _extract_text, _is_only_tool_results, _parse_timestamp
+
+    prompts: list[dict[str, Any]] = []
+
+    for sf in session_files:
+        if sf.stat().st_mtime < cutoff:
+            continue
+        try:
+            raw_lines = sf.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError:
+            continue
+
+        ordered: list[tuple[int, str, dict]] = []
+        for i, line in enumerate(raw_lines):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            msg_type = obj.get("type", "")
+            if msg_type in ("user", "assistant"):
+                ordered.append((i, msg_type, obj))
+
+        session_prompts: list[int] = [
+            idx for idx, (_, t, obj) in enumerate(ordered)
+            if t == "user"
+            and not obj.get("message", {}).get("isMeta")
+            and _extract_text(obj.get("message", {}).get("content", [])).strip()
+            and not _is_only_tool_results(obj.get("message", {}).get("content", []))
+        ]
+        total_in_session = len(session_prompts)
+
+        for position, idx in enumerate(session_prompts, 1):
+            _, _, obj = ordered[idx]
+            msg = obj.get("message", {})
+            content = msg.get("content", [])
+            prompt_text = _extract_text(content)
+
+            # context_before: last assistant text message before this prompt
+            context_before = ""
+            for k in range(idx - 1, -1, -1):
+                _, kt, ko = ordered[k]
+                if kt == "assistant":
+                    a_content = ko.get("message", {}).get("content", [])
+                    if isinstance(a_content, list):
+                        for block in a_content:
+                            if isinstance(block, dict) and block.get("type") == "text":
+                                context_before = block.get("text", "")
+                                break
+                    if context_before:
+                        break
+
+            followed_by_error = False
+            error_was_recovered = False
+            followed_by_correction = False
+            correction_text = ""
+            error_tool = ""
+            error_text = ""
+            error_count = 0
+            success_after_error = 0
+
+            for j in range(idx + 1, len(ordered)):
+                _, j_type, j_obj = ordered[j]
+
+                if j_type == "user":
+                    u_content = j_obj.get("message", {}).get("content", [])
+                    if isinstance(u_content, list):
+                        for block in u_content:
+                            if not isinstance(block, dict):
+                                continue
+                            if block.get("type") == "tool_result":
+                                if block.get("is_error"):
+                                    error_count += 1
+                                    if not followed_by_error:
+                                        followed_by_error = True
+                                        tid = block.get("tool_use_id")
+                                        for k in range(j - 1, idx, -1):
+                                            _, kt, ko = ordered[k]
+                                            if kt == "assistant":
+                                                ac = ko.get("message", {}).get("content", [])
+                                                if isinstance(ac, list):
+                                                    for ab in ac:
+                                                        if (isinstance(ab, dict)
+                                                                and ab.get("type") == "tool_use"
+                                                                and ab.get("id") == tid):
+                                                            error_tool = ab.get("name", "")
+                                                            break
+                                        rc = block.get("content", [])
+                                        if isinstance(rc, list):
+                                            for rb in rc:
+                                                if isinstance(rb, dict) and rb.get("type") == "text":
+                                                    error_text = rb.get("text", "")
+                                                    break
+                                        elif isinstance(rc, str):
+                                            error_text = rc
+                                else:
+                                    if error_count > 0:
+                                        success_after_error += 1
+
+                    if not j_obj.get("message", {}).get("isMeta"):
+                        next_text = _extract_text(u_content)
+                        if next_text.strip() and not _is_only_tool_results(u_content):
+                            if CORRECTION_PATTERNS.search(next_text):
+                                followed_by_correction = True
+                                correction_text = next_text
+                            break
+
+            error_was_recovered = (
+                followed_by_error
+                and success_after_error > 0
+                and not followed_by_correction
+            )
+
+            ts = _parse_timestamp(obj)
+            model_id = ""
+            model_tier = "unknown"
+
+            rec = {
+                "runtime": "claude",
+                "session_file": str(sf),
+                "timestamp": ts,
+                "prompt_text": truncate(prompt_text, PROMPT_TEXT_LIMIT),
+                "prompt_length": len(prompt_text),
+                "prompt_position": position,
+                "total_prompts_in_session": total_in_session,
+                "has_xml_tags": bool(re.search(r"<\w[\w-]*>", prompt_text)),
+                "has_file_paths": bool(re.search(r"(/[\w./\-]+|~\/[\w./\-]+|\.\./)", prompt_text)),
+                "has_code_blocks": "```" in prompt_text,
+                "followed_by_error": followed_by_error,
+                "error_was_recovered": error_was_recovered,
+                "followed_by_correction": followed_by_correction,
+                "correction_text": truncate(correction_text, CORRECTION_TEXT_LIMIT),
+                "error_tool": error_tool,
+                "error_text": truncate(error_text, 500),
+                "context_before": truncate(context_before, CONTEXT_BEFORE_LIMIT),
+                "model": model_id,
+                "model_tier": model_tier,
+                "task_complexity": classify_complexity(prompt_text),
+                "recommended_tier": COMPLEXITY_TO_TIER[classify_complexity(prompt_text)],
+                "compute_was_overkill": False,
+            }
+            prompts.append(rec)
+
+    return prompts
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Extract user prompts from AI assistant session files."
+    )
+    parser.add_argument(
+        "days_positional",
+        nargs="?",
+        type=int,
+        default=None,
+        metavar="DAYS",
+        help="Number of days to look back (positional shorthand).",
+    )
+    parser.add_argument(
+        "--days",
+        type=int,
+        default=None,
+        help="Number of days to look back (default 7).",
+    )
+    parser.add_argument(
+        "--runtime",
+        type=str,
+        default="auto",
+        help=f"Runtime to scan: auto, {', '.join(list_runtime_ids())} (default: auto).",
+    )
+    args = parser.parse_args()
+
+    # Resolve days: positional takes precedence over --days, both default to 7.
+    days = args.days_positional or args.days or 7
+
+    # Resolve adapters — unknown runtime exits 0 cleanly.
+    try:
+        adapters = get_adapters(args.runtime)
+    except ValueError as exc:
+        print(f"No data: {exc}", file=sys.stderr)
+        _write_empty(days, args.runtime)
+        return
+
+    cutoff = time.time() - (days * 86400)
+
+    all_prompts: list[dict[str, Any]] = []
+    sessions_scanned = 0
+    projects_seen: set[str] = set()
+
+    for adapter in adapters:
+        session_files = adapter.discover()
+
+        # Filter by age
+        recent_files = []
+        for sf in session_files:
+            try:
+                if sf.stat().st_mtime >= cutoff:
+                    recent_files.append(sf)
+            except OSError:
+                continue
+
+        if not recent_files:
+            # This adapter found no data — degrade cleanly.
+            continue
+
+        sessions_scanned += len(recent_files)
+
+        if adapter.RUNTIME_ID == "claude":
+            # Use full session-aware extraction for Claude to detect error context.
+            prompts = process_claude_sessions(recent_files, cutoff)
+        else:
+            # For other runtimes: simple parse without cross-turn context detection.
+            raw_by_session: dict[str, list[dict]] = {}
+            for sf in recent_files:
+                raws = adapter.parse(sf)
+                raw_by_session[str(sf)] = raws
+
+            prompts = []
+            for sf_str, raws in raw_by_session.items():
+                total = len(raws)
+                for pos, raw in enumerate(raws, 1):
+                    rec = normalise_record(raw, pos, total)
+                    prompts.append(rec)
+
+        # Collect project identifiers.
+        for sf in recent_files:
+            projects_seen.add(str(sf.parent))
+
+        all_prompts.extend(prompts)
+
+    if not all_prompts:
+        runtime_label = args.runtime
+        print(
+            f"No transcript data found for runtime '{runtime_label}' "
+            f"in the last {days} days.",
+            file=sys.stderr,
+        )
+        print(
+            "If you are using a supported runtime, check that its session "
+            "directory exists and contains recent files."
+        )
+        _write_empty(days, args.runtime)
+        return
+
+    # Prioritise error/correction prompts, then cap.
+    error_prompts = [p for p in all_prompts if p.get("followed_by_error") or p.get("followed_by_correction")]
+    clean_prompts = [p for p in all_prompts if not p.get("followed_by_error") and not p.get("followed_by_correction")]
+    all_prompts = (error_prompts + clean_prompts)[:MAX_PROMPTS]
+
+    total = len(all_prompts)
+    errors = sum(1 for p in all_prompts if p.get("followed_by_error"))
+    recovered = sum(1 for p in all_prompts if p.get("error_was_recovered"))
+    unrecovered = errors - recovered
+    corrections = sum(1 for p in all_prompts if p.get("followed_by_correction"))
+    avg_length = sum(p["prompt_length"] for p in all_prompts) / total if total else 0
+    xml_count = sum(1 for p in all_prompts if p.get("has_xml_tags"))
+    fp_count = sum(1 for p in all_prompts if p.get("has_file_paths"))
+    overkill_count = sum(1 for p in all_prompts if p.get("compute_was_overkill"))
+
+    # Model tier distribution
+    tier_dist: dict[str, int] = {}
+    for p in all_prompts:
+        t = p.get("model_tier", "unknown")
+        tier_dist[t] = tier_dist.get(t, 0) + 1
+
+    compute_stats = {
+        "tier_distribution": {t: round(c / total, 3) for t, c in tier_dist.items()},
+        "heuristic_overuse_count": overkill_count,
+        "heuristic_overuse_rate": round(overkill_count / total, 3) if total else 0,
+    }
+
+    result = {
+        "prompts": all_prompts,
+        "metadata": {
+            "runtime": args.runtime,
+            "days": days,
+            "sessions_scanned": sessions_scanned,
+            "projects_scanned": len(projects_seen),
+            "total_prompts": total,
+            "error_rate": round(errors / total, 3) if total else 0,
+            "recovered_error_rate": round(recovered / total, 3) if total else 0,
+            "effective_error_rate": round(unrecovered / total, 3) if total else 0,
+            "correction_rate": round(corrections / total, 3) if total else 0,
+            "avg_length": round(avg_length, 1),
+            "xml_usage_rate": round(xml_count / total, 3) if total else 0,
+            "file_path_rate": round(fp_count / total, 3) if total else 0,
+        },
+        "compute_stats": compute_stats,
+    }
+
+    # Write output to a temp file.
+    fd, out_path = tempfile.mkstemp(prefix="roast-me-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(result, fh, indent=2, default=str)
+    except OSError as exc:
+        print(f"Failed to write output: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Scanned {sessions_scanned} sessions across {len(projects_seen)} projects")
+    print(
+        f"Extracted {total} prompts "
+        f"({errors} with errors, {recovered} auto-recovered, {unrecovered} impactful)"
+    )
+    print(f"Corrections: {corrections} | Avg length: {avg_length:.0f} chars | XML: {xml_count}/{total}")
+    print(f"Compute: {overkill_count} overkill | tiers: {tier_dist}")
+    print(f"Output: {out_path}")
+
+
+def _write_empty(days: int, runtime: str) -> None:
+    """Write an empty result JSON and print its path."""
+    result: dict[str, Any] = {
+        "prompts": [],
+        "metadata": {
+            "runtime": runtime,
+            "days": days,
+            "sessions_scanned": 0,
+            "projects_scanned": 0,
+            "total_prompts": 0,
+            "error_rate": 0,
+            "recovered_error_rate": 0,
+            "effective_error_rate": 0,
+            "correction_rate": 0,
+            "avg_length": 0,
+            "xml_usage_rate": 0,
+            "file_path_rate": 0,
+        },
+        "compute_stats": {},
+    }
+    fd, out_path = tempfile.mkstemp(prefix="roast-me-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(result, fh, indent=2)
+    except OSError:
+        pass
+    print(f"Output: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ship
-description: "Use when the work is complete and verified and it is time to CLOSE the development branch — the final phase of the rsc SDD chain, after review approves the diff. Triggers: 'ship it', 'close the branch', 'open the PR', 'merge this', 'merge into main', 'create the pull request', 'how do I land this work', 'finish this feature', 'haz el merge', 'abre el PR', 'cierra la rama', 'súbelo a main', 'clean up the branch', 'I'm done, what now'. Presents exactly three landing options (direct merge / pull request / park-or-discard) matched to the workflow, runs the pre-ship safety checklist (review verdict, clean tree, rebased, no secrets), and writes the commit and PR. HARD RULE: git authorship is ALWAYS Eric — never Claude. No Co-Authored-By Claude, no 'generated with' footer in any commit or PR body. NOT running lint/type/test (that is verify), NOT reading the diff adversarially (that is review), NOT the deploy/release mechanics to a server (that is deployment). Honors the harness accompaniment dial."
+description: "Use when the work is complete and verified and it is time to CLOSE the development branch — the final phase of the rsc SDD chain, after review approves the diff. Triggers: 'ship it', 'close the branch', 'open the PR', 'merge this', 'merge into main', 'create the pull request', 'how do I land this work', 'finish this feature', 'haz el merge', 'abre el PR', 'cierra la rama', 'súbelo a main', 'clean up the branch', 'I'm done, what now'. HARD RULE it enforces: git authorship is ALWAYS Eric — never a Co-Authored-By or 'generated with' footer in any commit or PR. NOT running lint/type/test (that is `verify`), NOT reading the diff adversarially (that is `review`), NOT deploy/release mechanics to a server (that is `deployment`). Honors the harness accompaniment dial."
 tags: [sdd, ship, release, pr]
 recommends: []
 profiles: [core, full]
@@ -178,6 +178,14 @@ Never stack to hide review risk. Stack because each slice is independently revie
 - **Park:** leave the branch, push it so it's not lost (`git push -u origin feature/<slug>`), and log *why it's parked* to `02-DOCS/wiki/sdd/decisions.md`. Do not merge.
 - **Discard:** deletion is **destructive** — require an explicit confirmation that quotes the branch name (e.g. the literal `yes, delete feature/<slug>`) before `git branch -D`. Anything ambiguous means keep it. Log the discard and the reason so the dead-end is remembered, not re-attempted.
 
+**If the work lived in a worktree, clean it up provenance-aware.** After the merge/park/discard, only
+remove a worktree **rsc created** (under `.worktrees/`/`worktrees/` or the `../<repo>-<slug>` dir),
+never one the user or a native tool owns. Guard first: confirm it's a linked worktree
+(`git rev-parse --git-dir` ≠ `--git-common-dir`), rule out a submodule
+(`git rev-parse --show-superproject-working-tree` is empty), `cd` to the main working tree before
+removing, and run `git worktree prune` after. Full procedure: `../worktrees/SKILL.md` (Provenance-aware
+cleanup). If a native `EnterWorktree`-style tool created it, exit through that tool, not raw git.
+
 ## Commit message discipline
 
 The commit is the durable record. Make it describe the change and tie it to the spec — and keep it Eric's.

package/skills/specify/SKILL.md

@@ -100,7 +100,8 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
                             after EACH section ask "does this look right?" and adjust before moving on
 7. WRITE the spec         → 02-DOCS/wiki/sdd/specs/<slug>.md (WHAT/WHY), index it in 02-DOCS/wiki/index.md
                             (the Knowledge map; root CLAUDE.md keeps only a short pointer), commit if a repo
-8. SELF-REVIEW            → scan for TODO/placeholder, contradictions, ambiguity, scope creep; fix inline
+8. SELF-REVIEW            → scan for TODO/placeholder, contradictions, ambiguity, scope creep; fix inline.
+                            On L2/L3 or a high-risk spec, also dispatch a FRESH-EYES review (below)
 9. USER APPROVES          → ask them to read the written spec and confirm; loop on changes until they approve
 10. HAND OFF              → only now, result envelope → clarify/plan. NEVER to implement.
 ```
@@ -110,6 +111,25 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
 
 `<slug>` is a short kebab-case name derived from the feature (e.g. `bulk-csv-import`, `magic-link-login`). If a spec with that slug exists, read it and update rather than overwrite.
 
+### Fresh-eyes spec review (step 8, scaled to the dial)
+
+The author's own context is blind to its own gaps — the same mind that wrote the spec self-reviews it
+with the same blind spots. For an L2/L3 user or a **high-risk** spec (multi-subsystem, security/data,
+irreversible, or large scope), dispatch a **fresh-context subagent** to read the written spec cold,
+*before* the user-approval gate (step 9), and fold its findings in:
+
+- **Hand it only the spec file** (and the constitution), not your dialogue or reasoning — a fresh
+  reviewer that inherits your context inherits your blind spots.
+- **Calibrated checklist:** placeholders/TODOs, internal contradictions, ambiguity that would stall
+  planning, unstated assumptions, scope creep, and YAGNI (asked-for-but-unneeded). Tell it to *only
+  flag issues that would cause a real problem at planning time* and to **approve unless there are
+  serious gaps** — a fresh reviewer that nitpicks everything is as useless as no reviewer.
+- **It returns** `Approved` or `Issues found` with a short list; you fix the real ones inline, then
+  proceed to step 9.
+
+**Skip it** for L0/L1 on a small, low-risk spec — the self-review scan is enough there; don't spin up
+a subagent to vet a two-paragraph spec. Like the rest of the chain, ceremony scales to the stakes.
+
 ## Worked shape (abridged)
 
 ```markdown

package/skills/tasks/SKILL.md

@@ -175,6 +175,31 @@ delete a user's map entry).
 | T0NN |  | All done-checks pass + `verify.sh` green | every row above checked; `scripts/verify.sh` exits 0 | all | spec §Acceptance |
 ```
 
+### Per-task Interfaces (for context-isolated implementers)
+
+`implement` and `parallel` dispatch tasks to **context-isolated** workers (the `developer`
+subagent) that see *only their own task* — not the whole plan. Such a worker can't infer a
+neighbor's function signature, payload shape, or column name from a one-line row. For any task
+whose correctness depends on a contract it doesn't own, attach an **Interfaces block** right under
+its row. (Trivial, self-contained tasks don't need one — don't add ceremony where there's no
+cross-task contract.)
+
+```markdown
+**T004 — Interfaces**
+- Consumes: `auth.verifyPassword(plain: str, hash: str) -> bool` (from T003); `users.email UNIQUE`
+- Produces: `POST /login` → `200 {token}` | `401 {error}`; sets `Set-Cookie: sid=…; HttpOnly`
+```
+
+Rules:
+
+- Quote **exact** signatures/shapes, not descriptions — the isolated worker copies them, it can't
+  go look them up. "Returns the user" is invisible; `-> {id, email}` is usable.
+- `Consumes` names what the task reads from a neighbor or the environment; `Produces` names the
+  contract later tasks (and the per-task reviewer) will hold it to.
+- The plan's **§0 Global Constraints** are inherited by every task implicitly — do **not** repeat
+  them per task. Interfaces carry the *task-local* contract; Global Constraints carry the
+  *project-wide* one. Together they are everything a blind implementer needs.
+
 ## Review workload + delivery strategy forecast
 
 After the task table, append a short forecast. This protects the human reviewer

package/skills/worktrees/SKILL.md

@@ -115,6 +115,31 @@ Either way, the contract is identical: **after this step, the cwd is an isolated
 base, and the default-branch checkout is exactly as it was.** Confirm that out loud (at the dial's
 level) before handing to `implement`.
 
+### Provenance-aware cleanup (don't remove a workspace you didn't create)
+
+Removing the wrong worktree leaves phantom state and can destroy someone else's in-progress work.
+Before any `git worktree remove`, clear these guards:
+
+```bash
+# 1) Are we even inside a linked worktree? (GIT_DIR != GIT_COMMON_DIR ⇒ yes)
+[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] && echo "linked worktree"
+# 2) Submodule false-positive guard — never treat a submodule as a worktree to remove
+git rev-parse --show-superproject-working-tree   # non-empty ⇒ this is a submodule; STOP
+# 3) cd to the MAIN working tree before removing (you cannot remove the worktree you stand in)
+cd "$(git rev-parse --git-common-dir)/.."
+git worktree remove <path>
+git worktree prune                                # self-heal stale administrative entries
+```
+
+- **Only remove worktrees rsc/you created** — those under `.worktrees/` or `worktrees/`, or the
+  `../<repo>-<slug>` this skill made. A worktree the user or a native tool owns is **not yours to
+  delete**; leave it and say so.
+- **Native tool owns its own lifecycle.** If you isolated via a native `EnterWorktree`-style tool,
+  exit through that tool's `remove`/`keep` — do **not** hand-run `git worktree remove` on a workspace
+  the native tool created; let it clean up so its tracking stays consistent.
+- **`git worktree prune`** after a remove clears stale metadata when a directory vanished out from
+  under git — cheap self-healing, safe to run.
+
 ## Native vs. git fallback — which you're using
 
 | You have… | Create | Leave intact | Discard |