docs/INDEX.md (contract catalog) and docs/index.md (MkDocs landing) shared the
same case-folded name on case-insensitive filesystems, leaving the working tree
in a phantom-modified state and breaking contract-compatibility-gate when the
script read whichever file the OS resolved at run time.
Resolves TASK-1 + TASK-2 of .agents/plans/2026-04-26-resolve-docs-index-case-collision.md:
- Move catalog content from HEAD:docs/INDEX.md into docs/documentation-index.md
- Repoint contract validators (scripts/check-contract-compatibility.sh,
scripts/contract-orphans-allowlist.txt) and their tests at the new path
- Update navigation references across README.md, AGENTS.md, CLAUDE.md, and the
docs/ tree (newcomer-guide, CONTRIBUTING, CI-CD, plans/, positioning/,
templates/, contract examples)
- Replace stale docs/README.md mentions in CLAUDE.md / AGENTS.md / repo-execution
profile example with docs/index.md (the actual MkDocs landing)
Verification:
- bash scripts/check-contract-compatibility.sh -> 0 failures, 24 contracts catalogued
- bash tests/scripts/test-contract-compatibility-gate.sh -> 7/7 PASS (verified pre-rebase)
- bash tests/skills/test-repo-native-orchestration.sh -> 28/28 PASS (verified pre-rebase)
- git ls-files | awk casefold-dup scan -> empty
TASK-3 (casefold-collision guard script) and TASK-4 (worktree disposition) from
the plan remain to be done in a follow-up.
Defines a tracked contract for swarm worker result files living under
.agents/swarm/results/<task>.json. These files were implicitly shaped
but never validated — misshapen packets could silently break crank
result ingestion.
- schemas/swarm-evidence.schema.json: JSON Schema. Required: task,
status, files_changed, notes. Optional: tests, gate, evidence,
before/after counters. additionalProperties=true permits task-specific
extensions.
- scripts/validate-swarm-evidence.sh: jq-based validator accepting a
file or directory. ajv fallback when available. Exit 0 pass, 1 fail.
- docs/contracts/swarm-evidence.md: human-readable contract doc with
example and schema link. Added to docs/INDEX.md catalog.
- scripts/pre-push-gate.sh: new section 26b ('swarm evidence schema')
invokes the validator on every push.
- scripts/check-contract-compatibility.sh: extended ref resolution to
also search schemas/ so docs/contracts/*.md can cite
schemas/*.schema.json without tripping the cataloguing check.
Consumes ag-yhr 'Implement executable swarm evidence schema validation'.
- Fix hardcoded /tmp path in test-json-flag-consistency.sh (use mktemp)
- Add graceful skip for missing jq/python3 in check-contract-compatibility.sh
- Fix import grouping in maturity_test.go
- Update .agents/retros/ → .agents/learnings/ in ratchet gate.go
- Extract _validate_restricted_cmd to lib/hook-helpers.sh (shared lib)
- Wire test-json-flag-consistency.sh into CI (new validate.yml job)
- Add post-merge naming cleanup step to swarm local-mode.md
- Document operationalization heuristics in plan SKILL.md
- Create check-file-manifest-overlap.sh for pre-spawn conflict detection
- Wire file manifest overlap check into CI with self-tests
- Pre-mortem fixes: bash 4+ guard, mktemp in CI self-tests
- Merge 696 test functions from 30 *_coverage_test.go files into
existing *_test.go counterparts, reconcile imports, delete sources
- Add example→schema conformance validation to check-contract-compatibility.sh
- Add tests/cli/test-json-flag-consistency.sh for --json flag coverage
- Zero *_coverage_test.go files remain; go vet + go test pass clean
Replace hardcoded file list with dynamic checks:
- INDEX.md link resolution (all contracts/ refs verified)
- Bridge doc cross-reference verification
- Contract .md embedded schema reference resolution
- JSON schema/example validity (jq validation)
- Orphan detection (files on disk not in INDEX.md)
- Also catalogue rpi-run-registry and rpi-phase-result in INDEX.md
Boden Fuller