fix(validator): bind the SSoT ignore guard to git instead of .gitignore text

[KbWen]

A sibling fork of the same ancestor reported six governance findings. Diagnosis against this tree confirmed one root cause worth fixing here, at two altitudes — and the same blind spot had grown independently in both forks, which is what makes it a class rather than a slip.

The defect

.gitignore preserves persistent SSoT artifacts compared whole .gitignore lines against a fixed list of directory paths. .agentcortex/context/archive/*.md hides the archived Work Logs without ever spelling that directory, so the guard reported PASS while the governance record stopped being committed.

Reproduced before fixing — one appended line, fail=0, and git check-ignore confirming the logs were hidden:

$ printf '\n.agentcortex/context/archive/*.md\n' >> .gitignore
$ git check-ignore -q .agentcortex/context/archive/some-worklog.md ; echo $?
0
$ bash .agentcortex/bin/validate.sh | grep -E 'persistent SSoT|Summary:'
[PASS] .gitignore preserves persistent SSoT artifacts
Summary: pass=86 warn=1 fail=0 skip=8

The fix, and the three regressions it took to get right

The check now asks git. Four flags carry the correctness, and each of the last three was a regression I introduced and an independent reviewer caught:

probe a file inside each protected artifact	a directory probe reproduces the original blindness — docs/specs/*.md ignores contents without matching the directory
verdict from -q, never -v	-v exits 0 whenever a pattern matched, negations included. On docs/adr/* + !docs/adr/*.md, -v exits 0 while -q exits 1 and git tracks the file — reading -v would fail a correct adopter and name their protective ! line as the pattern to remove
--no-index	without it check-ignore skips tracked paths, so current_state.md — the one real probe — is inert in every healthy deploy. A detection narrowing inside a change meant to broaden
outer-repo cause re-labels, never re-decides	all probes ignored and non-empty rev-parse --show-prefix. Deliberately not check-ignore -- .: a blank CRLF line is the pattern \r, git strips it to the empty string, and the empty pattern matches . — that discriminator failed every core.autocrlf=true checkout, including this repository

Also: no longer gated on .gitignore existing (that branch emitted a PASS asserted without looking at anything, while .git/info/exclude and a global excludes file hide files just as well), and tri-state so a check that could not run reports SKIP rather than assurance.

The playbook is now bound to the mechanism

audit-guardrails.md Test 1 asserted git status shows none of .agent/, .agents/, .antigravity/, .agentcortex/context/. A real cold deploy shows 58 / 29 / 1 / 2 paths — and its command did not run at all, since --force is not a deploy.sh flag and the catch-all *) takes it as TARGET.

Rewritten to the verified ignore set, re-pointed at the canonical deploy.sh (the wrapper clones from the remote and writes an .agentcortex-src/ cache into the reader's own tree — this guide ships downstream), and bound by a test that executes the page's own assertion list against a real deployed ignore block. Both language twins; heading kept verbatim because it is an encoding canary in both validators.

Adopter delta

Measured on one identical tree with each version's own deployed validator, .gitignore hiding both the archive and the adopter's own spec:

• v1.8.23 → [PASS] .gitignore preserves persistent SSoT artifacts, fail=0
• this build → [FAIL] 2/6 probes ignored naming each source:line

On a healthy tree the tallies are identical before and after upgrade, so this adds detection without adding churn. All four changed deployed files are core tier — adopters get it on their next deploy with no action.

Evidence

• 17 scenarios across install / update / dev, each run rather than reasoned about: fresh deploy · --no-python host · non-git tree · nested under an outer vendor/ ignore · upgrade from v1.8.23 with downstream state seeded · re-deploy ×3 · rollback · no-trailing-newline .gitignore · git worktree · the pre-commit hook's real interpreter (powershell 5.1, not pwsh) · CRLF .gitignore
• 16 test arms, every new guard mutation-proved against the code it guards
• Full CI-equivalent suite, no -m filter, run as CI runs it (--splits 3): 913 passed, 1 skipped, 0 failed
• Both validators on this repo: pass=118 warn=3 fail=0 skip=2, identical, exit 0
• ADR-006 native-check ratchet unmoved at 204/204 — the stricter guard cost no ratchet headroom

What this does not do

The parity and structural guards live in non-required CI contexts, so they fail visibly on a PR and nothing more; making one blocking is a branch-protection setting, not something this branch can reach. Pytest is never exercised under the 3.9 floor — CI's 3.9 job runs validate.sh only — so 3.9 compliance here rests on the static ratchet plus a scan, not on ever running these files under 3.9. And the probes are representative, not exhaustive: a pattern narrower than the probe name (archive/*-worklog.md) still slips through. It catches the whole-directory and whole-extension shapes, which is the class that bit downstream.

Four findings surfaced by doing the work were filed rather than folded in: #183 workflow job-graph needs: integrity, #184 PowerShell version floor + a 5.1 CI arm, #185 backtick-path reference integrity, #186 token-governance.md §8's compaction target colliding with the archived-Work-Log contract.

🤖 Generated with Claude Code