martin1847/evolab / skills/repo-governance-bootstrap
repo-governance-bootstrap
Verified一次性初始化 AI 协作项目的轻量工程治理骨架。新仓库 / 文档治理初始化时调用(也是 cto-orchestration 接入新项目的第一步)。One-shot governance bootstrap for a new repo.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.9 KB |
| hooks.json | config | 592 B |
| references/PROJECT_AGENT.md | markdown | 7.9 KB |
| references/PR_SELF_CHECK.skeleton.md | markdown | 826 B |
| references/docs-check.shexecutable | script | 7.4 KB |
| references/engineering-gate.conf.example | other | 361 B |
| references/engineering-gate.shexecutable | script | 6.8 KB |
| references/hook-wiring.md | markdown | 2.4 KB |
| references/memory-discipline-hook.pyexecutable | script | 2.7 KB |
| references/memory-discipline-hook.ts | script | 1.5 KB |
| references/pre-commit.shexecutable | script | 1.4 KB |
| references/pre-push.template | other | 3.5 KB |
| references/templates.md | markdown | 14.4 KB |
references/docs-check.sh
View on GitHub#!/usr/bin/env bash
# docs-check — mechanical anti-rot gate for the governance skeleton (bootstrap step 12).
#
# Rot is a workflow problem: nothing verifies docs against code unless a gate does.
# Four checks, each backed by a documented failure mode:
# 1. size — AGENTS.md/CLAUDE.md over budget (>200 lines WARN; combined >32KiB FAIL:
# Codex silently truncates merged instruction files at 32KiB).
# 2. links — relative .md links in docs/ + AGENTS.md must resolve (FAIL on broken).
# 3. fresh — ACTIVE_CONTEXT.md "Last rewritten:" older than $DOCS_FRESH_DAYS (default 14)
# or over ~80 lines → WARN (snapshot is the fastest-rotting doc in the repo).
# 4. paths — backticked repo paths (`a/b.ext`) in AGENTS.md + docs/*.md that no longer
# exist → WARN (study: 23% of repos carry context files referencing deleted
# code elements; conservative pattern, placeholders/globs/URLs skipped).
# heal — `--heal` (opt-in, never in check mode) rewrites a dead backticked path whose
# basename is unique under docs/ and whose directory segments the candidate covers;
# every other pointer is skipped with a reason code. Explicit, mechanical, no guesses.
#
# Usage: bash docs-check.sh [repo-root] [--heal] (default: cwd) — wire into pre-commit or CI.
# Exit 1 on any FAIL; WARNs never block.
set -eu
HEAL=0
ROOT=.
for a in "$@"; do
case "$a" in --heal) HEAL=1 ;; *) ROOT="$a" ;; esac
done
python3 - "$ROOT" "$HEAL" <<'PY'
import os, re, sys, time
root = sys.argv[1]
heal = sys.argv[2] == "1"
fails, warns = 0, 0
def fail(m): # blocking
global fails; fails += 1; print(f" ✗ FAIL {m}")
def warn(m): # advisory
global warns; warns += 1; print(f" ⚠ WARN {m}")
def p(*a): return os.path.join(root, *a)
# 1. size gate
combined = 0
for f in ("AGENTS.md", "CLAUDE.md"):
fp = p(f)
if not os.path.isfile(fp):
continue
data = open(fp, encoding="utf-8", errors="replace").read()
combined += len(data.encode())
n = data.count("\n") + 1
if n > 200:
warn(f"{f}: {n} lines (>200 — adherence drops as instruction files bloat)")
if combined > 32 * 1024:
fail(f"AGENTS.md+CLAUDE.md combined {combined} bytes (>32KiB — Codex silently truncates)")
# collect markdown files in scope
mds = []
for base in (p("docs"),):
for dirpath, dirnames, filenames in os.walk(base):
dirnames[:] = [d for d in dirnames if d not in ("archive", "node_modules", ".git")]
mds += [os.path.join(dirpath, fn) for fn in filenames if fn.endswith(".md")]
for f in ("AGENTS.md",):
if os.path.isfile(p(f)):
mds.append(p(f))
# 2. relative link gate
for md in mds:
body = open(md, encoding="utf-8", errors="replace").read()
for target in re.findall(r"\]\(([^)#\s]+?\.md)(?:#[^)]*)?\)", body):
if target.startswith(("http://", "https://", "mailto:")) or "<" in target:
continue
resolved = os.path.normpath(os.path.join(os.path.dirname(md), target))
if not os.path.exists(resolved):
fail(f"{os.path.relpath(md, root)}: broken link -> {target}")
# 3. ACTIVE_CONTEXT freshness
ac = p("docs", "ACTIVE_CONTEXT.md")
if os.path.isfile(ac):
body = open(ac, encoding="utf-8", errors="replace").read()
n = body.count("\n") + 1
if n > 80:
warn(f"ACTIVE_CONTEXT.md: {n} lines (snapshot contract is ~60 — journal creep?)")
m = re.search(r"Last rewritten:\s*(\d{4})-(\d{2})-(\d{2})", body)
if not m:
warn("ACTIVE_CONTEXT.md: no 'Last rewritten: YYYY-MM-DD' header (freshness unknowable)")
else:
age = (time.time() - time.mktime(time.strptime("-".join(m.groups()), "%Y-%m-%d"))) / 86400
limit = int(os.environ.get("DOCS_FRESH_DAYS", "14"))
if age > limit:
warn(f"ACTIVE_CONTEXT.md: last rewritten {age:.0f}d ago (>{limit}d — stale snapshot misleads every new session)")
# 4. phantom path references (conservative: real-looking repo paths only)
PATH_RE = re.compile(r"`([A-Za-z0-9_.\-]+(?:/[A-Za-z0-9_.\-]+)+\.[A-Za-z0-9]{1,8})`")
for md in mds:
body = open(md, encoding="utf-8", errors="replace").read()
for ref in set(PATH_RE.findall(body)):
if any(c in ref for c in "*<>{}$") or ref.startswith(("http", "~")):
continue
if not os.path.exists(p(ref)) and not os.path.exists(os.path.join(os.path.dirname(md), ref)):
warn(f"{os.path.relpath(md, root)}: references `{ref}` which does not exist (phantom path)")
# 5. heal pass — opt-in rewrite of the mechanically unambiguous subset of check 4's phantoms
def segs(pth): return [s for s in pth.split("/") if s and s != "."]
def phantom(ref, md):
return not os.path.exists(p(ref)) and not os.path.exists(os.path.join(os.path.dirname(md), ref))
def live_refs(line):
return [m for m in PATH_RE.finditer(line)
if not (any(c in m.group(1) for c in "*<>{}$") or m.group(1).startswith(("http", "~")))]
SAFE_RE = re.compile(r"[A-Za-z0-9_./-]+\Z")
def heal_target(ref, md, index):
"""(successor ref or None, reason). Healed only when one docs/ file carries the dead ref's
basename and its directory segments cover the ref's — anything else is a guess, so it skips."""
cands = index.get(os.path.basename(ref), [])
if len(cands) != 1:
return None, "ambiguous" if cands else "gone"
cand_segs = segs(os.path.dirname(cands[0]))
ref_segs = [s for s in segs(os.path.dirname(ref)) if s != ".."]
for s in (cand_segs, ref_segs):
if s[:1] == ["docs"]:
del s[0]
if not set(ref_segs) <= set(cand_segs):
return None, "dir-mismatch"
# write the successor in the reading the dead ref used, so check 4 re-resolves it next run
new = os.path.relpath(p(cands[0]), root if ref.startswith("docs/") else os.path.dirname(md))
if not SAFE_RE.match(new):
return None, "unsafe-target"
return new, "ok"
if heal and not os.path.exists(p(".git")):
print(" skip: heal (not-a-git-repo — a rewrite would have no rollback)")
heal = False
if heal:
index = {}
for dirpath, dirnames, filenames in os.walk(p("docs")):
dirnames[:] = [d for d in dirnames if d not in ("archive", "node_modules", ".git")]
for fn in filenames:
fp = os.path.join(dirpath, fn)
if not os.path.islink(fp):
index.setdefault(fn, []).append(os.path.relpath(fp, root))
for md in mds:
rel = os.path.relpath(md, root)
if os.path.islink(md):
print(f" skip: {rel} (symlink)")
continue
lines = open(md, encoding="utf-8", newline="").readlines()
healed = False
for i, line in enumerate(lines, 1):
refs = live_refs(line)
dead = [m for m in refs if phantom(m.group(1), md)]
if not dead:
continue
ref = dead[0].group(1)
if len(refs) > 1:
print(f" skip: {rel}:{i} {ref} (multi-ref)")
continue
new, why = heal_target(ref, md, index)
if new is None:
print(f" skip: {rel}:{i} {ref} ({why})")
continue
lines[i - 1] = line[:dead[0].start(1)] + new + line[dead[0].end(1):]
healed = True
print(f" heal: {rel}:{i} {ref} -> {new}")
if healed:
open(md, "w", encoding="utf-8", newline="").writelines(lines)
print()
if fails:
print(f"docs-check: {fails} FAIL, {warns} WARN — FAIL"); sys.exit(1)
print(f"docs-check: clean ✓ ({warns} WARN)")
PY
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |