feat: read and edit a plan or spec by address, not by the whole file

[protonspy]

An agent answering "what is the next open task?" reads the whole file to find out. Measured on a real workspace: one plan is 56KB / ~14k tokens, and its 31 specs bring the corpus to ~90k tokens. That cost is paid on every request rather than once, because a token read is paid 1× on entry and 0.1× on every subsequent request of the session.

This adds a read surface and a write surface that address an artifact by name.

scc map — read

index | outline | tasks | show | blocks | find | trace

	tokens
the plan	~14,350
scc map <plan>	~220
scc map blocks <plan> notes	~1,295
scc map show <plan> notes:10	~128

scc patch — write

check | uncheck | task | add | rm | append | prepend | replace | fm

It exists for a policy rather than a cost: a harness makes a tool read a file before it may edit it. That guard is right for a text editor and wrong for a structured artifact, so it is replaced by three that are stronger here — an address that does not resolve is an error and never an insert at a guess; the file is re-validated and the change rolled back if it introduced a finding (exit 2, file untouched); and the changed lines are printed back.

A change deleting more than a screenful stops and asks for --force, with the displaced region elided — a confirmation that echoed 400 lines would put the file in context by the back door while reporting that it refused to touch it.

Addresses

None is a line number, which is what lets a write survive an edit above it:

1.2          a task           #notes     a section, by anchor slug
R1.2         a requirement    notes:7    the 7th paragraph of that section
specs/foo/   a leaf           L120-160   an explicit range, the escape hatch

Two things measurement decided

blocks exists because section addressing bottoms out. That plan's ## Notes is 411 lines — half the file — with no headings inside it, but every paragraph opens with a bolded thesis. The leads alone are an index a twentieth of the size.

No search engine. At 352KB / 94 artifacts a linear BM25 pass ranks the whole workspace in 55ms. Tantivy or its kin would cost a CGO surface or a second binary against a stdlib-only go.mod and a six-platform cross-compile. What precision needed was a better unit — addressable regions rather than lines, so a hit comes back as something show accepts. The seam is artifact.Search.

One grammar, two consumers

The task grammar moves into internal/artifact and internal/validate consumes it. A reader that disagreed with the validator about what a task is would be worse than no reader. The parser states facts about a line; turning a fact into a finding stays in validate — which is also what lets map open a malformed artifact instead of refusing exactly the file a user most needs to inspect.

Also

• artifacts.md, a new rule inside the 55-line preload budget; code-search.md points at it, closing the gap it already named.
• plan-run stops re-reading the plan to find its place — it maps it, and ticks boxes with patch check.
• The entry file's layout block is now one column across all three harnesses, with the padding computed from the profile: a run of spaces that lines up for .codex/ is ragged for .opencode/. TestEntryLayoutBlockIsAligned is what keeps the hand-written and derived halves agreeing.
• assets.Version → 12.

Verification

gofmt · go vet · full suite green. The race detector could not run locally (no gcc on this Windows box) — CI covers it on Linux and macOS.

Behaviour proven against the real 94-artifact corpus: check/uncheck round-trips the 56KB plan byte-identically, an edit that introduces plan.item-has-two-records is rolled back with the file intact, and 28 pre-existing findings do not block an unrelated edit.

🤖 Generated with Claude Code

https://claude.ai/code/session_019YLNd5uRpQDQ8ffvEvLJ3q