@runecraft/grimoire 1.0.0

package/skills/deprecation-and-migration/scripts/migration_tracker.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""
+migration_tracker.py — deterministic per-consumer migration tracking.
+
+Tracks migration status for a single deprecation effort (identified by --slug).
+Canonical state lives in .migrations/<slug>/state.json; a human-readable
+STATUS.md is regenerated on every write.
+
+Pure standard library. No dependencies. Run from the project root (the dir
+that contains .migrations), or pass --root.
+
+Commands:
+  add-consumer    Register a consumer with a migration status.
+  mark-migrated   Flip a consumer to migrated with an evidence note.
+  status          Print aggregate counts (total, pending, migrating, done).
+  list-pending    Print consumers not yet migrated.
+
+Exit codes: 0 ok, 2 usage/validation error.
+"""
+
+import argparse
+import datetime as _dt
+import json
+import os
+import sys
+
+MIGRATIONS_DIR = ".migrations"
+
+VALID_STATUSES = {"pending", "migrating", "done"}
+
+
+def _now():
+	return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _store_path(root, slug):
+	return os.path.join(root, MIGRATIONS_DIR, slug, "state.json")
+
+
+def _render_path(root, slug):
+	return os.path.join(root, MIGRATIONS_DIR, slug, "STATUS.md")
+
+
+def _slug_dir(root, slug):
+	return os.path.join(root, MIGRATIONS_DIR, slug)
+
+
+def _load(root, slug):
+	path = _store_path(root, slug)
+	if not os.path.exists(path):
+		return {"slug": slug, "consumers": []}
+	with open(path, "r", encoding="utf-8") as f:
+		data = json.load(f)
+	data.setdefault("slug", slug)
+	data.setdefault("consumers", [])
+	return data
+
+
+def _save(root, slug, data):
+	os.makedirs(_slug_dir(root, slug), exist_ok=True)
+	with open(_store_path(root, slug), "w", encoding="utf-8") as f:
+		json.dump(data, f, indent=2, ensure_ascii=False)
+		f.write("\n")
+	_render(root, slug, data)
+
+
+def _find_consumer(data, name):
+	for c in data["consumers"]:
+		if c["name"] == name:
+			return c
+	return None
+
+
+def _render(root, slug, data):
+	consumers = data["consumers"]
+	total = len(consumers)
+	pending = sum(1 for c in consumers if c["status"] == "pending")
+	migrating = sum(1 for c in consumers if c["status"] == "migrating")
+	done = sum(1 for c in consumers if c["status"] == "done")
+
+	lines = []
+	lines.append(f"# Migration Status: `{slug}`")
+	lines.append("")
+	lines.append("> Auto-maintained by `scripts/migration_tracker.py`. Do NOT hand-edit.")
+	lines.append(f"> Canonical state lives in `.migrations/{slug}/state.json`.")
+	lines.append("")
+	lines.append("## Summary")
+	lines.append("")
+	lines.append("| Metric | Count |")
+	lines.append("| ------ | ----- |")
+	lines.append(f"| Total  | {total} |")
+	lines.append(f"| Pending | {pending} |")
+	lines.append(f"| Migrating | {migrating} |")
+	lines.append(f"| Done | {done} |")
+	lines.append("")
+
+	if not consumers:
+		lines.append("_(no consumers registered)_")
+		lines.append("")
+	else:
+		lines.append("## Consumers")
+		lines.append("")
+		lines.append("| Consumer | Status | Evidence | Last Updated |")
+		lines.append("| -------- | ------ | -------- | ------------ |")
+		for c in sorted(consumers, key=lambda x: x.get("created", "")):
+			evidence = c.get("evidence_note") or "\u2014"
+			updated = c.get("updated", c.get("created", "\u2014"))
+			lines.append(f"| {c['name']} | {c['status']} | {evidence} | {updated} |")
+		lines.append("")
+
+	with open(_render_path(root, slug), "w", encoding="utf-8") as f:
+		f.write("\n".join(lines).rstrip() + "\n")
+
+
+# ----------------------------- commands -----------------------------
+
+
+def cmd_add_consumer(root, args):
+	slug = args.slug
+	consumer_name = args.consumer
+	status = args.status
+
+	data = _load(root, slug)
+	existing = _find_consumer(data, consumer_name)
+	now = _now()
+
+	if existing:
+		existing["status"] = status
+		existing["updated"] = now
+		_save(root, slug, data)
+		print(f"UPDATED {consumer_name} -> {status}")
+	else:
+		data["consumers"].append({
+			"name": consumer_name,
+			"status": status,
+			"evidence_note": None,
+			"created": now,
+			"updated": now,
+		})
+		_save(root, slug, data)
+		print(f"ADDED {consumer_name} -> {status}")
+	return 0
+
+
+def cmd_mark_migrated(root, args):
+	slug = args.slug
+	consumer_name = args.consumer
+	note = (args.note or "").strip()
+
+	data = _load(root, slug)
+	existing = _find_consumer(data, consumer_name)
+
+	if not existing:
+		print(f"ERROR: consumer '{consumer_name}' not registered for slug '{slug}'. Use add-consumer first.", file=sys.stderr)
+		return 2
+
+	now = _now()
+	existing["status"] = "done"
+	existing["evidence_note"] = note if note else None
+	existing["updated"] = now
+	_save(root, slug, data)
+	print(f"MIGRATED {consumer_name} ({note if note else 'no note'})")
+	return 0
+
+
+def cmd_status(root, args):
+	slug = args.slug
+	data = _load(root, slug)
+	consumers = data["consumers"]
+
+	if not consumers:
+		print("(no consumers registered)")
+		return 0
+
+	total = len(consumers)
+	pending = sum(1 for c in consumers if c["status"] == "pending")
+	migrating = sum(1 for c in consumers if c["status"] == "migrating")
+	done = sum(1 for c in consumers if c["status"] == "done")
+
+	print(f"{slug}: {total} total | pending={pending} migrating={migrating} done={done}")
+	return 0
+
+
+def cmd_list_pending(root, args):
+	slug = args.slug
+	data = _load(root, slug)
+
+	if not data["consumers"]:
+		print("(no consumers registered)")
+		return 0
+
+	pending = [c for c in data["consumers"] if c["status"] in ("pending", "migrating")]
+
+	if not pending:
+		print("(no pending consumers)")
+		return 0
+
+	for c in sorted(pending, key=lambda x: x.get("created", "")):
+		print(f"{c['name']} ({c['status']})")
+	return 0
+
+
+def main(argv=None):
+	p = argparse.ArgumentParser(
+		prog="migration_tracker.py",
+		description="Deterministic per-consumer migration tracking.",
+	)
+	p.add_argument("--root", default=".", help="Project root containing .migrations/ (default: current dir)")
+	sub = p.add_subparsers(dest="cmd", required=True)
+
+	sp = sub.add_parser("add-consumer", help="Register a consumer with a migration status")
+	sp.add_argument("--slug", required=True, help="Migration effort slug")
+	sp.add_argument("--consumer", required=True, help="Consumer name")
+	sp.add_argument("--status", required=True, choices=sorted(VALID_STATUSES), help="Migration status")
+	sp.set_defaults(fn=cmd_add_consumer)
+
+	sp = sub.add_parser("mark-migrated", help="Flip a consumer to migrated with an evidence note")
+	sp.add_argument("--slug", required=True, help="Migration effort slug")
+	sp.add_argument("--consumer", required=True, help="Consumer name")
+	sp.add_argument("--note", required=True, help="Evidence note for the migration")
+	sp.set_defaults(fn=cmd_mark_migrated)
+
+	sp = sub.add_parser("status", help="Print aggregate counts")
+	sp.add_argument("--slug", required=True, help="Migration effort slug")
+	sp.set_defaults(fn=cmd_status)
+
+	sp = sub.add_parser("list-pending", help="Print consumers not yet migrated")
+	sp.add_argument("--slug", required=True, help="Migration effort slug")
+	sp.set_defaults(fn=cmd_list_pending)
+
+	args = p.parse_args(argv)
+	root = os.path.abspath(args.root)
+	return args.fn(root, args)
+
+
+if __name__ == "__main__":
+	raise SystemExit(main())

package/skills/doubt-driven-development/README.md

@@ -0,0 +1,13 @@
+# doubt-driven-development
+
+Adversarial review of every non-trivial decision before it stands: CLAIM → EXTRACT → DOUBT → RECONCILE → STOP.
+
+| Field | Value |
+|-------|-------|
+| Version | 1.0.0 |
+| Trigger | `/harden`, "stress-test this", "play devil's advocate", "fresh-context review" |
+| PT trigger | `/endurecer`, "questionar decisão", "será que tô certo?" |
+
+**Do not use for** trivial changes where the cost of doubt exceeds the cost of a bug, or for finished artifact review (that's `/review`).
+
+See [SKILL.md](SKILL.md) for the full process.

package/skills/doubt-driven-development/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: doubt-driven-development
+description: >
+  Subjects every non-trivial decision to a fresh-context adversarial review (CLAIM → EXTRACT →
+  DOUBT → RECONCILE → STOP) before it stands. Use when correctness matters more than speed,
+  in unfamiliar code, or when stakes are high (production, security-sensitive logic, irreversible ops).
+  EN triggers: /harden, "stress-test this", "play devil's advocate", fresh-context review, CLAIM EXTRACT DOUBT.
+  PT triggers: /endurecer, questionar decisão, revisar com olhos novos, "será que tô certo?".
+  Do NOT use for: trivial changes where the cost of doubt exceeds the cost of a bug, or for finished
+  artifact review (that's /review).
+license: CC-BY-4.0
+---
+
+# Doubt-Driven Development
+
+## Overview
+
+A confident answer is not a correct one. Long sessions accumulate context that quietly turns assumptions into "facts" without anyone noticing. Doubt-driven development is the discipline of materializing a fresh-context reviewer — biased to **disprove**, not approve — before any non-trivial output stands.
+
+This is not `/review`. `/review` is a verdict on a finished artifact. This is an in-flight posture: non-trivial decisions get cross-examined while course-correction is still cheap.
+
+## When to Use
+
+A decision is **non-trivial** when at least one of these is true:
+
+- It introduces or modifies branching logic
+- It crosses a module or service boundary
+- It asserts a property the type system or compiler cannot verify (thread safety, idempotence, ordering, invariants)
+- Its correctness depends on context the future reader cannot see
+- Its blast radius is irreversible (production deploy, data migration, public API change)
+
+Apply the skill when:
+
+- About to make an architectural decision under uncertainty
+- About to commit non-trivial code
+- About to claim a non-obvious fact ("this is safe", "this scales", "this matches the spec")
+- Working in code you don't fully understand
+
+**When NOT to use:**
+
+- Mechanical operations (renaming, formatting, file moves)
+- Following a clear, unambiguous user instruction
+- Reading or summarizing existing code
+- One-line changes with obvious correctness
+- Pure tooling operations (running tests, listing files)
+- The user has explicitly asked for speed over verification
+
+If you doubt every keystroke, you ship nothing. The skill applies only to non-trivial decisions as defined above.
+
+## Loading Constraints
+
+This skill is designed for the **main-session orchestrator**, where Step 3 (DOUBT, detailed below) can spawn a fresh-context reviewer.
+
+- **Do NOT add this skill to a persona's `skills:` frontmatter.** A persona that follows Step 3 would spawn another persona — the orchestration anti-pattern ("personas do not invoke other personas").
+- **If you find yourself applying this skill from inside a subagent context** (where Claude Code prevents nested subagent spawn): the preferred path is to surface to the user that doubt-driven cannot run nested and let the main session handle it. As a last resort only, a degraded self-questioning fallback exists — rewrite ARTIFACT + CONTRACT as a fresh self-prompt with a hard mental separator from your prior reasoning, and walk Steps 1–5. This is **not fresh-context review** (you carry your own context with you), so flag the result as degraded and prefer escalation whenever the user is reachable.
+
+## The Process
+
+Copy this checklist when applying the skill:
+
+```
+Doubt cycle:
+- [ ] Step 1: CLAIM — wrote the claim + why-it-matters
+- [ ] Step 2: EXTRACT — isolated artifact + contract, stripped reasoning
+- [ ] Step 3: DOUBT — invoked fresh-context reviewer with adversarial prompt
+- [ ] Step 4: RECONCILE — classified every finding against the artifact text
+- [ ] Step 5: STOP — met stop condition (trivial findings, 3 cycles, or user override)
+```
+
+### Step 1: CLAIM — Surface what stands
+
+Name the decision in two or three lines:
+
+```
+CLAIM: "The new caching layer is thread-safe under the
+        read-heavy workload described in the spec."
+WHY THIS MATTERS: a race here corrupts user data and is
+                  hard to detect in QA.
+```
+
+If you can't write the claim that compactly, you have a vibe, not a decision. Surface it before scrutinizing it.
+
+### Step 2: EXTRACT — Smallest reviewable unit
+
+A fresh-context reviewer needs the **artifact** and the **contract**, not the journey.
+
+- Code: the diff or the function — not the whole file
+- Decision: the proposal in 3–5 sentences plus the constraints it has to satisfy
+- Assertion: the claim plus the evidence that supposedly supports it (kept distinct from the Step 1 CLAIM block, which is the orchestrator's hypothesis under scrutiny)
+
+Strip your reasoning. If you hand over conclusions, you'll get back validation of your conclusions. The unit must be small enough that a reviewer can hold it in mind in one read — if it's a 500-line PR, decompose first.
+
+### Step 3: DOUBT — Invoke the fresh-context reviewer
+
+The reviewer's prompt **must be adversarial**. Framing decides the answer.
+
+```
+Adversarial review. Find what is wrong with this artifact.
+Assume the author is overconfident. Look for:
+- Unstated assumptions
+- Edge cases not handled
+- Hidden coupling or shared state
+- Ways the contract could be violated
+- Existing conventions this might break
+- Failure modes under unexpected input
+
+Do NOT validate. Do NOT summarize. Find issues, or state
+explicitly that you cannot find any after thorough examination.
+
+ARTIFACT: <paste artifact>
+CONTRACT: <paste contract>
+```
+
+**Pass ARTIFACT + CONTRACT only. Do NOT pass the CLAIM.** Handing the reviewer your conclusion biases it toward agreement. The reviewer must independently determine whether the artifact satisfies the contract.
+
+In Claude Code, the role-based reviewers in `agents/` start with isolated context by design and are usable here — see `agents/` for the roster and per-domain match.
+
+**The adversarial prompt above takes precedence over the persona's default response shape.** Personas like `code-reviewer` are written to produce balanced verdicts with both strengths and weaknesses; doubt-driven needs issues-only output. Paste the adversarial prompt verbatim into the invocation so it overrides the persona's default. If a persona's response shape can't be overridden cleanly, fall back to a generic subagent with the adversarial prompt.
+
+#### Cross-model escalation
+
+A single-model reviewer shares blind spots with the original author — a colder, different-architecture model catches them. Doubt-driven is already opt-in for non-trivial decisions, so within that scope offering cross-model is part of the skill's value, not optional friction.
+
+**Interactive sessions: always offer. Never silently skip.**
+
+**Step 1: Ask the user**
+
+After the single-model review in Step 3 above, but before RECONCILE, pause and ask:
+
+> *"Single-model review complete. Want a cross-model second opinion? Options: Gemini CLI, Codex CLI, manual external review (you paste it elsewhere), or skip."*
+
+This question is mandatory in every interactive doubt cycle — even on artifacts that feel low-stakes. The user — not the agent — decides whether the cost is worth it. The agent's job is to surface the choice.
+
+**Step 2: If the user picks a CLI — verify, then invoke**
+
+1. Check the tool is in PATH (`which gemini`, `which codex`).
+2. Test it works (`gemini --version` or equivalent) before passing the full prompt — a stale or broken binary may pass `which` but fail on real input.
+3. Confirm the exact invocation with the user, including required flags, auth, and env vars (e.g., API keys). Implementations vary; never assume.
+4. Pass ARTIFACT + CONTRACT + the adversarial prompt **only**. No session context, no CLAIM.
+5. Mind shell escaping. If the artifact contains quotes, `$(...)`, or backticks, prefer stdin (`echo … | gemini`) or a heredoc over inline `-p "…"`. When in doubt, ask the user to confirm the invocation before running it.
+6. Take the output into Step 4 (RECONCILE).
+
+**Never interpolate the artifact into a shell-quoted argument.** Code, markdown, and review prompts routinely contain backticks, `$(...)`, and quote characters that will either truncate the prompt or execute embedded shell. Write the full prompt to a file and pipe it through stdin.
+
+Example shapes (verify flags against your installed tool — syntax differs across implementations and versions):
+
+```bash
+# Write the adversarial prompt + ARTIFACT + CONTRACT to a temp file first.
+# Then pipe via stdin so shell metacharacters in the artifact stay inert.
+
+# Codex (read-only sandbox keeps the CLI from writing to your workspace):
+codex exec --sandbox read-only -C <repo-path> - < /tmp/doubt-prompt.md
+
+# Gemini ('--approval-mode plan' is read-only; '-p ""' triggers non-interactive
+# mode and the prompt is read from stdin):
+gemini --approval-mode plan -p "" < /tmp/doubt-prompt.md
+```
+
+A read-only sandbox is the load-bearing detail: a doubt artifact may itself contain instructions (intentional or accidental prompt injection) that the cross-model CLI would otherwise execute against your workspace.
+
+**Step 3: If the CLI is unavailable or fails**
+
+Surface the failure explicitly. Offer: run it manually, try a different tool, or skip. Do not silently fall back to single-model — the user should know cross-model didn't happen.
+
+**Step 4: If the user skips**
+
+Acknowledge the skip in the output (*"Proceeding with single-model findings only"*) and continue to RECONCILE. Skipping is fine; silent skipping is not.
+
+**Non-interactive contexts** (CI, `/loop`, autonomous-loop, scheduled runs):
+
+- Cross-model is **skipped**, and the skip must be **announced** in the output: *"Cross-model skipped: non-interactive context."*
+- **Never invoke an external CLI without explicit user authorization** — this is a load-bearing safety property.
+
+Cross-model adds cost, latency, and tool fragility. The agent surfaces the choice every cycle; the user decides whether this artifact warrants it.
+
+### Step 4: RECONCILE — Fold findings back
+
+The reviewer's output is data, not verdict. **You are still the orchestrator.** Re-read the artifact text against each finding before classifying — rubber-stamping the reviewer is the same failure mode as ignoring it.
+
+For each finding, classify in this **precedence order** (first matching class wins):
+
+1. **Contract misread** — reviewer flagged something specifically because the CONTRACT you provided was unclear or incomplete. Fix the contract first, re-classify on the next cycle.
+2. **Valid + actionable** — real issue requiring a change to the artifact. Change it, re-loop.
+3. **Valid trade-off** — issue is real but cost of fixing exceeds cost of accepting. Document the trade-off explicitly so the user sees it.
+4. **Noise** — reviewer flagged something that's actually correct under context the reviewer didn't have. Note it, move on, and ask: would adding that context to the contract have prevented the false flag?
+
+A fresh reviewer can be wrong because it lacks context. Don't defer just because it's "fresh."
+
+### Step 5: STOP — Bounded loop, not recursion
+
+Stop when:
+
+- Next iteration returns only trivial or already-considered findings, **or**
+- 3 cycles completed (escalate to user, don't grind a fourth alone), **or**
+- User explicitly says "ship it"
+
+If after 3 cycles the reviewer still surfaces substantive issues, the artifact may not be ready. Surface this to the user — three unresolved cycles is information about the artifact, not a reason to keep looping.
+
+If 3 cycles is "obviously insufficient" because the artifact is large: the artifact is too big — return to Step 2 and decompose. Do not lift the bound.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'm confident, skip the doubt step" | Confidence correlates poorly with correctness on novel problems. Moments of certainty are exactly when blind spots hide. |
+| "Spawning a reviewer is expensive" | Debugging a wrong commit in production is more expensive. The check is bounded; the bug isn't. |
+| "The reviewer will just nitpick" | Only if unscoped. Constrain the prompt to "issues that would make this fail under the contract." |
+| "I'll do doubt at the end with `/review`" | `/review` is a final gate. Doubt-driven catches wrong directions early when course-correction is cheap. By PR time it's too late. |
+| "If I doubt every step I'll never ship" | The skill applies to non-trivial decisions, not every keystroke. Re-read "When NOT to Use." |
+| "Two opinions are always better than one" | Not when the second has less context and produces noise. Reconcile, don't defer. |
+| "The reviewer disagreed so I was wrong" | The reviewer lacks your context — disagreement is information, not verdict. Re-read the artifact, classify, then decide. |
+| "Cross-model is always better" | Cross-model catches blind spots a single model shares with itself, but it adds cost and tool fragility. Offer it every interactive doubt cycle — the user decides whether the artifact warrants it. The agent's job is to surface the choice, not to gate it. |
+| "User said yes once, so I can keep invoking the CLI" | Each invocation is its own authorization. The artifact, the prompt, and the flags change between calls — re-confirm the exact command with the user before every run. |
+
+## Red Flags
+
+- Spawning a fresh-context reviewer for a one-line rename or formatting change
+- Treating reviewer output as authoritative without re-reading the artifact text
+- Looping >3 cycles without escalating to the user
+- Prompting the reviewer with "is this good?" instead of "find issues"
+- Skipping doubt under time pressure on a high-stakes decision
+- Re-spawning fresh-context on an unchanged artifact (you'll get the same findings; you're stalling)
+- **Doubt theater (checkable signal)**: across 2 or more cycles where the reviewer surfaced substantive findings, zero findings were classified as actionable. You are validating, not doubting. Stop and escalate.
+- Doubting only after committing — that's `/review`, not doubt-driven development
+- Hardcoding an external CLI invocation without confirming with the user that the tool exists, is configured, and accepts that exact syntax
+- **Silently skipping cross-model in an interactive doubt cycle.** Even when not recommending it, the offer must be visible. Skipping is fine; silent skipping is not.
+- Falling back silently when an external CLI errors or is missing — surface the failure and let the user redirect
+- Stripping the contract from the reviewer's input
+- Passing the CLAIM to the reviewer (biases toward agreement)
+
+## Interaction with Other Skills
+
+- **`code-review-and-quality` / `/review`**: complementary. `/review` is post-hoc PR verdict; doubt-driven is in-flight per-decision. Use both.
+- **Framework-fact verification**: verifying *facts about frameworks* against official docs is a different claim class. Doubt-driven verifies *your reasoning about the artifact* — checking the API exists is a fact check; checking you used it correctly under the contract is doubt-driven's job.
+- **`test-driven-development`**: TDD's RED step is doubt made concrete — a failing test is a disproof attempt. When TDD applies, that failing test *is* the doubt step for behavioral claims.
+- **`debugging-and-error-recovery`**: when the reviewer surfaces a real failure mode, drop into the debugging skill to localize and fix.
+- **Repo orchestration rules**: this skill orchestrates from the main session. A persona calling another persona is anti-pattern B — see Loading Constraints above.
+
+## Verification
+
+After applying doubt-driven development:
+
+- [ ] Every non-trivial decision (per the definition above) was named explicitly as a CLAIM before standing
+- [ ] At least one fresh-context review per non-trivial artifact (a failing test produced by TDD's RED step satisfies this for behavioral claims, per Interaction with Other Skills)
+- [ ] The reviewer received ARTIFACT + CONTRACT — NOT the CLAIM, NOT your reasoning
+- [ ] The reviewer's prompt was adversarial ("find issues"), not validating ("is it good")
+- [ ] Findings were classified against the artifact text (not rubber-stamped) using the precedence: contract misread / actionable / trade-off / noise
+- [ ] A stop condition was met (trivial findings, 3 cycles, or user override)
+- [ ] In interactive mode, cross-model was **explicitly offered** to the user (regardless of artifact stakes) and the response was acknowledged in the output
+- [ ] In non-interactive mode, cross-model was skipped and the skip was announced
+- [ ] Any external CLI invocation was preceded by a PATH check, a working-binary test, syntax confirmation with the user, and explicit authorization to run

package/skills/git-commit-learning/.skill-meta.json

@@ -0,0 +1,14 @@
+{
+  "name": "git-commit-learning",
+  "version": "1.0.0",
+  "type": "workflow-skill",
+  "description": "RPI model (Research → Plan → Implement → Verify) — analyzes git log for patterns and writes AI-learnable commits. PT/EN triggers.",
+  "modes": ["analyze", "write"],
+  "trigger": "/commit",
+  "scope": "public",
+  "audience": "development-teams",
+  "dependencies": {
+    "required": [],
+    "optional": ["spec-driven"]
+  }
+}