@tyroneross/build-loop 0.36.0 → 0.43.0

package/skills/plugin-builder/references/distribution.md

@@ -198,7 +198,15 @@ Trusted Publisher settings before the real publish:
 - Workflow filename exactly matches the publish workflow, for example
   `publish-npm.yml`.
 - Environment is blank unless the workflow uses a GitHub environment.
-- Allowed actions include `npm publish`.
+- Allowed actions include `npm publish` (stage-only records reject a direct publish).
+- The record EXISTS. `npmjs.com → package → Settings → Trusted publishing` is per
+  package and only the web UI (with 2FA) can create it. If the OIDC exchange answers
+  `"OIDC token exchange error - package not found"`, there is no record; no workflow
+  edit will help. See `../../../references/npm-package-publishing.md`
+  §"Diagnosing a trusted-publishing failure" for the exchange probe and the answer table.
+- `package.json#repository.url` exactly matches the GitHub repository.
+- The package already exists on npmjs; trusted publishing cannot create one, so the
+  first version of a new package needs a one-time human login.
 
 The workflow should use a GitHub-hosted runner, `permissions: id-token: write`,
 `actions/checkout`, and `actions/setup-node` with `registry-url` set to the
@@ -209,7 +217,10 @@ cache detection is noisy.
 
 Run `npm publish --dry-run --provenance --access public --registry=https://registry.npmjs.org`
 as a packaging check, but do not treat it as proof that the Trusted Publisher
-mapping is valid. A real publish can still fail after a successful dry-run when
+mapping is valid. Nor is the `Signed provenance statement` line at publish time:
+with `publishConfig.provenance: true` npm signs before it knows whether the OIDC
+exchange succeeded. A later `E404 Not Found - PUT` is an unauthenticated write masked by
+setup-node's placeholder `NODE_AUTH_TOKEN`, not a missing package. A real publish can still fail after a successful dry-run when
 the npm package settings do not match the GitHub workflow. After publishing,
 verify the registry metadata includes
 `dist.attestations.provenance.predicateType = https://slsa.dev/provenance/v1`.

package/skills/plugin-builder/references/plugin-hygiene-lessons.md

@@ -48,13 +48,13 @@ Better: use `EnterWorktree` or a separate test project directory for plugin deve
 
 **What happened.** Editing hook files under `~/.claude/plugins/cache/rosslabs-ai-toolkit/showcase/0.1.1/hooks/hooks.json` took effect immediately, but the next marketplace sync (pulling the GitHub repo) overwrote the edit with the repo's original file. Hours of debugging lost to the illusion of a persistent fix.
 
-**Rule.** Cache is regenerated from the marketplace's upstream repo. Always edit the source (`~/Desktop/git-folder/RossLabs-AI-Toolkit/plugins/<plugin>/…`), commit, push. If you need an immediate fix in the current session, edit both the source and the cache — the cache copy keeps the session alive until you push, then the next sync reconciles.
+**Rule.** Cache is regenerated from the marketplace's upstream repo. Always edit the source (your local checkout of the marketplace repo, e.g. `<your-checkouts-root>/RossLabs-AI-Toolkit/plugins/<plugin>/…`), commit, push. If you need an immediate fix in the current session, edit both the source and the cache — the cache copy keeps the session alive until you push, then the next sync reconciles.
 
 The marketplace repo is the source of truth. Nothing under `~/.claude/plugins/cache/` is authored — it's all generated.
 
 ## 5a. The reverse trap: source-only edits don't take effect at runtime
 
-**What happened (2026-04-22, build-loop).** Edited `~/Desktop/git-folder/build-loop/scripts/write_run_entry.py` in the source repo and updated the orchestrator prose to invoke `${CLAUDE_PLUGIN_ROOT}/scripts/write_run_entry.py`. Tests passed. Claimed success. The orchestrator never saw the new script because `${CLAUDE_PLUGIN_ROOT}` resolves to `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` — a frozen snapshot that only updates on marketplace sync. Source-only edit = runtime silently runs the old version (or in this case, returns "file not found" and the orchestrator falls back to hand-writing JSON, if it remembers to).
+**What happened (2026-04-22, build-loop).** Edited `<local checkout>/build-loop/scripts/write_run_entry.py` in the source repo and updated the orchestrator prose to invoke `${CLAUDE_PLUGIN_ROOT}/scripts/write_run_entry.py`. Tests passed. Claimed success. The orchestrator never saw the new script because `${CLAUDE_PLUGIN_ROOT}` resolves to `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` — a frozen snapshot that only updates on marketplace sync. Source-only edit = runtime silently runs the old version (or in this case, returns "file not found" and the orchestrator falls back to hand-writing JSON, if it remembers to).
 
 **Rule.** The full sync cycle is **source → commit → push → marketplace sync → cache**. Any link that breaks leaves the cache stale.
 

package/skills/plugin-tests/SKILL.md

@@ -77,7 +77,7 @@ Don't migrate to pytest, vitest, or Playwright. The stdlib pattern keeps the har
 ## What this skill does NOT do
 
 - Runtime testing (live MCP calls, actual `Skill()` invocation) — that's Review-B Validate's job, executed by the orchestrator with the live runtime
-- UI testing — for plugins that build UIs, use the orchestrator's build-loop-owned UI validation route (`ui-validator`, project-native tests, screenshots/static scanner). Dispatch IBR only when the user explicitly asks for IBR / Interface Built Right / `.ibr-test.json`.
+- UI testing — for plugins that update, compare, or audit renderable UI designs, follow `../../references/ibr-ui-verification-policy.md`: IBR is primary when installed, with `ui-validator`, project-native tests, screenshots, and the static scanner as supporting/fallback evidence.
 - Performance / Lighthouse — separate concern, not a plugin metadata issue
 - Cross-plugin integration — that's the bridge skills' job at runtime
 
@@ -87,7 +87,7 @@ Don't migrate to pytest, vitest, or Playwright. The stdlib pattern keeps the har
 - `commands/test.md` — slash-command surface (`/build-loop:test`)
 - `scripts/collision_scan.py` — the static detector that `test_skill_resolution.py` wraps
 - `KNOWN-ISSUES.md` 2026-05-02 entry — testing survey across 13 projects that informed this design
-- `agents/ui-validator.md` and `skills/build-loop/phases/ui-validation.md` — default UI validation route. IBR's `.ibr-test.json` remains an explicit-only auxiliary format.
+- `agents/ui-validator.md`, `skills/build-loop/phases/ui-validation.md`, and `references/ibr-ui-verification-policy.md` — default UI validation route. Authoring a new `.ibr-test.json` remains plan-authorized or explicit.
 
 ## History
 

package/skills/recursive-retrospective/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: recursive-retrospective
-description: Run a recursive-learning retrospective on an app/agent/plugin/build-loop project — analyze build history, behavior, and current state to extract reusable learning objects and encode them into memory, agents, skills, plugins, evals, preflights, and approval gates. Use after a substantial build, when reviewing a project's trajectory, when deciding preserve/refine/redirect/reset, or when converting a session into durable system improvement. Discovery-first (observe behavior → cluster patterns → encode learning); RCA is one module, not the whole job.
+description: Deliberate retrospective on one project's full trajectory — decide preserve/refine/redirect/reset and encode lessons into memory, agents, skills, evals, and gates. Use when the user asks to review a project's history after a substantial build, or convert a session into durable improvement. Not for the automatic cross-run pattern scan (use `self-improve`).
 user-invocable: false
 ---
 

package/skills/repo-closeout/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: repo-closeout
+description: "Compatibility alias for Repository Maintenance. Use when an existing prompt or workflow invokes repo-closeout; route all repository structure, artifact, branch, worktree, sibling consolidation, and local-main maintenance work to repo-maintenance. Deprecated: prefer repo-maintenance for new work."
+user-invocable: false
+---
+
+# Repository Closeout Compatibility Alias
+
+This identifier is retained for one release so existing prompts keep working.
+
+Load and follow the canonical skill and its bundled resources:
+
+```text
+../repo-maintenance/SKILL.md
+```
+
+Use `repo-maintenance` in new prompts, automation, documentation, and handoffs.

package/skills/repo-closeout/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Repository Maintenance (Legacy Alias)"
+  short_description: "Compatibility alias for repo maintenance"
+  default_prompt: "Use $build-loop:repo-closeout to route this request to the canonical Repository Maintenance workflow."

package/skills/repo-maintenance/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: repo-maintenance
+description: "Audit and evolve repository structure — topology, module boundaries, artifact retention, branch/worktree hygiene, and open-source readiness. Use when the user asks how a repo should be structured, why it has duplicate source, wants generated artifacts cleaned, or wants a repo readied to open-source. Never pushes, deletes unique source, or rewrites history without explicit authorization."
+user-invocable: false
+---
+
+# Repository Maintenance
+
+Optimize the repository for the product's real boundaries, then keep it recoverable as worktrees, builds, generated state, and branches evolve. Treat closeout as one phase of maintenance, not the whole workflow.
+
+Resolve `REPO_MAINTENANCE_ROOT` to the directory containing this `SKILL.md` before running bundled scripts. Under Claude Code this is normally `${CLAUDE_PLUGIN_ROOT}/skills/repo-maintenance`; under Codex or another host, derive it from the loaded skill path.
+
+## Establish the product and repository contract
+
+1. Read applicable `AGENTS.md`, architecture, build, coordination, and document-lifecycle guidance.
+2. Check live coordination before editing shared files or refs. Treat notes as provenance, not code proof.
+3. Identify the product, shipped artifacts, consumers, release boundary, owners, and canonical build/test commands.
+4. Resolve the canonical Git root, local `main`, upstream, linked worktrees, and nested or sibling repositories.
+5. Run the read-only baseline:
+
+```bash
+python3 "$REPO_MAINTENANCE_ROOT/scripts/audit_repo_maintenance.py" \
+  --repo "$PWD" --base main --json
+```
+
+Read [references/safety-protocol.md](references/safety-protocol.md) before changing structure, refs, worktrees, stashes, or generated directories.
+
+For repository-boundary, module, or folder-layout work, read [references/repository-taxonomy.md](references/repository-taxonomy.md). For application-specific, build-system, cache, or generated-layout work, read [references/stack-profiles.md](references/stack-profiles.md). When preparing a repository for open-source publication or external/paid distribution — personal-content and secret scrub, de-tracking internal artifacts, `.git` bloat and history-leak review, and distribution signing — read [references/pre-public-hygiene.md](references/pre-public-hygiene.md). Classify signals before recommending a target structure.
+
+## Classify the repository without forcing one label
+
+1. Record observed application, language, build-system, workspace, runtime, ownership, and release signals.
+2. Classify portfolio strategy, repository scope, composition, release coupling, runtime deployment, internal organization, and physical layout independently.
+3. Label heuristic results as inferred with confidence. Directory names and manifests are not product-boundary proof.
+4. Separate current state from target state and name the smallest transition that addresses measured cost.
+5. Preserve framework conventions unless changing them has a concrete product, ownership, security, release, build, or navigation benefit.
+
+Do not flatten `workspace`, `product monorepo`, `service polyrepo`, and `orchestration repo` into one topology enum. They describe different dimensions. Do not treat agent configuration such as `.claude/` or `.codex/` as product architecture.
+
+## Decide the source of truth from product boundaries
+
+Prefer one repository when a component:
+
+- ships only with the parent product;
+- changes and verifies in the same release gate;
+- has no independent consumers, version, or ownership boundary;
+- must stay code-identical to a bundled or generated artifact.
+
+Keep a separate repository when it has an independent public contract, release cadence, consumers, operational boundary, or ownership/security boundary. Do not preserve a repository split merely because history started that way.
+
+Compare a sibling source repository to its proposed in-tree prefix:
+
+```bash
+python3 "$REPO_MAINTENANCE_ROOT/scripts/audit_repo_maintenance.py" \
+  --repo "$PWD" --base main \
+  --compare-repo /path/to/source-repo \
+  --compare-prefix path/inside/current/repo --json
+```
+
+If the sibling head is already an ancestor of `main` and the in-tree prefix has since diverged, the usual disposition is `retire-sibling`, not another merge. Treat comparison output as source-tree evidence only; it is never sufficient retirement authorization. Audit sibling branches, worktrees, stashes, operations, and dirty paths separately before retirement. Preserve unique state under recovery refs.
+
+## Keep structure navigable without ceremonial refactors
+
+- Give each shipped capability one canonical source and a thin stable public boundary.
+- Organize internal files by capability or bounded context; use small, well-named modules behind the stable boundary.
+- Keep generated, vendored, cached, and source-owned paths distinguishable.
+- Verify that every generated or bundled artifact has one reproducible writer and a parity gate.
+- Use revisit/churn and agent cost as structure signals. Do not claim that generic cleanup alone improves correctness.
+- Require a concrete product, ownership, dependency, or verification reason for deep-module or repository-boundary changes.
+- Split modules only when a boundary enforces a public contract, dependency direction, ownership/security rule, independent test/release, real reuse, or measured build benefit. Merge them back when scaffolding and coordinated edits dominate.
+
+## Control build and cache accumulation
+
+Per-worktree or per-agent build roots are valid isolation. Accumulation without retention is repository hygiene debt. Inventory before deleting:
+
+```bash
+python3 "$REPO_MAINTENANCE_ROOT/scripts/audit_repo_maintenance.py" \
+  --repo "$PWD" --base main --artifacts --stale-days 7 --json
+```
+
+The recursive inventory finds matching roots below test modules, worktrees, and agent lanes while pruning descendants of an already-counted artifact root and dependency environments such as `node_modules` and Python virtual environments. It protects canonical top-level `build` and `build-rust` roots by default; use `--protect-artifact` for additional repo-specific roots. Use `--no-default-artifact-protection` only when the repository explicitly defines different canonical roots.
+
+Classify each artifact root as `protected`, `active`, `release-artifact`, `recent-cache`, `cleanup-candidate`, or `review-tracked-or-unignored`. Treat `cleanup-candidate` as a stale ignored review candidate; the script does not prove reproducibility. A `release-artifact` contains a high-confidence distributable such as a DMG, package, archive, installer, mobile build, or an app bundle inside a distribution root and requires an explicit retain/archive/remove decision. Ordinary build products such as an `.app` inside an isolated build cache remain governed by cache retention. `active-missing-artifact` means a live process still references an artifact path that no longer exists; stop or reconcile that process before further deletion. Remove only reproducible, ignored, inactive artifacts within the user's authorized scope. Protect the coordinator/final build, active worktree builds, canonical dependency caches, and anything required for current verification.
+
+Add a repository retention policy when isolation creates named build roots: naming convention, protected roots, active-process test, age threshold, cleanup owner, and the command that refreshes build-server metadata after pruning.
+
+## Structurally clean a polluted data store
+
+The same discipline governs a polluted append-only data store — a log, telemetry corpus, cache, generated dataset, **or a documentation tree an agent writes into** — not just build artifacts. Removing bad records by matching known-bad content is whack-a-mole: it misses the next unknown pollutant and invites repeated "it's clean now" claims that are each wrong (observed: five marker-based passes on one telemetry log, each declared done, each missing more).
+
+1. **Derive one structural signal before deleting anything.** Separate polluted from legitimate by *shape*, not content: a provenance field, an impossible/out-of-registry value, or a context field legitimate data never carries (a `tmp*` temp-dir path, a test-harness cwd, a missing "written by the real path" stamp). A content denylist is acceptable only for a one-time sweep of *known-historical* strings, never as the permanent detector.
+2. **Classify every record, then prove completeness by re-scan.** Cleanup is done when a full re-scan returns zero suspects — never when the known-bad rows are gone. Eyeballing the tail is how residue survives.
+3. **Move, never delete.** Quarantine suspects to a sibling archive (`*.quarantined.*`) plus one full pre-clean snapshot, so every removed record is recoverable.
+4. **Fix the writer, not just the data.** Re-pollution recurs until the source is closed. Add a provenance invariant — *only the production path may write here* (e.g. a live-hook flag; test/ad-hoc writers are suppressed) — and an integrity gate that fails loudly at the earliest boundary (pre-commit/CI) so a regression is caught the next commit, not weeks later. Pair it with an analysis-time quarantine so a consumer never silently computes on corrupted data.
+5. **Never report the store "clean" while any record is unclassified** — the same rule as unclassified repo state below.
+
+**A documentation tree is one of these stores.** The word "data" reads as logs and
+telemetry, so a `docs/` tree full of agent-written plans, RCAs, retrospectives, and
+session handoffs does not look like a polluted store on a careful read — and that
+misread is exactly how one survives. Apply the test by shape, not by name: *does an
+automated writer append here faster than a human curates it?* If yes, it is this
+kind of store, and step 4 binds.
+
+Worked case (build-loop, 2026-08-28): a documentation-boundary audit found 122 of 716
+tracked documents were private working material in a public tree. Draining them was
+proposed as a file-archiving pass. But `skills/spec-writing/SKILL.md` instructed every
+run to write its plan into `docs/plans/` and commit it, so 13 of the 122 regenerated on
+the next run. **The archiving pass would have made room, not progress.** Closing the
+writer — plans now go to the gitignored `.build-loop/plans/` — was the step that had to
+come first; `scripts/doc_boundary.py` is the integrity gate that catches a regression at
+the next commit.
+
+## Evolve work safely
+
+1. Use an isolated worktree for material changes when shared-checkout collision is possible.
+2. Map the change to its capability boundary and enumerate cross-repo consumers before changing contracts or paths.
+3. Run the narrow verifier during implementation and the canonical verifier on the final integration tip.
+4. Regenerate bundled outputs only from canonical source; verify code or artifact parity afterward.
+5. Collapse completed work back to one protected local `main`; remove temporary worktrees and branches only after ancestry or patch-equivalence proof.
+
+## Close completed local work
+
+Give every worktree, branch, stash, dirty path set, sibling source, and artifact root exactly one disposition:
+
+- `integrate` — unique completed work with review and verification.
+- `redundant` — ancestor of `main` or proven patch-equivalent.
+- `retire-sibling` — imported source whose in-tree canonical copy has evolved.
+- `cleanup-candidate` — reproducible, ignored, inactive generated state past retention.
+- `release-artifact` — distributable output requiring an explicit retain, archive, or remove decision.
+- `active-missing-artifact` — a live process references a removed artifact root; reconcile the process before cleanup.
+- `preserve-only` — incomplete, unrelated, user-owned, or historical material.
+- `blocked` — active ownership, failed verification, conflicts, or unclear provenance.
+
+Before mutation, create dated annotated recovery tags for pre-integration `main`, every branch head, and every stash commit under `archive/pre-closeout-YYYY-MM-DD/`. Preserve dirty state including untracked files. Prefer fast-forward integration; re-run the canonical verifier on exact final `main` after the last mutation.
+
+### Grade the base, not the test result
+
+Before assigning `integrate` to any branch, score it. A passing suite describes the branch **at its own base**, and says nothing about merging into today's `main`:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/merge_risk.py" --branch <b> --target main \
+    --evidence "test suite=pass" --evidence-time <ISO8601 when the suite ran> --json
+# or sweep every local branch, risk-first:
+python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/merge_risk.py" --all-branches --json
+```
+
+The load-bearing field is `contested_files` — files the branch changed that `main` **also** changed since the merge-base. When that set is non-empty, `evidence_valid_against_target` is `false` and the verdict is `stale_base_evidence_invalid` (`risk: high`, exit 1). Green evidence supplied alongside contested files makes the verdict more alarming, not less; the script records `evidence_ignored_reason: "produced_at_stale_base"` rather than letting a pass downgrade the risk.
+
+Verdicts, in priority order:
+
+| Verdict | Risk | Exit | Meaning |
+|---|---|---|---|
+| `stale_base_evidence_invalid` | high | 1 | Contested files — the evidence describes a base that no longer reflects target |
+| `evidence_failing` | high | 1 | Supplied evidence says `fail`; a failure is not ignorable either |
+| `conflict_likely` | high | 1 | `git merge-tree` predicts conflicts |
+| `behind_but_disjoint` | medium | 0 (`--strict`: 1) | Target moved, but not on files this branch touched |
+| `conflict_probe_unavailable` | medium | 1 (`--allow-unprobed`: 0) | The conflict probe could not run — an unobserved probe is not a pass |
+| `mergeable_evidence_current` | low | 0 | Base current, evidence current and passing |
+
+`predicted_conflicts` is `null`, never `0`, when the probe is unavailable — and the VERDICT respects that too, not just the field. Both are needed: `None` is falsy in Python, so a scorer that branches on truthiness alone treats "no conflicts" and "never checked" identically and reports the second as mergeable. The script is read-only: no merge, rebase, checkout, or ref write.
+
+`stale_base_evidence_invalid` maps to `blocked`, not `integrate`. Rebase or re-verify against current `main` first, then re-score.
+
+Observed 2026-08-07: branch `bl/run-938939` passed `cargo build`, `cargo test`, and a Python↔Rust parity suite 5288/5288 — at a base of 2026-07-30, while `main` had since changed those same files twice. A scorer reading "tests pass" as low-risk would have auto-merged it. The rebase produced 5 conflict hunks, and the branch side did not compile against `main` (`E0609`, `E0599`).
+
+Clean in dependency order: auxiliary worktrees, contained branches, patch-equivalent branches with recovery proof, archived stashes, stale worktree metadata, then authorized generated artifacts. Never use `git reset --hard` or force-delete unique state as cleanup.
+
+## Report distinct truths
+
+Lead with the disposition, then state:
+
+1. canonical source and repository-boundary decision;
+2. final local `main` commit and verifier evidence;
+3. worktrees, branches, stashes, sibling repos, and artifacts integrated, retained, or removed;
+4. recovery namespace and residual risks;
+5. local-versus-upstream divergence;
+6. committed, merged locally, pushed, deployed, and runtime-tested status separately.
+
+Do not report “merged” for work that exists only on another branch. Do not report “clean” while unique sibling, stash, dirty, or generated state remains unclassified.

package/skills/repo-maintenance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Repository Maintenance"
+  short_description: "Audit repo architecture, artifacts, and closeout"
+  default_prompt: "Use $build-loop:repo-maintenance to classify the application and build profile, audit repository structure and artifacts, and close completed local work safely."

package/skills/repo-maintenance/references/pre-public-hygiene.md

@@ -0,0 +1,134 @@
+# Pre-Public / Distribution Hygiene
+
+Load this phase when a repo is being prepared for **open-source publication or
+paid/external distribution** (any transition from private/solo to external
+consumers). It layers on top of the normal maintenance lifecycle: run the
+artifact/worktree/branch/local-main phases first, then this.
+
+The governing question shifts from *"is this repo well-structured?"* to *"is it
+safe and reproducible in a stranger's hands, and does its history leak anything?"*
+
+Always read [safety-protocol.md](safety-protocol.md) first. History rewrite and
+force-push are irreversible and gated on explicit authorization.
+
+## 1. Personal content & secrets in the working tree (SAFE)
+
+Scan tracked files — never the whole checkout (build caches produce noise):
+
+```bash
+git grep -nI -e '/Users/' -e '/home/' -e "$(whoami)" \
+  -e '[A-Za-z0-9._%+-]\+@[A-Za-z0-9.-]\+\.[A-Za-z]\{2,\}'   # emails
+git grep -nIE '(api[_-]?key|secret|token|password|BEGIN (RSA|EC|OPENSSH) PRIVATE KEY|ghp_[A-Za-z0-9]{36}|sk-[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16})'
+```
+
+Then **separate leaks from intentional publisher identity** — the second set stays:
+
+| Leave (identity) | Fix (leak) |
+|---|---|
+| SPDX copyright headers (author name/email) | Absolute home paths (`/Users/<you>/…` → `~/…` or `<repo-root>`) |
+| `github.com/<owner>/…` project URLs | Real home paths / usernames in **test fixtures** (violates no-personal-content-in-fixtures) |
+| `com.<owner>.*` bundle IDs / reverse-DNS | Personal machine paths in code **comments** / dead references |
+| Team ID / signing identity in a *distribution* config | Local `file://…` paths in code defaults → repoint to the public URL |
+
+Code defaults carrying a home path (e.g. a serialized source-pin URL) may be
+**behavior-safe to change** — trace whether the value is dereferenced or is pure
+metadata, and re-run the test that asserts it. Fix, then re-run the owning test.
+
+## 2. Documentation audience — what may be public at all (SAFE)
+
+De-tracking tool state is mechanical; deciding whether a *document* may ship is a
+policy call. The policy is
+[public-repository-documentation-boundary.md](../../../references/public-repository-documentation-boundary.md)
+at the plugin root — §2 is the allow-list, §3 the deny-list, §4 the
+archive-before-removal rule. Read it before keeping or removing any doc. It binds
+public repositories only: a private repo may retain both product documentation and
+internal development records.
+
+Grade the tree before arguing about it:
+
+```bash
+python3 <build-loop>/scripts/doc_boundary.py --repo . --json
+```
+
+The classifier reports the policy's own four buckets — `public_current`,
+`private_archived`, `public_removed`, `blocked` — with a `confidence` and the
+matched signal per file. A filename only *seeds* a verdict (policy §3: "Naming is
+evidence, not the decision"); where only the content resolves the audience it
+returns `needs_review` rather than guessing, and those are the ones you read. Exit
+1 means decided findings; a private or unresolved-visibility repo is reported,
+never failed.
+
+Nothing leaves public tracking until the private copy carries a `build-loop-memory`
+receipt (policy §4). Then ignore the artifact **class**, not the file — the
+agent-rally-point `.gitignore` block (`docs/plans/`, `docs/*RCA*.md`,
+`docs/*ASSESSMENT*.md`, `/BACKLOG.md`, `/LESSONS.md`, …) is the worked example — so
+the next agent cannot reintroduce it.
+
+## 3. De-track internal artifacts (SAFE — files stay on disk)
+
+`git rm -r --cached` (never delete from disk) + gitignore, for content that
+should not ship publicly:
+
+- Tool state: `.navgator/`, `.build-loop/`, `.claude/` scratch, editor/project
+  generated dirs — tool artifacts, not source.
+- Captured test evidence / scan dumps (screenshots, AX JSON, e2e logs) — usually
+  the *bulk* of leaked personal paths; de-track wholesale beats sanitizing each.
+- **`archive/*.bundle` / history bundles** — a committed git bundle leaks the
+  *entire* pre-sanitization history even after a tree scrub. Always de-track.
+- Committed build outputs / vendored binaries → build-from-source instead
+  (see stack-profiles.md); a committed binary can drift from or be tampered
+  against its source.
+
+## 4. `.git` size: gc BEFORE deciding on a rewrite (SAFE gc / GATED rewrite)
+
+Loose-object bloat is usually reclaimable with **no history change**:
+
+```bash
+git count-objects -vH          # if `size` (loose) >> `size-pack`, gc wins big
+git gc --prune=2.weeks.ago     # grace window keeps recent dangling objects
+```
+
+Only *after* gc, assess whether the remaining pack justifies a history rewrite.
+The stronger argument for a rewrite is usually **privacy** (history still holds
+every personal path/secret ever committed), not size.
+
+**Rewrite is GATED — never silent.** Prefer the lowest-risk option:
+
+1. **Fresh-cut public repo** (recommended default): publish a new repo whose root
+   is a squash/graft at the sanitized commit. Zero rewrite risk to the private
+   repo; clean public history. Best when private history need not travel.
+2. **`git filter-repo --invert-paths`** on the private repo only when history
+   must be preserved public. Before running: `git bundle create ../backup.bundle
+   --all` + verify; check whether local `main` is **ahead of `origin`** (a botched
+   rewrite with no pushed backup loses unpushed work); every SHA changes and all
+   clones/cross-references break. Requires explicit user confirmation.
+
+## 5. Distribution signing / notarization (GATED — needs a credential)
+
+Dev builds commonly ship ad-hoc (`CODE_SIGN_IDENTITY="-"`). A distributed build
+needs a real signing identity the maintainer holds — document the runbook, do not
+automate cert install (never touch the login keychain automatically):
+
+- Enroll / verify the platform developer program; create the distribution cert
+  in the keychain (manual user step).
+- Add signing identity + team to a **distribution config variant**, keeping the
+  ad-hoc identity as the dev default.
+- Sign nested binaries (daemons/helpers) with hardened runtime + timestamp →
+  submit to the notary service → staple → verify (`spctl -a -vv` on macOS).
+
+## Execution order & tiers
+
+1. **SAFE, now:** gc → grade the docs tree against the boundary policy
+   (`doc_boundary.py`) and read every `needs_review` → archive-with-receipt, then
+   de-track internal artifacts → de-personalize tracked files
+   (fixtures/comments/docs/code-default URLs), each code change re-verified by its
+   owning test.
+2. **GATED:** history-rewrite decision (recommend fresh-cut) — decide only after
+   gc; requires confirmation and a backup bundle.
+3. **DEFER to credential:** write the signing/notarization runbook now; execute
+   when the maintainer has the cert in hand.
+
+Report the boundary review in the policy's own vocabulary (`public_current` /
+`private_archived` / `public_removed` / `blocked`), then what was de-tracked
+(counts), reclaimed size, residual identity strings intentionally kept, and the
+gated items awaiting a decision.

package/skills/repo-maintenance/references/repository-taxonomy.md

@@ -0,0 +1,161 @@
+# Repository Taxonomy and Module Boundaries
+
+Use this reference when classifying a repository, choosing Git boundaries, changing modules, or evaluating a proposed folder tree. This is a working decision taxonomy, not an industry-standard list of mutually exclusive repository types.
+
+## Contents
+
+1. Classification model
+2. Mapping common topology labels
+3. Repository-boundary decision
+4. Internal organization patterns
+5. Module-boundary decision
+6. Evolution and validation
+7. Output contract
+
+## 1. Classification model
+
+Classify each axis independently. A repository can be a product-scoped monorepo, use several language workspaces, contain a modular monolith plus a daemon, and release some packages independently. One label cannot express all of that.
+
+| Axis | Values | Question answered |
+| --- | --- | --- |
+| Portfolio strategy | `monorepo`, `polyrepo`, `hybrid` | How is source divided across Git repositories? |
+| Repository scope | `single-component`, `product`, `organization`, `integration-orchestration` | What product or coordination boundary does this repository own? |
+| Composition | `single-package`, `workspace`, `multi-app`, `multi-service`, `package-family`, `mixed` | What independently buildable units are coordinated inside the repository? |
+| Release coupling | `coordinated`, `independent`, `mixed` | Which units version and ship together? |
+| Runtime deployment | `single-deployable`, `modular-monolith`, `multiple-deployables`, `library-package`, `mixed` | What executes or distributes independently? |
+| Internal organization | `technical-layer`, `feature-first`, `domain-oriented`, `layered-feature`, `package-module`, `deployable-first`, `hybrid` | What is the primary grouping dimension inside a unit? |
+| Ownership and risk | team owners, security boundaries, compliance boundaries | Who can change what, and which boundaries must be enforced? |
+| Physical layout | stack-specific paths | How do the selected build systems express these decisions on disk? |
+
+Do not infer portfolio strategy from a workspace manifest. Cargo, Gradle, SwiftPM, pnpm, and similar workspaces coordinate packages within a checkout; they do not decide whether the organization uses a monorepo or polyrepo.
+
+## 2. Mapping common topology labels
+
+Use familiar labels as shorthand, then expand them into the independent axes above.
+
+| Common label | Normalized meaning |
+| --- | --- |
+| Single-project repo | Usually `single-component` scope plus `single-package` composition; may still contain several targets. |
+| Workspace repo | A `workspace` composition signal. Portfolio strategy and repository scope remain undecided. |
+| Product monorepo | `monorepo` portfolio plus `product` scope; composition may be multi-app, multi-service, package-family, or mixed. |
+| Organization monorepo | `monorepo` portfolio plus `organization` scope. Requires strong tooling and ownership controls. |
+| Service-per-repo | Usually `polyrepo` portfolio, service-sized scope, and independent releases. |
+| Package-per-repo | Usually `polyrepo` portfolio, library-package deployment, and independent versioning. |
+| Hybrid portfolio | `hybrid` portfolio; record the rule that determines which units share a repo. |
+| Meta/orchestration repo | `integration-orchestration` scope; source of truth should remain in the repositories it coordinates unless explicitly vendored or generated. |
+
+These are useful recurring shapes, not eight values on one axis.
+
+## 3. Repository-boundary decision
+
+Start with the product and release boundary, not the current folder tree.
+
+Prefer one repository when most of these are true:
+
+- units normally change in one user-visible feature or compatibility transaction;
+- the same integration gate is required before release;
+- releases are coordinated and there is no external compatibility promise;
+- one owner and security boundary controls the units;
+- consumers are internal to the same product;
+- atomic changes reduce integration risk more than repository size increases tooling cost.
+
+Prefer separate repositories when one or more strong boundaries exist:
+
+- independent public contract and semantic versioning;
+- independent external consumers or distribution channel;
+- independent release, availability, security, compliance, or ownership boundary;
+- access control cannot be expressed safely inside one repository;
+- checkout, history, or CI cost remains materially high after ordinary optimization;
+- the unit must evolve without coordinating with the parent product.
+
+Use evidence, not repository count aesthetics. Record:
+
+1. product and consumers;
+2. change coupling from recent history;
+3. release and compatibility coupling;
+4. build and test fan-out;
+5. ownership, access, and operational boundaries;
+6. migration cost and recovery plan.
+
+Monorepo does not mean monolith. Polyrepo does not mean microservices. Repository placement, module boundaries, and runtime deployment are separate decisions.
+
+## 4. Internal organization patterns
+
+Choose one primary grouping dimension at each level. Hybrid structures are valid when the transition point is explicit.
+
+| Pattern | Best fit | Main risk |
+| --- | --- | --- |
+| Technical-layer | Small, stable applications where flow across UI/domain/data remains easy to trace | Feature changes fan out across distant directories. |
+| Feature-first | Product applications with independently evolving user capabilities | Shared code can become an unowned junk drawer. |
+| Domain-oriented | Complex business rules and durable bounded contexts | Domain ceremony can exceed product complexity. |
+| Layered-feature | Feature ownership with internal UI/domain/data separation | Repeated scaffolding and inconsistent local layers. |
+| Package-module | Enforceable compile, visibility, ownership, or reuse boundaries | Too many modules increase configuration and build-graph overhead. |
+| Deployable-first | Multiple services, workers, apps, or independently operated runtimes | Shared packages can couple deployables invisibly. |
+| Hybrid | Products with genuinely different scales or runtime shapes | Ambiguous transition rules make navigation unpredictable. |
+
+For a hybrid, state the rule, for example: `apps/` and `services/` are deployable-first; each deployable is feature-first; reusable contracts live under `packages/`.
+
+## 5. Module-boundary decision
+
+Create or retain a module when it provides at least one enforceable benefit:
+
+- an independently testable capability or volatile implementation is hidden behind a stable interface;
+- compile-time visibility or dependency direction needs enforcement;
+- ownership or security responsibility differs;
+- reuse is real and already has more than one consumer;
+- change history shows cohesive files repeatedly moving together;
+- independent build caching or release behavior measurably reduces cost.
+
+Consolidate modules when configuration, adapters, and boilerplate dominate the capability; boundaries are routinely bypassed; most changes require coordinated edits across them; or no independent consumer, owner, test, or release exists.
+
+For every proposed module, record:
+
+```text
+Capability:
+Public contract:
+Hidden decision:
+Consumers:
+Owner:
+Allowed dependencies:
+Verification gate:
+Split trigger:
+Merge-back trigger:
+```
+
+Agent/configuration overlays such as `.claude/`, `.codex/`, or repository-local skills may improve how tools operate on the repository. They are not product modules and must not substitute for runtime architecture, package boundaries, or product documentation.
+
+## 6. Evolution and validation
+
+Treat structure as a hypothesis. Prefer the smallest reversible transition that addresses observed cost.
+
+Split a package, module, or repository when measured evidence shows growing independent ownership, release, security, consumer, or build boundaries. Merge or flatten when the proposed boundary has no enforceable contract and increases navigation or change fan-out.
+
+Validate a structural change with:
+
+- the canonical build and targeted tests;
+- dependency-direction or visibility checks;
+- change fan-out on representative recent features;
+- navigation cost: files and manifests needed to understand or edit one capability;
+- generated/bundled artifact parity;
+- release and rollback procedure;
+- checkout, CI, or build metrics when performance was the reason for change.
+
+Do not claim correctness improvement from tidiness alone. Cleaner module shape can reduce navigation and maintenance cost; correctness still requires behavior-specific verification.
+
+## 7. Output contract
+
+Separate three truth levels:
+
+- **Observed** — manifests, paths, Git history, dependency edges, owners, build commands, and releases directly inspected.
+- **Inferred** — likely classification with evidence and confidence; never present a filename heuristic as architectural fact.
+- **Decided** — current or target structure chosen by the product owner, with rationale, migration, and validation gates.
+
+Report all applicable axes, the current and target state, the smallest transition, rejected alternatives, and the evidence that would reverse the decision.
+
+## Source basis
+
+- Cargo workspaces coordinate related packages through a shared lockfile and target directory: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
+- Android's modularization guide describes benefits and warns about both overly fine and overly coarse granularity: https://developer.android.com/topic/modularization
+- GitHub documents repository size, width, depth, branch, and activity limits as operational constraints: https://docs.github.com/en/repositories/creating-and-managing-repositories/repository-limits
+- Research on multi-repository microservice architecture reconstruction documents the difficulty of maintaining accurate architecture across independently evolving services: https://arxiv.org/abs/2602.08166
+- A systematic grey-literature review describes modular monoliths as an alternative to, and possible transition point toward, microservices: https://arxiv.org/abs/2401.11867