Skip to content

Bring the documents back in line with the direction - #50

Merged
junixlabs merged 2 commits into
mainfrom
docs-catch-up
Sep 11, 2026
Merged

junixlabs merged 2 commits into
mainfrom
docs-catch-up

Conversation

@junixlabs

Copy link
Copy Markdown
Owner

The direction changed; four documents did not. Found by auditing rather than by
remembering, which is the only method this repository is entitled to use.

1. The roadmap contradicted the measurements

The README still carried the v0.1 roadmap:

v0.2  Parser / model engine      ← retired, not rescheduled
v0.3  Agent integration          ← skills shipped
v0.4  Graph explorer             ← shipped, on Pages
v0.5  Change impact engine       ← shipped; its open question is measurement (#5)

"v0.2 — parser / model engine" is the entry two days of measurement refuted. Git
already ships per-language funcname heuristics; git log -L narrowed 145 of this
repository's file-level decay events to 23, and a peer's 132 to 39, on TypeScript and
Python alike with nothing configured. The parser this project was going to build is one
it should never build.

Replaced by the four horizons from DIRECTION.md, each with the measurement that decides
it — H1 by #10, H2 by ADR-015's three-incident test, H3 by whether teams can cite a frozen
record at all, H4 by #5. DIRECTION.md gains the section recording why the parser entry
was deleted, with the general form this project had to learn twice in a day: check what
the dependency already does before building the thing it does.

2. skills/reference/ had no entry for INV-027 or INV-028 — and the checker was fine with it

skills/reference/ is the stated single home for the rules; the SKILL.md files cite by
id instead of restating. check_docs scanned all of skills/, so a citation inside a
SKILL.md satisfied "cited by a skill" and two rules landed with no reference entry at
all
.

That is the drift this checker exists to catch, occurring in the checker. Fixed in code,
not in prose: check_docs now requires an entry in skills/reference/ specifically, and
the two rules have real entries. Verified it fails when either heading is removed.

The assertion covering this said the invariants stay "tripled" across three homes. There
are four. The claim was wrong, not just its evidence — corrected, with the refuting change
in the log.

3. DEVELOPMENT-PLAN.md read as a plan, and its numbers had rotted

It said "Every phase is complete. 24/24 test groups, 96/96 assertions", referenced
tools/traceos.py and schema/, and counted 22 invariants. All four have changed.

It is now labelled history, not a plan, with a note saying why it is deliberately not
updated: a design record rewritten to match today's code stops being evidence of what was
decided and becomes a second, worse copy of the code — which is INV-001 applied to the
document about INV-001. The v0.1 numbers stay, marked as v0.1's.

4. Smaller

docs/decisions/README.md said "14/14 ACCEPTED" and stopped at ADR-014; ADR-015 is listed
with its half-accepted status. README layout counts corrected (28 invariants, 15 ADRs,
13/9/16 test groups) and DIRECTION.md added to the layout. The spec's Non-goals no longer
says "TraceOS v0.1 is not an IDE" now that v0.1 is not the current version.

Checks

39/39 groups, 185/185 assertions, check_docs 28/28 with the stricter rule,
check_locators 38/38, ratchet exit 0 — discharged by re-reading check_docs.py, which
is what raised the finding in the first place.

@junixlabs
junixlabs merged commit f26f2ce into main Sep 11, 2026
9 checks passed
@junixlabs
junixlabs deleted the docs-catch-up branch September 11, 2026 18:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant