docs: consolidate scattered docs — archive 3 historical files, slim skills.md#55
Merged
Conversation
…kills.md
Across this repo's lifetime we've accumulated ~17 markdown files
touching adjacent topics (specs, coverage, conventions, runbooks,
historical analyses). Several have real overlap and the
"what-to-update-on-a-spec-change" cost is high.
This is a focused first pass to reduce scatter without losing
content.
# Archived
Three time-bound / one-shot historical docs move to docs/archive/:
- docs/test-review-2026-05-20.md (snapshot review, time-bound)
- docs/logout-all-contract-evolution.md (one-shot analysis, decision landed)
- docs/root-cause-88-2026-05-20.md (incident RCA, belongs in PR history)
Adds docs/archive/README.md explaining the convention: time-bound,
decision-shaped, or superseded docs go here; pointers back to the
current working docs are listed for anyone landing in the archive
folder by mistake.
# Slimmed skills.md (445 → 321 lines, -28%)
Two sections deleted as redundant:
- §0 Fast + reliable run profiles → already documented in README.md
(Running section) + CLAUDE.md (conventions). Was duplicating env
/ workers / pacing guidance.
- §1 openspec coverage → redundant with docs/spec-coverage.md, which
is the hand-maintained audit table. The intro now points at that
doc explicitly.
Kept (all unique content):
- §1 (was §2) Orthogonal coverage — narrative of OWASP /
product-UX / per-app admin tests outside the openspec scope
- §2 (was §3) Per-app link-coverage rules L1–L8 — the
tests/lib/link-coverage.ts contract
- §3 (was §4) Per-app branding table
- §4 (was §5) Adding a new app — five-step checklist
- §5 (was §6) Findings + known limitations F1–F11 — hard-won
caveats about what each test catches and what it doesn't
- §6 (was §7) Implementation reference — lib pointers
- §7 (was §8) Bug staging workflow — tests/bugs/ lifecycle +
test-writer agent pipeline
Stale cross-reference in §1 ("see workspace-auto-join#auto-join-role
above") rewired to point at the current audit table + deferred doc.
# Updated stale counts
- README.md "Today: 84 requirements" → "88 requirements" with
matching skill count (32 → 36) and a `make audit` pointer for
live numbers.
# Updated CLAUDE.md "Read these in order"
Reordered to put the audit (docs/spec-coverage.md) ahead of
skills.md (because skills.md no longer carries the table) and
re-described skills.md's role to its remaining unique content
(findings, link rules, bug-staging workflow). TESTS.md kept but
flagged as hand-maintained and possibly lagging — `git log -- tests/`
is the source of truth.
# Out of scope for this PR (follow-up candidates)
- Auto-generating docs/spec-coverage.md from the audit script
- Retiring TESTS.md in favour of an auto-generated index or a
README pointer
- Moving §3 link-coverage rules into the tests/lib/link-coverage.ts
file head if we want to remove skills.md entirely
Audit + typecheck remain clean (88 covered/deferred/missing total
unchanged — this PR is doc-only).
5 tasks
awais786
added a commit
that referenced
this pull request
Jun 3, 2026
TESTS.md was already flagged as "hand-maintained, may lag — git log is the truth" in CLAUDE.md after PR #55. That's a soft deprecation; this commit follows through. The catalog's content is redundant with: - @SPEC tags above each test - the audit table at docs/spec-coverage.md - per-file head comments Drift between TESTS.md and reality has been the highest of any doc in the suite (every test add/remove needs a hand-edit). Retiring it removes the maintenance burden without losing information. Changes: - TESTS.md → docs/archive/TESTS.md (preserved for provenance) - docs/test-review-2026-05-{22,30}.md → docs/archive/ (the 2 review snapshots from prior sessions that were sitting untracked at the repo root level of docs/; same time-bound shape as the test-review-2026-05-20 that PR #55 already archived) - CLAUDE.md "Read these in order": point at file-head comments + `grep -nA1 "// @SPEC" tests/` instead of TESTS.md - README.md opening highlight: point at docs/spec-coverage.md (which has the requirement-by-requirement table) instead of TESTS.md (which had the per-test catalog by another name) - scripts/check-doc-paths.sh: drop TESTS.md from DOC_FILES (no longer at the repo root) After this: - Live doc set at root: CLAUDE.md, README.md, skills.md, TRIAGE.md (4, down from 5) - Archive: 4 historical files + the new TESTS.md
5 tasks
awais786
added a commit
that referenced
this pull request
Jun 4, 2026
docs/spec-coverage.md was the highest-drift hand-maintained file in the repo's doc set. Every PR that added a test, retitled a requirement, or moved an entry in spec-coverage-deferred.md needed a matching hand-edit. The counts went stale routinely (we caught the "59 of 84" line in skills.md during PR #55; the audit table itself drifted more silently). # What Adds `scripts/gen-spec-coverage.sh` — a pure-bash generator that reads the same inputs the audit reads: - Per-module `### Requirement:` blocks from `vendor/openspec/specs/*/spec.md` and `vendor/openspec/skills/*/SKILL.md` - `// @SPEC module#slug` tags across `tests/` - Categorised deferred entries in `docs/spec-coverage-deferred.md` …and emits the full markdown table to stdout. Coverage state mirrors the audit, with one additional distinction: - ✅ — at least one @SPEC tag - 🟡 Partial — tagged AND the deferred doc carries a "Partially covered" note -⚠️ Deferred — no tag; deferred entry with rationale - ❌ Missing — neither; CI fails on this state via the existing audit script (the generator emits it for honest reporting even though the audit blocks before it can ship) # Wiring - `make spec-coverage-doc` writes the regenerated file. - `make check-spec-coverage-doc-fresh` runs the generator and `diff -u` against the committed file. Fails the PR if stale. - Added to `make pre-commit` so local runs catch drift before push. - Added a "Check spec-coverage.md is fresh" step to `.github/workflows/spec-coverage.yml`. Same gate at CI time. # Slug normalisation fix While writing the generator, found a case-mismatch between spec.md ("Layer 1 expiry SHALL ...") and the corresponding deferred entry ("... shall ..."). The audit handles this by slugifying both sides before comparison; an earlier generator draft compared raw titles and reported a false "❌ Missing" for that one entry. Fixed by slugifying titles in collect_deferred_categorised + category_for_deferred. Audit and generator now agree. # Counts (this regeneration) - 61 ✅ Covered - 2 🟡 Partial - 25⚠️ Deferred - 0 ❌ Missing = 88 total Sum (covered + partial = 63) matches the audit's "covered" count exactly. Deferred count matches. Total matches. # Out of scope (follow-ups) - The per-row nuance the old hand-curated file carried (e.g. "Outline observable; PM/Penpot/SurfSense/Twenty skip — no JS-readable session cookie") is dropped in this regeneration. That nuance belongs in the test file's head comment, which is the right place for it and where the test author already documents it. The audit table is now a clean index.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Across this repo's lifetime we've accumulated ~17 markdown files
touching adjacent topics (specs, coverage, conventions, runbooks,
historical analyses). Several have real overlap and the
"what-to-update-on-a-spec-change" cost is high.
This is a focused first pass to reduce scatter without losing
content.
Archived
Three time-bound / one-shot historical docs move to docs/archive/:
Adds docs/archive/README.md explaining the convention: time-bound,
decision-shaped, or superseded docs go here; pointers back to the
current working docs are listed for anyone landing in the archive
folder by mistake.
Slimmed skills.md (445 → 321 lines, -28%)
Two sections deleted as redundant:
(Running section) + CLAUDE.md (conventions). Was duplicating env
/ workers / pacing guidance.
is the hand-maintained audit table. The intro now points at that
doc explicitly.
Kept (all unique content):
product-UX / per-app admin tests outside the openspec scope
tests/lib/link-coverage.ts contract
caveats about what each test catches and what it doesn't
test-writer agent pipeline
Stale cross-reference in §1 ("see workspace-auto-join#auto-join-role
above") rewired to point at the current audit table + deferred doc.
Updated stale counts
matching skill count (32 → 36) and a
make auditpointer forlive numbers.
Updated CLAUDE.md "Read these in order"
Reordered to put the audit (docs/spec-coverage.md) ahead of
skills.md (because skills.md no longer carries the table) and
re-described skills.md's role to its remaining unique content
(findings, link rules, bug-staging workflow). TESTS.md kept but
flagged as hand-maintained and possibly lagging —
git log -- tests/is the source of truth.
Out of scope for this PR (follow-up candidates)
README pointer
file head if we want to remove skills.md entirely
Audit + typecheck remain clean (88 covered/deferred/missing total
unchanged — this PR is doc-only).
Motivation / Background
This Pull Request has been created because:
Detail
This Pull Request changes:
Additional information
TIP: Provide additional information such as screenshots, benchmarks, reference to other repositories or alternative solutions
Checklist
Before submitting the PR make sure the following are checked:
[Fix #issue-number]