grant/standards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Thread inbox-check line and canonical .gitignore into the retrofit flow; scope relative-symlink rule to in-repo links

Browse Source 
Retrofit playbook Step 0/Step 1 and the /retrofit guide now seed every new repo
with the canonical .gitignore block and the inbox-check line, and Part 5 documents
/capture, /triage, /roundup. portability.md and the portability-checker guide now
scope the relative-symlink mandate to in-repo (committed) symlinks, so global
~/.claude/* links are no longer flagged. ROADMAP adds a high-priority cross-repo
git-hygiene audit.
This commit is contained in:
Keysat
2026-06-14 11:15:16 -05:00
parent 72bebdd3e8
commit 04651503d2
5 changed files with 42 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
guides/portability-checker.md
+8 -3
View File
@@ -26,6 +26,9 @@ A path to the repo to audit (default: the current working directory).
3. **Resolve every symlink concretely.** Use `ls -l` / `readlink` (not assumptions): confirm
it exists, points the correct *direction*, its target exists (not dangling), and the link
is **relative**, never absolute — an absolute link breaks if the repo is cloned or moved.
Scope this to symlinks *inside the repo* (the ones git commits). Symlinks outside the repo
— notably the global `~/.claude/*` links — are never committed and are recreated per
machine, so they may be absolute without harm; do not flag them in a repo audit.
4. **Check each layer against the checklist below**, citing file paths and `readlink` output.
5. **Reconcile with the live spec.** If `portability.md` states a rule the checklist doesn't
cover, check it too and flag the gap.
@@ -60,7 +63,8 @@ A path to the repo to audit (default: the current working directory).
**Self-containment and swap-readiness**
- Everything required to work on the repo lives in the repo. A hard dependency on a global
or user-level file for a *requirement* (not a preference) is a blocker.
- All vendor symlinks are relative, so the repo stays portable.
- All vendor symlinks **inside the repo** are relative, so the repo stays portable. (The
global `~/.claude/*` links are out of scope — not part of the repo and never committed.)
- `.gitignore` covers `.env`; no secrets, large binaries, or generated artifacts committed.
## Hard rules
@@ -68,8 +72,9 @@ A path to the repo to audit (default: the current working directory).
user can run (the `git mv` / `ln -s` to run), never apply them.
- Every PASS/FAIL cites concrete evidence: a file path, a `readlink` result, a line number.
Anything you did not actually inspect is UNVERIFIED, never assumed.
- Verify both **direction** and **relativeness** of every symlink — a link that resolves but
points the wrong way, or is absolute, fails.
- Verify both **direction** and **relativeness** of every **in-repo** symlink — a link that
resolves but points the wrong way, or is absolute, fails. (Global `~/.claude/*` links are
out of scope.)
- Distinguish **blockers** (break vendor-neutrality or hot-swap) from **warnings** (friction
or style). The absence of an optional layer (no subagents, no scoped guides) is neither —
list it as Not applicable. Only present-but-wrong is a finding.