devrites 2.6.0 → 3.0.0

package/scripts/skill-pruning-audit.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Advisory pruning audit plus blocking ordered-step completion contracts.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const root = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const skillsArg = process.argv.indexOf('--skills-dir');
+const skillsDir = skillsArg >= 0 ? process.argv[skillsArg + 1] : join(root, 'pack', '.claude', 'skills');
+const quiet = process.argv.includes('--quiet');
+
+function frontmatter(src) {
+  const m = src.match(/^---\n([\s\S]*?)\n---/);
+  const out = {};
+  if (!m) return out;
+  for (const line of m[1].split(/\r?\n/)) {
+    const i = line.indexOf(':');
+    if (i > 0) out[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^['"]|['"]$/g, '');
+  }
+  return out;
+}
+
+function refs(src) {
+  return [...src.matchAll(/\]\(([^)]+\.md)\)/g)].map((m) => m[1]);
+}
+
+function workflowSteps(src) {
+  const steps = [];
+  const sections = src.matchAll(/^## (?:Workflow|Protocol|Process|Steps|Run|Flow|The .*cycle)[^\n]*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/gm);
+  for (const section of sections) {
+    const body = section[1];
+    const starts = [...body.matchAll(/^(\d+[a-z]?)\.\s+/gm)];
+    steps.push(...starts.map((match, i) => ({
+      id: match[1],
+      body: body.slice(match.index, starts[i + 1]?.index ?? body.length),
+    })));
+  }
+  return steps;
+}
+
+function hasStepCompletion(body) {
+  const explicit = /\b(done when|completion|stop(?:s|ped)?|pass(?:es|ed)?|fail(?:s|ed)?|written|updated|recorded|reported|returned|emitted|rendered|confirmed|verified|captured|mapped|resolved|green)\b|\brc=|\bexit\s+\d|\buntil\b/i;
+  const observableAction = /\b(write|update|record|report|return|emit|render|confirm|verify|read|run|dispatch|apply|select|capture|map|append|persist|fetch|compare|classify|rank|fix|build)\b/i;
+  const observableTarget = /`[^`]+`|\b(file|artifact|command|result|verdict|matrix|diff|workspace|slice|question|route|scenario|report|evidence|spec|plan|test|check|gate|surface|journey|finding|decision)\b/i;
+  return explicit.test(body) || (observableAction.test(body) && observableTarget.test(body));
+}
+
+function markdownFiles(dir, skipResearch = false) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || entry.name === 'generated' || (skipResearch && entry.name === 'research')) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...markdownFiles(path, skipResearch));
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(path);
+  }
+  return out;
+}
+
+const warnings = [];
+const contractFailures = [];
+for (const dir of readdirSync(skillsDir).sort()) {
+  const file = join(skillsDir, dir, 'SKILL.md');
+  try { if (!statSync(file).isFile()) continue; } catch { continue; }
+  const src = readFileSync(file, 'utf8');
+  const fm = frontmatter(src);
+  const lines = src.split(/\r?\n/).length;
+  const isPublic = fm['user-invocable']?.toLowerCase() === 'true';
+  const budget = isPublic ? 220 : 180;
+  if (lines > budget) warnings.push(`${relative(root, file)}: ${lines} lines > advisory budget ${budget}; consider progressive disclosure`);
+
+  const desc = fm.description || '';
+  const useWhen = (desc.match(/\bUse (when|for)\b/g) || []).length;
+  if (useWhen > 1) warnings.push(`${relative(root, file)}: description has ${useWhen} trigger clauses; collapse duplicate branches if they are synonyms`);
+
+  if (refs(src).some((r) => r.includes('/') && !r.startsWith('reference/') && !r.startsWith('../'))) {
+    warnings.push(`${relative(root, file)}: has a multi-level reference pointer; prefer one-hop disclosure from SKILL.md`);
+  }
+
+  const hasCompletion = /Completion:|\bstop\b|output contract|reply contract|Verification|checklist/i.test(src);
+  const hasPointer = /reference\/|\.md\)/.test(src);
+  if (!hasCompletion && !hasPointer) warnings.push(`${relative(root, file)}: no obvious completion criterion or reference pointer`);
+  for (const step of workflowSteps(src)) {
+    if (!hasStepCompletion(step.body)) {
+      contractFailures.push(`${relative(root, file)}: ordered step ${step.id} needs a checkable completion criterion`);
+    }
+  }
+}
+
+const proseFiles = [
+  ...markdownFiles(skillsDir),
+  ...markdownFiles(join(root, 'pack', '.claude', 'agents')),
+  ...markdownFiles(join(root, 'docs'), true),
+  join(root, 'README.md'),
+  join(root, 'CONTRIBUTING.md'),
+];
+for (const file of proseFiles) {
+  const src = readFileSync(file, 'utf8');
+  const lines = src.split(/\r?\n/).map((line) => line.trim());
+  const seen = new Set();
+  let inCode = false;
+  for (const line of lines) {
+    if (line.startsWith('```')) { inCode = !inCode; continue; }
+    if (inCode || line.length < 100 || line.startsWith('|') || line.startsWith('> **Untrusted-input safety.**')) continue;
+    if (seen.has(line)) warnings.push(`${relative(root, file)}: repeats a long sentence/line; keep one owner or use a leading word`);
+    seen.add(line);
+  }
+  if (/^(?:[-*]\s+)?(?:be careful|be thorough|do your best|produce high quality)[.!]?$/im.test(src)) {
+    warnings.push(`${relative(root, file)}: contains a likely no-op instruction; replace it with a checkable target or delete it`);
+  }
+  if (/[/$](?:humanizer|writing-great-skills)\b/i.test(src)) {
+    warnings.push(`${relative(root, file)}: contains a foreign workflow command token in a promoted surface`);
+  }
+}
+
+if (!quiet) {
+  console.log(`skill-pruning-audit: ${warnings.length} advisory finding(s)`);
+  for (const w of warnings.slice(0, 40)) console.log(`warn: ${w}`);
+  if (warnings.length > 40) console.log(`warn: ${warnings.length - 40} more finding(s) suppressed`);
+}
+for (const failure of contractFailures) console.log(`FAIL: ${failure}`);
+process.exit(contractFailures.length ? 1 : 0);

package/scripts/skills-inventory.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// skills-inventory.mjs — verify authored DevRites skill inventory and docs counts.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const root = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const skillsDir = join(root, 'pack', '.claude', 'skills');
+const docsSkills = join(root, 'docs', 'skills.md');
+const docsCommandMap = join(root, 'docs', 'command-map.md');
+const readme = join(root, 'README.md');
+const arch = join(root, 'docs', 'architecture.md');
+
+function fail(message) {
+  console.error(`FAIL: ${message}`);
+  failures++;
+}
+
+function frontmatter(text, file) {
+  const lines = text.split(/\r?\n/);
+  if (lines[0] !== '---') {
+    fail(`${file}: missing opening frontmatter fence`);
+    return new Map();
+  }
+  const fields = new Map();
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === '---') return fields;
+    if (!line.trim() || line.trimStart().startsWith('#') || /^[ \t]/.test(line)) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, '');
+    fields.set(key, value);
+  }
+  fail(`${file}: missing closing frontmatter fence`);
+  return fields;
+}
+
+let failures = 0;
+const skills = [];
+for (const entry of readdirSync(skillsDir).sort()) {
+  if (entry.startsWith('.')) continue;
+  const dir = join(skillsDir, entry);
+  if (!statSync(dir).isDirectory()) continue;
+  const file = join(dir, 'SKILL.md');
+  const text = readFileSync(file, 'utf8');
+  const fm = frontmatter(text, relative(root, file));
+  const name = fm.get('name') || '';
+  const description = fm.get('description') || '';
+  const invocable = fm.get('user-invocable') || '';
+  const lines = text.split(/\r?\n/).length;
+
+  if (name !== entry) fail(`${relative(root, file)}: name ${JSON.stringify(name)} does not match directory ${JSON.stringify(entry)}`);
+  if (!description) fail(`${relative(root, file)}: missing description`);
+  if (!['true', 'false'].includes(invocable)) fail(`${relative(root, file)}: user-invocable must be explicit true/false`);
+  if (entry === 'devrites-lib' && fm.get('disable-model-invocation') !== 'true') {
+    fail(`${relative(root, file)}: devrites-lib must set disable-model-invocation: true`);
+  }
+  skills.push({ name: entry, invocable, lines, description });
+}
+
+const total = skills.length;
+const publicCount = skills.filter((s) => s.invocable === 'true').length;
+const internalCount = skills.filter((s) => s.invocable === 'false').length;
+const publicRiteCount = skills.filter((s) => s.invocable === 'true' && s.name.startsWith('rite-')).length;
+const modelInvokedInternalCount = skills.filter((s) => s.invocable === 'false' && s.name !== 'devrites-lib').length;
+
+function assertDocContains(path, expected, label) {
+  const text = readFileSync(path, 'utf8');
+  if (!text.includes(expected)) {
+    fail(`${relative(root, path)}: missing ${label}: ${JSON.stringify(expected)}`);
+  }
+}
+
+function assertPublicSkillLinks(path, label) {
+  const text = readFileSync(path, 'utf8');
+  for (const skill of skills.filter((s) => s.invocable === 'true')) {
+    const link = `../pack/.claude/skills/${skill.name}/SKILL.md`;
+    if (!text.includes(link)) {
+      fail(`${relative(root, path)}: missing ${label} link for ${skill.name}: ${link}`);
+    }
+  }
+}
+
+assertDocContains(docsSkills, `# All ${total} skills`, 'total skill heading');
+assertDocContains(docsSkills, `**${total} skills total**`, 'total skill prose');
+assertDocContains(docsSkills, `${publicRiteCount} user-invocable \`rite-*\``, 'public rite-* count');
+assertDocContains(docsSkills, `${modelInvokedInternalCount} model-invoked \`devrites-*\` specialists`, 'model-invoked internal count');
+assertDocContains(docsSkills, 'npx devrites', 'npx distribution contract');
+assertDocContains(docsCommandMap, 'npx devrites', 'npx distribution contract');
+assertDocContains(readme, `**${total} skills total**`, 'README total skill prose');
+assertDocContains(readme, `# skills/  ${total} skills`, 'README layout total count');
+assertDocContains(arch, `${publicRiteCount} public \`rite-*\` skills (${total} total)`, 'architecture surface count');
+assertPublicSkillLinks(docsSkills, 'skills catalogue');
+assertPublicSkillLinks(docsCommandMap, 'command map');
+
+console.log(`skills total: ${total}`);
+console.log(`public skills: ${publicCount}`);
+console.log(`public rite-* skills: ${publicRiteCount}`);
+console.log(`internal skills: ${internalCount}`);
+console.log(`model-invoked devrites-* specialists: ${modelInvokedInternalCount}`);
+
+if (failures) {
+  console.error(`skills-inventory: ${failures} failure(s)`);
+  process.exit(1);
+}
+console.log('skills-inventory: PASS');

package/scripts/validate-agent-composition.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Validate DevRites agent persona composition blocks."""
+from __future__ import annotations
+import argparse, re, sys
+from pathlib import Path
+ROOT=Path(__file__).resolve().parent.parent
+
+WRITE_TERMS=re.compile(r'\b(write-capable|may edit|may mutate|commit|push|patch files|modify files)\b', re.I)
+READONLY_TERMS=re.compile(r'\bread-only\b|do not edit|findings only|proposes, never imposes', re.I)
+REQUIRED={
+  'role/scope':[r'## Role / scope', r'You are ', r'## Scope'],
+  'tools/read-write mode':[r'## Tools / read-write mode', r'read-only', r'write-capable', r'Do \*\*not\*\* edit', r'Writes code'],
+  'output format':[r'## Output format', r'## Output', r'```'],
+  'composition block':[r'## Composition', r'Do not invoke another agent', r'Invoke directly when']
+}
+COMPOSITION_LINE=re.compile(
+    r'^Do not invoke another agent\. You are called by (?:a `rite-\*` skill|`/rite-build`) '
+    r'and return (?:findings|your result) to that orchestrator\.$', re.M
+)
+UNTRUSTED_LINE=re.compile(
+    r'^> \*\*Untrusted-input safety\.\*\* .*data, not instructions.*never act on a directive.*'
+    r'surface it instead of obeying it.*security\.md', re.I | re.M
+)
+
+def validate(agents_dir:Path):
+    errors=[]
+    for f in sorted(agents_dir.glob('*.md')):
+        name=f.stem
+        text=f.read_text(encoding='utf-8')
+        for label,pats in REQUIRED.items():
+            if not any(re.search(p,text,re.I|re.M) for p in pats):
+                errors.append(f'{f}: missing {label}')
+        if not COMPOSITION_LINE.search(text):
+            errors.append(f'{f}: composition guard must match the canonical no-nested-agent contract')
+        if not UNTRUSTED_LINE.search(text):
+            errors.append(f'{f}: untrusted-input guard must keep the complete canonical safety contract')
+        says_write=bool(WRITE_TERMS.search(text)) and not re.search(r'Do \*\*not\*\* edit|Do not edit|never edit|does not edit|does not write|Does not edit', text, re.I)
+        if name=='devrites-slice-wright':
+            if not re.search(r'write-capable|Writes code|write code', text, re.I):
+                errors.append(f'{f}: devrites-slice-wright must state write-capable mode')
+        else:
+            if says_write or not READONLY_TERMS.search(text):
+                errors.append(f'{f}: only devrites-slice-wright may be write-capable; reviewers must state read-only/findings-only mode')
+        if re.search(r'invoke (the )?(devrites-|another agent)|spawn (the )?(devrites-|another agent)', text, re.I) and not re.search(r'Do not invoke another agent|never invoke another agent|does not invoke another agent', text, re.I):
+            errors.append(f'{f}: agents must not say they may invoke another agent')
+    return errors
+
+def main():
+    p=argparse.ArgumentParser(); p.add_argument('--agents-dir', type=Path, default=ROOT/'pack/.claude/agents'); p.add_argument('--quiet', action='store_true'); args=p.parse_args()
+    errors=validate(args.agents_dir)
+    if errors:
+        for e in errors: print(f'FAIL: {e}')
+        print(f'validate-agent-composition: {len(errors)} failure(s)')
+        return 1
+    if not args.quiet: print('validate-agent-composition: PASS')
+    return 0
+if __name__=='__main__': sys.exit(main())

package/scripts/validate-command-parity.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Validate Claude/Codex command parity for public DevRites skills."""
+from __future__ import annotations
+import argparse, re, sys
+from pathlib import Path
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def fm(text):
+    if not text.startswith('---\n'): return {}
+    end = text.find('\n---', 4)
+    out = {}
+    if end == -1: return out
+    for line in text[4:end].splitlines():
+        if not line.strip() or ':' not in line or line.startswith((' ', '\t')): continue
+        k,v = line.split(':',1); out[k.strip()] = v.strip().strip('"\'')
+    return out
+
+
+def public_rites(skills_dir: Path):
+    names=[]
+    for f in sorted(skills_dir.glob('*/SKILL.md')):
+        meta=fm(f.read_text(encoding='utf-8'))
+        name=meta.get('name', f.parent.name)
+        if meta.get('user-invocable')=='true' and name.startswith('rite-') and name!='rite':
+            names.append(name)
+    return names
+
+
+def main():
+    p=argparse.ArgumentParser()
+    p.add_argument('--skills-dir', type=Path, default=ROOT/'pack/.claude/skills')
+    p.add_argument('--docs-skills', type=Path, default=ROOT/'docs/skills.md')
+    p.add_argument('--docs-command-map', type=Path, default=ROOT/'docs/command-map.md')
+    p.add_argument('--readme', type=Path, default=ROOT/'README.md')
+    p.add_argument('--router', type=Path, default=ROOT/'pack/.claude/skills/rite/SKILL.md')
+    p.add_argument('--generated-root', type=Path, default=ROOT/'pack/generated')
+    p.add_argument('--quiet', action='store_true')
+    args=p.parse_args()
+    errors=[]
+    skills=public_rites(args.skills_dir)
+    docs_skills=args.docs_skills.read_text(encoding='utf-8') if args.docs_skills.exists() else ''
+    docs_map=args.docs_command_map.read_text(encoding='utf-8') if args.docs_command_map.exists() else ''
+    readme=args.readme.read_text(encoding='utf-8') if args.readme.exists() else ''
+    router=args.router.read_text(encoding='utf-8') if args.router.exists() else ''
+    all_docs='\n'.join([docs_skills, docs_map, readme])
+    if 'npx devrites' not in all_docs:
+        errors.append('docs missing npx devrites distribution contract')
+    for line in all_docs.splitlines():
+        if re.search(r'\b(install|installed|installing)\s+via\s+.*\b(plugin|marketplace)\b', line, re.I) and 'not' not in line.lower():
+            errors.append('docs imply plugin distribution instead of npx install')
+            break
+    for name in skills:
+        verb=name.removeprefix('rite-')
+        needle=f'/rite-{verb}'
+        if needle not in router:
+            errors.append(f'router missing {needle} for {name}')
+        if needle not in docs_map:
+            errors.append(f'docs/command-map Claude direct: missing Claude command {needle} for {name}')
+        if args.generated_root.exists():
+            for rel in [f'claude/skills/{name}/SKILL.md', f'codex/skills/{name}/SKILL.md']:
+                if not (args.generated_root/rel).exists():
+                    errors.append(f'generated artifact missing {rel}')
+    if errors:
+        for e in errors: print(f'FAIL: {e}')
+        print(f'validate-command-parity: {len(errors)} failure(s)')
+        return 1
+    if not args.quiet: print('validate-command-parity: PASS')
+    return 0
+if __name__=='__main__': sys.exit(main())

package/scripts/validate-frontmatter.py

@@ -16,6 +16,12 @@ KNOWN_AGENT_FIELDS = {
     "mcpServers", "hooks", "maxTurns", "skills", "initialPrompt", "memory",
     "effort", "background", "isolation", "color",
 }
+DESCRIPTION_WORD_LIMITS = {
+    "public": 90,
+    "internal": 75,
+    "library": 60,
+    "explicit": 30,
+}
 
 
 def extract_frontmatter(text):
@@ -130,14 +136,44 @@ def main(argv):
             print("ERROR %s: description must be a single line (no newlines)" % path)
             errors += 1
             continue
-        if "when_to_use" in data:
-            dlen += len(str(data.get("when_to_use", "")))
-            if dlen > 1536:
-                warn += " [warn: description+when_to_use %d>1536 chars]" % dlen
+        desc_words = len(desc.strip().split())
+        explicit_only = str(data.get("disable-model-invocation", "")).lower() == "true"
+        if not is_agent(path):
+            if str(data.get("name", "")) == "devrites-lib":
+                budget = DESCRIPTION_WORD_LIMITS["library"]
+            elif explicit_only:
+                budget = DESCRIPTION_WORD_LIMITS["explicit"]
+            elif str(data.get("user-invocable", "")) == "true":
+                budget = DESCRIPTION_WORD_LIMITS["public"]
+            else:
+                budget = DESCRIPTION_WORD_LIMITS["internal"]
+            if desc_words > budget:
+                print("ERROR %s: description %d words > %d budget (keep triggers tight; move workflow into the body)"
+                      % (path, desc_words, budget))
+                errors += 1
+                continue
+            failed = False
+            for phrase in ("Use when", "Not for"):
+                count = desc.count(phrase)
+                if count > 1:
+                    print("ERROR %s: description repeats %r %d times (collapse duplicate trigger branches)"
+                          % (path, phrase, count))
+                    errors += 1
+                    failed = True
+                    break
+            if failed:
+                continue
+            if explicit_only and str(data.get("name", "")) != "devrites-lib":
+                for phrase in ("Use when", "Not for"):
+                    if phrase in desc:
+                        print("ERROR %s: explicit-only description contains %r; keep it a human summary" % (path, phrase))
+                        errors += 1
+                        failed = True
+                        break
+                if failed:
+                    continue
         ui = data.get("user-invocable", "(default)")
-        ctx = data.get("context", "")
-        flag = (" context=%s" % ctx) if ctx else ""
-        print("OK    %s  (user-invocable=%s%s)%s" % (path, ui, flag, warn))
+        print("OK    %s  (user-invocable=%s)%s" % (path, ui, warn))
     if errors:
         print("\n%d file(s) failed frontmatter validation." % errors)
         return 1

package/scripts/validate-skill-anatomy.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Validate DevRites-native skill anatomy contracts."""
+from __future__ import annotations
+import argparse, re, sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = ROOT / "pack" / ".claude" / "skills"
+
+PUBLIC_REQUIRED = {
+    "operating contract": [r"## Operating rules", r"## Rules", r"## Contract", r"## Core operating rules", r"## Two modes", r"## Safety", r"## Mode", r"## Protocol"],
+    "rules consulted / standards read": [r"## Rules consulted", r"governing rules", r"standards/core\.md", r"devrites-lib/reference/standards"],
+    "workflow or phase-contract pointer": [r"## Workflow", r"phase-contract\.md", r"## Steps", r"## Protocol", r"## Flow", r"## Run", r"## Menu", r"## Process", r"## Modes"],
+    "output/reply contract": [r"## Output", r"## What to output", r"reply-contract\.md", r"Default success shape", r"Completion"],
+    "phase boundary / stop condition": [r"stop", r"Stop when", r"Done when", r"NO-GO", r"GO", r"one slice"],
+}
+INTERNAL_REQUIRED = {
+    "trigger boundary": [r"Use when", r"## Trigger", r"## When to use", r"## Boundaries", r"Triggered by"],
+    "hard rules": [r"## Hard rules", r"## Rules", r"## NEVER", r"## Operating rules", r"## Boundaries", r"Do not", r"Never", r"Must", r"Scope"],
+    "output contract": [r"## Output", r"## Return", r"Output format", r"Default success shape", r"Visual Verdict", r"writes? `", r"writes? ", r"Return"],
+    "when not to use": [r"Not for", r"## When NOT to use", r"## Boundaries", r"Do not", r"Never"],
+}
+GOTCHA_PATTERNS = [r"## Gotchas", r"reference/anti-patterns\.md", r"Mid-flight discipline", r"## Hard rules", r"## NEVER", r"## Boundaries", r"## Rules", r"## Scope reminders", r"## When NOT to use", r"## What NOT to include", r"Anti-AI-slop", r"Do not", r"Never"]
+EXEMPT = {"devrites-lib"}
+# Legacy exceptions waive only the named missing section. They are owned and
+# time-bounded so a compact skill cannot silently bypass unrelated contracts.
+def exemption(owner: str, reason: str) -> dict[str, str]:
+    return {"owner": owner, "reason": reason, "expires": "2026-10-01"}
+
+
+SECTION_EXEMPTIONS = {
+    "devrites-api-interface": {
+        "hard rules": exemption("guidance", "compact specialist encodes rules in prose"),
+        "output contract": exemption("guidance", "output is owned by the caller contract"),
+        "gotchas/anti-patterns pointer": exemption("guidance", "compact specialist has no standalone reference payload"),
+    },
+    "devrites-frontend-craft": {"output contract": exemption("guidance", "reference-driven craft output")},
+    "rite-doctor": {
+        "operating contract": exemption("guidance", "read-only diagnostic utility"),
+        "rules consulted / standards read": exemption("guidance", "engine owns the diagnostic checks"),
+    },
+    "rite-frame": {
+        "rules consulted / standards read": exemption("guidance", "ad-hoc lens utility"),
+        "workflow or phase-contract pointer": exemption("guidance", "FRAME/AUDIT flow is encoded in prose"),
+    },
+    "rite-handoff": {
+        "operating contract": exemption("guidance", "single-purpose artifact writer"),
+        "workflow or phase-contract pointer": exemption("guidance", "handoff artifact is the workflow")},
+    "rite-polish": {"workflow or phase-contract pointer": exemption("guidance", "workflow is split across code and UI references")},
+    "rite-pressure-test": {
+        "operating contract": exemption("guidance", "compact ideation utility"),
+        "workflow or phase-contract pointer": exemption("guidance", "pressure-test loop is encoded in prose")},
+    "rite-prototype": {
+        "operating contract": exemption("guidance", "throwaway prototype lifecycle"),
+        "workflow or phase-contract pointer": exemption("guidance", "prototype loop is encoded in prose"),
+        "phase boundary / stop condition": exemption("guidance", "prototype is intentionally disposable"),
+        "gotchas/anti-patterns pointer": exemption("guidance", "prototype warning is encoded in prose")},
+    "rite-status": {
+        "operating contract": exemption("guidance", "read-only engine status utility"),
+        "workflow or phase-contract pointer": exemption("guidance", "engine progress command owns flow")},
+    "rite-zoom-out": {
+        "operating contract": exemption("guidance", "read-only mapping utility"),
+        "workflow or phase-contract pointer": exemption("guidance", "structural map is the workflow")},
+}
+
+
+def parse_frontmatter(text: str) -> dict[str, str]:
+    if not text.startswith("---\n"): return {}
+    end = text.find("\n---", 4)
+    fields = {}
+    if end == -1: return fields
+    for line in text[4:end].splitlines():
+        if not line.strip() or line.startswith((" ", "\t", "#")) or ":" not in line: continue
+        k,v = line.split(":",1)
+        fields[k.strip()] = v.strip().strip('"\'')
+    return fields
+
+
+def has_any(text: str, patterns: list[str]) -> bool:
+    return any(re.search(p, text, re.I | re.M) for p in patterns)
+
+
+def validate(skills_dir: Path) -> list[str]:
+    errors = []
+    for f in sorted(skills_dir.glob("*/SKILL.md")):
+        text = f.read_text(encoding="utf-8")
+        fm = parse_frontmatter(text)
+        name = fm.get("name", f.parent.name)
+        if name in EXEMPT:
+            continue
+        exemptions = SECTION_EXEMPTIONS.get(name, {})
+        invocable = fm.get("user-invocable") == "true"
+        rules = PUBLIC_REQUIRED if invocable else INTERNAL_REQUIRED
+        for label, patterns in rules.items():
+            if not has_any(text, patterns) and label not in exemptions:
+                errors.append(f"{f}: missing {label}")
+        if not has_any(text, GOTCHA_PATTERNS) and "gotchas/anti-patterns pointer" not in exemptions:
+            errors.append(f"{f}: missing gotchas/anti-patterns pointer")
+        for label, record in exemptions.items():
+            if not record.get("owner") or not record.get("reason") or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", record.get("expires", "")):
+                errors.append(f"{f}: anatomy exemption {label!r} requires owner, reason, and YYYY-MM-DD expires")
+            elif record["expires"] < date.today().isoformat():
+                errors.append(f"{f}: anatomy exemption {label!r} expired {record['expires']}")
+        desc = fm.get("description", "")
+        explicit_only = fm.get("disable-model-invocation") == "true"
+        if not explicit_only and not re.search(r"\bUse when\b|\bUse to\b|\bTrigger|\bwhen\b|\bfor ", desc, re.I):
+            errors.append(f"{f}: model-invoked description must include trigger language")
+        # Cross-skill references: obvious backtick references should exist.
+        for ref in re.findall(r"`((?:rite|devrites)-[a-z0-9-]+)`", text):
+            if ref in {"rite-use", "devrites-source-cache"}:
+                continue
+            if not (skills_dir / ref / "SKILL.md").exists() and not (ROOT / "pack" / ".claude" / "agents" / f"{ref}.md").exists():
+                errors.append(f"{f}: unknown cross-skill/agent reference `{ref}`")
+    afk_contract = skills_dir / "devrites-lib" / "reference" / "standards" / "afk-hitl.md"
+    if afk_contract.exists():
+        afk_text = afk_contract.read_text(encoding="utf-8")
+        if "allow_irreversible" in afk_text:
+            errors.append(f"{afk_contract}: irreversible-risk gates must not have an unattended bypass")
+        if "## Irreversible-risk list (always pause)" not in afk_text:
+            errors.append(f"{afk_contract}: missing irreversible-risk always-pause contract")
+    return errors
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--skills-dir", type=Path, default=SKILLS_DIR)
+    p.add_argument("--quiet", action="store_true")
+    args = p.parse_args()
+    errors = validate(args.skills_dir)
+    if errors:
+        for e in errors: print(f"FAIL: {e}")
+        print(f"validate-skill-anatomy: {len(errors)} failure(s)")
+        return 1
+    if not args.quiet:
+        print("validate-skill-anatomy: PASS")
+    return 0
+
+if __name__ == "__main__": sys.exit(main())

package/scripts/validate-workflow-security.py

@@ -9,7 +9,8 @@ gate fails CI when a workflow:
     `actions/*` and `github/*` tags are tolerated);
   - declares no `permissions:` scope anywhere — the default token is broad;
   - uses `permissions: write-all` (over-broad);
-  - uses `pull_request_target` (runs with secrets on untrusted PR code — review required).
+  - uses `pull_request_target`, except for a Dependabot-only workflow that never
+    checks out PR code.
 
 Usage: validate-workflow-security.py [DIR]   (default: .github/workflows)
 Exit: 0 clean; 1 on any finding.
@@ -21,11 +22,28 @@ import sys
 FIRST_PARTY = {"actions", "github"}   # GitHub-owned; major-tag refs tolerated
 SHA_RE = re.compile(r"^[0-9a-f]{40}$")
 USES_RE = re.compile(r"^\s*-?\s*uses:\s*([^\s#]+)")
+DEPENDABOT_ONLY_RE = re.compile(
+    r"^\s*if:\s*(?:\$\{\{\s*)?"
+    r"(?:github\.actor|github\.event\.pull_request\.user\.login)\s*==\s*"
+    r"['\"]dependabot\[bot\]['\"]",
+    re.MULTILINE,
+)
+
+
+def safe_dependabot_target(text):
+    if re.search(r"^\s*-?\s*uses:\s*actions/checkout@", text, re.MULTILINE):
+        return False
+    jobs = text.split("\njobs:", 1)
+    if len(jobs) != 2:
+        return False
+    blocks = re.split(r"(?m)^  [A-Za-z0-9_-]+:\s*(?:#.*)?$", jobs[1])[1:]
+    return bool(blocks) and all(DEPENDABOT_ONLY_RE.search(block) for block in blocks)
 
 
 def scan_text(path, text):
     findings = []
     lines = text.splitlines()
+    dependabot_target_is_safe = safe_dependabot_target(text)
     if not re.search(r"^\s*permissions:", text, re.MULTILINE):
         findings.append("%s: no permissions: scope — the default GITHUB_TOKEN is broad; "
                         "add an explicit least-privilege permissions block" % path)
@@ -33,9 +51,10 @@ def scan_text(path, text):
         if "write-all" in line:
             findings.append("%s:%d: permissions: write-all is over-broad — scope to the "
                             "minimum needed" % (path, i))
-        if "pull_request_target" in line:
+        if "pull_request_target" in line and not dependabot_target_is_safe:
             findings.append("%s:%d: pull_request_target runs with secrets on untrusted PR "
-                            "code — review carefully or use pull_request" % (path, i))
+                            "code — only a Dependabot-only workflow without checkout is allowed"
+                            % (path, i))
         m = USES_RE.match(line)
         if not m:
             continue