Skip to content

Document driftlock as a finished project - #54

Merged
hyj28 merged 1 commit into
mainfrom
docs-for-release
Sep 14, 2026
Merged

hyj28 merged 1 commit into
mainfrom
docs-for-release

Conversation

@hyj28

@hyj28 hyj28 commented Sep 14, 2026

Copy link
Copy Markdown
Owner

The README had grown into a 610-line thesis with the quick start at line 220, a "Planned deliverables" section, and a subsystem labelled being replaced that had in fact shipped. PLAN.md announced itself as the working plan and was last revised before fifty-one of the commits it was meant to describe. Neither read as a project anyone could pick up.

Two corrections that matter more than the reorganisation

The Terminus-2 adapter was documented as legacy awaiting deletion. It is the opposite. All 287 archived job configs used driftlock.harbor_agent:LHTBDriftlockAgent, so it is the path the published results came from, and the reason that run stays replayable.

RESULTS.md never said which agent produced its numbers. A reader would reasonably have assumed driftlock's own tool-calling agent. It now names the agent under test in the run table, and states that the native agent and the components built on it have no published measurement yet. The claim the report actually supports — about the checkpoint, scoring, localization, distillation and paired-validation machinery — is unaffected.

Changes

README.md 610 → 171 lines: what it is, whether it works, how to run it, then links out
docs/usage.md the long operational material, moved unchanged
docs/architecture.md new — the one invariant each component exists to hold
docs/design-journal.md PLAN.md, frozen and dated, with its two measurement-retired decisions called out
CONTRIBUTING.md new — the discipline actually used, not an invented contributor workflow
CHANGELOG.md new — grouped by the four phases the history actually has
.github/workflows/ci.yml new — a repository with 1260 tests should not have been missing this
pyproject.toml description from the middleware era; claimed 3.11 while the code targets 3.13; classifiers and URLs added

docs/architecture.md is the one worth reading: most of that reasoning previously existed only in commit messages.

Gates

pytest 1260 passed, 3 skipped. ruff check . and ruff format --check . exit 0. Every internal documentation link resolves, and no reference to the retired filename remains — including one in skill_retrieval.py that cited it by section number.

The README had grown into a 610-line thesis with the quick start at line 220, a
"Planned deliverables" section, and a subsystem marked "being replaced" that had
in fact shipped. PLAN.md announced itself as the working plan and was last revised
before fifty-one of the commits it was supposed to describe. Neither read as a
project anyone could pick up.

The README is now 171 lines that answer what this is, whether it works, and how to
run it, and then link out. The long operational material moved to docs/usage.md
unchanged.

Two corrections matter more than the reorganisation.

The Terminus-2 adapter was documented as legacy awaiting deletion. It is the
opposite: all 287 archived job configs used
driftlock.harbor_agent:LHTBDriftlockAgent, so it is the path the published results
came from and the reason that run stays replayable. RESULTS.md never said which
agent produced its numbers, and a reader would reasonably have assumed driftlock's
own. It says so now, along with the fact that the native agent and everything built
on it have no published measurement yet. The claim the report actually supports is
about the checkpoint, scoring, localization, distillation and validation machinery -
which is what was measured - and that claim is unaffected.

PLAN.md becomes docs/design-journal.md, frozen and dated, kept because two of its
decisions were retired by measurement rather than argument and the reasoning is
worth preserving next to the outcome.

New: docs/architecture.md, which states the one invariant each component exists to
hold - most of that reasoning previously existed only in commit messages.
CONTRIBUTING.md, which writes down the discipline rather than inventing a
contributor workflow: the four gates, what counts as weakening a suite, what a new
component must prove, and why a runtime driver that has not seen the diff and a
reviewer who reads the code find different things. CHANGELOG.md, grouped by the
four phases the history actually has. A CI workflow, which a repository with 1260
tests should not have been missing.

pyproject carried a description from when this was middleware and claimed Python
3.11 while the code targets 3.13; both fixed, with classifiers and project URLs
added. One code comment pointed at PLAN.md by section number.

Gates: pytest 1260 passed / 3 skipped, ruff check and ruff format --check clean,
every internal documentation link resolves, no reference to the retired filename
remains.
@hyj28
hyj28 merged commit 817b96d into main Sep 14, 2026
1 check failed
@hyj28
hyj28 deleted the docs-for-release branch September 14, 2026 05:39
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