repo-align

name	repo-align
description	This skill should be used when the user says "repo-align", "align the repo", "clean up the repo", "check for drift", "is the repo in good shape", "find contradictions", "what's gotten messy", "doc cleanup", "are my docs consistent", "tidy up the docs", or when startup's trust report went red. The deep, opt-in alignment pass: mechanical scans (drift, freshness, structure drift, vocabulary, size budgets) plus judgment passes — a doc router that reads off-shelf files and proposes where their content belongs, a routes-vs-api.md and modules-vs-module-map diff, and an on-request rules audit of AGENTS.md. Proposes before acting on every judgment call; preserves history with git mv; never silently merges, deletes, or archives.
argument-hint	[--report-only] [--rules-audit]
user-invocable	true
allowed-tools	Read Glob Grep Bash Write Edit AskUserQuestion

Repo Align — bring the repo back to the shelf

The deep, opt-in pass — run it every ~25 commits or when the trust report goes red. Find documentation drift, surface it in plain English, and propose one disposition per judgment call — always confirmed before acting. Never silently merge, delete, archive, or rewrite.

The model you're aligning to is <plugin-root>/references/shelf-spec.md — the context stack (L0 AGENTS.md ≤40 lines, L1 docs/handoff.md ≤60 lines), the closed shelf of docs under docs/, active initiatives, vocabulary profiles, the one-writer table, and domain authority. Read it before judging.

With --report-only, do steps 1–3 (find and present) and stop — propose no changes.

1. Run the mechanical scans

Pure-stdlib, advisory. Capture each JSON; they surface candidates, not verdicts. Your judgment decides which are real. (Use python3, or python on Windows.)

PLUGIN_ROOT=$( [ -d "./plugins/rad-repo-manager" ] && echo "./plugins/rad-repo-manager" || echo "${CLAUDE_PLUGIN_ROOT:-$HOME/.gemini/config/plugins/rad-repo-manager}" )
python3 "$PLUGIN_ROOT/scripts/repo-scan.py" . --json --no-record      # floating docs, inbox, L0/L1 size budgets, align cadence
python3 "$PLUGIN_ROOT/scripts/doc-freshness.py" . --json              # trust report, stale docs, structure/route-weighted staleness
python3 "$PLUGIN_ROOT/scripts/structure-drift.py" . --json            # routes vs api.md · modules vs architecture.md's module map
python3 "$PLUGIN_ROOT/scripts/vocab-lint.py" . --json                 # profile-driven synonyms, wrong-doc ladder terms
python3 "$PLUGIN_ROOT/scripts/doc-contradiction.py" . --json          # prd non-goals + locked constraints vs plan
python3 "$PLUGIN_ROOT/scripts/doc-redundancy.py" . --json             # same fact in two docs
python3 "$PLUGIN_ROOT/scripts/audit-user-content.py" . --json         # orphan terms, dead paths in AGENTS.md

(If Python 3 is unavailable, do the same checks by reading the docs directly and say the mechanical pass was skipped.)

Size budgets: the repo-scan JSON flags l0_over_budget (root AGENTS.md > 40 lines) and l1_over_budget (handoff > 60 lines). L0 overflow is a rules-audit trigger (step 2d); L1 overflow means durable content leaked into the handoff — route it to plan.md/prd.md/lessons.md in step 4.

2. The judgment passes

2a. Doc router — read what's off the shelf, route its content

For every file the scan flagged as floating (created since the last pass, not on the shelf): read it — don't just report the filename. Classify what's inside and propose a routing per finding, e.g. "this file is three settled decisions and one idea — append them to docs/decisions.md / docs/ideas.md, then archive the file?" Transient brainstorm specs (docs/*-spec.md / *-design.md) whose plan already exists get proposed for docs/archive/. An approved finite migration may instead be routed to docs/initiatives/<slug>.md from templates/initiative.md; require all lifecycle metadata and a link from docs/plan.md. A domain reference doc with no shelf slot is a satellite, not a loose end — propose a link from the nearest core doc if it's unlinked, and leave it in place (shelf-spec "Satellite docs" / "Conformance without loss"). Propose, never silently act.

2b. Vocabulary lint

Read the vocab-lint findings. Advisory synonym hits invite a proposed reword; strict profile hits must be resolved before the check is green. Judge each candidate — "staging environment" is not a tracked unit — and preview every drafting edit. Ladder terms in the wrong doc still need routing. Content-level plan problems get flagged to /rad-planner:replan, not fixed here (format is this plugin's lane; plan substance is the planner's).

2c. Structure drift — api.md routes and architecture.md's module map

structure-drift.py (step 1) already did the mechanical diff; this pass judges its candidates and drafts the doc edits.

• api.md (when it exists): routes in code but not the doc → propose the missing lines; routes in the doc but not the code → propose removal. If the script found no route patterns for this codebase, fall back to a manual grep — Express/Fastify app.get|post|...(, Next.js app/**/route.ts / pages/api/**, Flask/FastAPI decorators, Rails routes.rb — and say the diff was inconclusive rather than guessing.
• architecture.md (when it exists): source modules absent from the ## Module map → propose rows (name · what it owns · entry point · LOCKED flag where a decision record pins a boundary); map rows whose module is gone → propose removal. If architecture.md has no ## Module map section yet, draft one from the actual source tree (this is the one place a map gets bolted onto a legacy architecture.md) and propose it as a single addition, per the shelf-spec format.

2d. Rules audit — on request (--rules-audit) or when L0 is over budget

For each rule in AGENTS.md, classify by evidence (git history, lessons.md, what you can observe in the repo — say when evidence is thin):

• Promote to hook — violated in practice AND mechanically checkable.
• Keep — violated in practice, needs judgment; it earns one of the ≤7 hard-rule slots.
• Demote — dormant (no sign it's been needed in months) → move to a referenced guardrails file (docs/archive/ or a linked doc), leaving L0 lean.

Present the classification with one line of reasoning per rule. Propose-only — the owner decides every move; this is how a beloved-but-bloated AGENTS.md gets condensed without losing the guardrails the owner values.

2e. The classic drift checks

Read the shelf docs that exist plus CLAUDE.md, README.md, docs/archive/ names (not contents). Identify: duplicate authorities, stale docs, pointer chains, missing docs whose triggers have clearly fired, contradictory read paths, off-model status/roadmap docs, scoped AGENTS.md files without materially different subtree rules, scoped overlays missing a one-line CLAUDE.md shim, duplicate root facts in scoped files, and root-README content that has become stale status.

Resolve contradictions by domain authority (shelf-spec): applicable root/scoped instructions and locked ADRs govern constraints; prd.md governs product intent; code plus architecture.md/api.md govern current state; plan.md and active initiatives govern approved future change; design.md governs visual direction; handoff is only a session snapshot. A plan never overrides a locked ADR. Propose the edit to the incorrect domain document (step 5). If authorities in the same domain disagree, or the owner has not made the product decision, STOP and surface it under "Needs a decision." Never silently merge two conflicting decisions.

Check the role boundaries — each doc holds only its own kind of content: execution detail in the PRD → plan.md; permanent product rules in the plan → prd.md; durable facts in the handoff → plan/prd/lessons; product summaries or roadmap in AGENTS.md → replace with a pointer. Settled decisions stranded in a brainstorm, the handoff, or AGENTS.md → propose appending to docs/decisions.md (visual/design decisions → docs/design.md).

Terminology / superseded sweep. If AGENTS.md has a ## Retired terminology table, grep the managed docs for each retired term and flag stray uses (suggest the replacement). Regardless, flag any doc that calls something "current" when newer evidence in the same domain has overtaken it, and any superseded content lacking a superseded banner.

3. Present findings — plain language, grouped

# Repo alignment

## Needs a decision
- The plan builds offline mode, but the PRD lists offline as a non-goal. Which wins?

## Doc router
- `docs/2026-06-28-notes.md` — contains two settled decisions and an idea: append to decisions.md/ideas.md, archive the file?

## Vocabulary
- `docs/prd.md:14` says "sprint 2" — the ladder term is Milestone (M2), and it belongs in plan.md, not the PRD.

## Size budgets
- `AGENTS.md` is 57 lines (budget 40) — rules audit below proposes what to demote.

## Structure drift
- `POST /api/upload` exists in code but not in docs/api.md.
- `src/stores/` has no row in architecture.md's module map.

## Conflicts / redundancy / role-boundary leaks
- `docs/prd.md` and `AGENTS.md` both define the validation steps — pick one home.

## Rules audit (when run)
- "Never push without tests" — violated twice, mechanically checkable → promote to a hook.

## Loose / misplaced docs · pointer problems · missing docs
- `smoke-2026-05-30.md` (repo root) — a smoke-test report sitting loose.

## Suggested actions
[per-item dispositions below]

No jargon, no validator names in the user-facing report — describe the problem and the fix in words a non-coder follows.

4. Offer fixes — closed disposition set, confirmed per item

For each finding, propose ONE disposition and ask before acting (via AskUserQuestion, ask_question on Antigravity, or a clear yes/no per item):

1. Route — append the content to its shelf home (decisions/ideas/lessons/design), then archive the original.
2. Fold — merge durable content into the owning shelf doc, then archive the original.
3. Archive — historical / done → git mv into docs/archive/, add the archive banner.
4. Relocate — a misplaced doc → move to its shelf home.
5. Banner — content overtaken but staying in place → add a superseded banner pointing at the current authority.
6. Reword — a vocabulary or budget fix inside a doc this plugin may edit.

Rules:

• Propose, never auto-act. Every route/fold/move/delete waits for the user's yes.
• Preserve history: move tracked files with git mv, never delete-and-recreate.
• Append-only files stay append-only — route content by appending new entries, never by editing existing decisions/ideas/lessons lines.
• Keep CLAUDE.md/GEMINI.md as thin @AGENTS.md pointers — if one has grown its own content, propose folding it into AGENTS.md and restoring the shim.
• After approved moves, confirm the L0/L1 read path still points at reality.

5. Durable changes — draft the edit, apply only on explicit confirmation

When a finding implies a change to a doc the manager doesn't write — docs/prd.md, docs/design.md, or docs/plan.md content — the user owns the decision, not the typing. Draft the exact edit (old → new) and ask per doc via AskUserQuestion: apply / skip / let me reword. Apply only on an explicit "apply" for that specific edit; a skip means hands off, restated in one line at the end. Never bundle user-owned edits into a blanket OK. Structural plan problems go to /rad-planner:replan, not to an edit here.

6. Stamp the run — align cadence tracking

At the end of the pass (including --report-only runs — the repo was inspected either way), record it:

python3 "$PLUGIN_ROOT/scripts/repo-scan.py" . --record-align --json >/dev/null

This stamps the current HEAD into .rad/repo-manager-state.json; startup, ship, and the SessionStart hook read it to report "last align was N commits ago" against the ~25-commit cadence. Skip silently if Python is unavailable.

What this skill does NOT do

• Does not auto-apply judgment calls — every move/merge/archive/reword is user-confirmed.
• Does not write docs/prd.md/docs/design.md without an explicit per-edit "apply".
• Does not edit existing entries in append-only docs.
• Does not create docs/status.md, docs/roadmap.md, docs/implementation-plan.md, loose root status docs, speculative scoped instructions, or scoped AGENTS.md files without matching one-line CLAUDE.md shims.
• Does not run on every session — it's the opt-in deep pass (/ship runs only the mechanical scans, none of the judgment passes).

References

• <plugin-root>/references/shelf-spec.md — shelf, profiles, budgets, initiatives, one-writer table, domain authority
• <plugin-root>/scripts/ — drift scans, repository contract discovery, and pre-ship gate