0 Fork 0

Files

T

Frank 8af40c402b chore(agent): commit the machine tier and the doctrine text the checkout was already running

Landing blocker for #61 and #63: the deployment checkout is 12 commits behind and
`merge --ff-only` refuses while tracked paths are dirty. Discard is not available here
(workspace policy: no `checkout`/`stash` on shared state), so the dirt is committed.

- `agent/APPEND_SYSTEM.md`: the point-of-use / one-work-log / PR-link doctrine, already
  byte-identical to `origin/main` (`cmp` against the trunk blob: no difference). No new
  prose — the commit exists so the trunk merge can proceed.
- `agent/config.yml` and `agent/managed-skills/**`: the machine-live tier the heartbeat
  owns (AGENTS.md § Live-sync tiers).

`ALLOW_SECRETS=1` was used, deliberately and after auditing the staged diff by hand: the
only credential-shaped strings in it are two copies of `AKIA0000000000000EXAMPLE` — the
inert all-zero AWS example id — and they appear inside the two skill pages that teach
that exact placeholder shape. This checkout is still running the pre-#61 hook; the merged
gate (value-scoped placeholder filter, `71601f7`) exempts this value, so the refusal
dies with this landing. No `--no-verify` was used: the gate ran and its verdict is
recorded here.

Refs #61

2026-10-21 01:44:51 -07:00

4.5 KiB

Raw Blame History

name, description

name	description
single-work-log-bundle-rule	A bundle keeps ONE work log — the entry law, the one-file rule, and the kb-lint gate that fails a second log.md. Use before writing any log entry or creating log.md/NOTES.md/PROGRESS.md/worklog anywhere.

A bundle keeps ONE work log. Before writing any log entry, or creating any file named log.md / NOTES.md / PROGRESS.md / STATUS.md / worklog/, use this: the entry law, the one-file rule, and the kb-lint.sh gate that fails a second log. Law earned 2026-10-20 on dank/command-center PR #57, after an agent had once kept logs in fifty-odd files and none of them was the place to look.

One work log per bundle

The rule

One file, at the bundle root. In dank/command-center that is omp-docs/log.md. In another repo, the change-log page its docs index names. A subdirectory NEVER keeps its own log, and no run/branch/feature gets a private one.
Write it in the same commit as the change it describes; read it before starting to recover where things stand.
Entry = what changed + the durable lesson, a few lines. No per-file inventories, no run-by-run numbers, no transcripts, no re-expanding an old entry in place — git log --follow <log> is the transcript.
No log page in the KB? Add one at its root and list it in the index. That is the fix — never a log somewhere else.
Measured numbers in a log still have to pass the purpose test (agent/APPEND_SYSTEM.md § 1): a figure for a model/runtime/hardware config that is neither deployed nor being compared is dead weight — delete it, do not archive it.

The gate

scripts/kb-lint.sh reports any log.md that is not the bundle root's:

a bundle has one work log, log.md, at the bundle root; found: core/log.md, log.md

scripts/kb-coverage.py enforces the other half of "one place to look": every directory has an index.md and that index links its siblings. Both gates skip any path containing .AGENTTRASH — quarantined pages are not bundle content, and a gate that only goes green once the quarantined copy is deleted is a gate that deletes history.

Run both before committing a docs change:

bash scripts/kb-lint.sh omp-docs && python3 scripts/kb-coverage.py omp-docs

Folding a second log in (the procedure)

Prove it is redundant, don't assert it. Read the candidate: its entries are usually migration bookkeeping (file moved, directory created, log created) — every one recoverable from git log, so it carries no fact git lacks.
Check whether the copies disagree. The two logs in command-center gave the same OKF conversion two different dates (2026-07-15 vs 2026-01-15) while git dated the rebuild 2026-08-28: duplicated logs do not preserve facts, they multiply errors.
Fix what pointed at it. The stale page stays in circulation because an index links it — repoint core/index.md (or whichever index) at the root log in the same change.
Quarantine, never rm: mkdir -p <dir>/.AGENTTRASH && mv <dir>/log.md <dir>/.AGENTTRASH/log.md, then git add -A <dir> so git records the deletion while the copy waits for a pruning session with Frank.
Write the entry in the surviving log, law-first: what changed, then the durable lesson, then links to the spec pages now carrying the law.

Traps

The spec called log.md a reserved name and maintenance said every bundle "has one" — which reads as "any directory may have one". Reserved ≠ replicable; say exactly one, at the root wherever the spec is stated, or the sprawl regrows from the spec itself.
An OKF maintenance page teaching "one line per change with file path" (exampled as /docs/ghostty.md — Updated keybind table) produces manifests that duplicate git and absolute links the linter cannot resolve. Replace the instruction; do not add a second, conflicting one beside it.
Trashing a page turns gates red if they walk .AGENTTRASH/ (frontmatter demanded of a quarantined page, an index demanded for the trash dir). Fix the gates; never delete the quarantined copy to go green.
Deleting the log file in a worktree does not preserve it: a copy moved into a gitignored .AGENTTRASH/ inside a worktree is destroyed when the worktree is removed. Copy it to the deployment (or ~/.AGENTTRASH/) before pruning.
Verify the rule is actually live in a fresh session — a subagent reading ~/.omp/agent/APPEND_SYSTEM.md and quoting the law back proves the deployment, which the current session cannot do for itself (its prompt was built before the change).

4.5 KiB Raw Blame History