Skip to content

v0.1.8

Choose a tag to compare

View all tags
@github-actions github-actions released this 21 Aug 13:41
· 42 commits to dev since this release
v0.1.8
b57f433

Action required

Run specflow upgrade in every repo that has specflow installed, and update the binary. This
release changes both the procedures and the CLI: specflow finish takes a new flag, and next /
verify print a new line.

curl -fsSL https://raw.githubusercontent.com/MatanKoby/specflow/main/install.sh | sh
specflow upgrade
specflow status     # `stale` should read `none` afterwards

Why

Pruning bounded the ledgers by count — CLAIMS.md to its 5 newest completed entries,
BUILD_QUEUE.md to zero completed batches. Both rules work. Neither bounds the size of a single
entry, or the prose that is not an entry at all. An install running at its prescribed retention of 5
still carried a 27 KB CLAIMS.md, and both ledgers are re-read on every claim, finish, and prune.

What it changes on disk

Four managed files are refreshed. Nothing you own is touched: spec/, BUILD_QUEUE.md, CLAIMS.md,
and your own text outside specflow's markers are unaffected, and upgrade still never commits.

Path Change
specflow/procedures/finish-batch.md steps 3 and 4 rewritten: stub in CLAIMS.md, narrative in the archive
specflow/procedures/prune-ledgers.md new section 3: audit the BUILD_QUEUE.md preamble
.claude/skills/finish-batch/SKILL.md trigger text follows the new split
.claude/skills/prune-ledgers/SKILL.md trigger text names the preamble audit and the weight warning

A managed file you have edited yourself is still left alone, with its new version written to
<file>.specflow-new.

The narrative is written once

Finishing a batch used to ask for prose about that batch twice: the "What shipped" summary in
CLAIMS.md and the paragraph in specflow/history/BUILD_QUEUE_DONE.md. They were authored
independently, and neither was a superset of the other — so the batch's story ended up split across a
hot file and an archive, with the hot copy carrying most of it.

Now CLAIMS.md keeps a stub: the metadata fields, at most 8 lines of "What shipped", and a
pointer. The full narrative goes to BUILD_QUEUE_DONE.md, which nothing reads on the hot path.
A resuming agent gets enough to know whether it needs to read further; the unabridged record is one
file away.

specflow finish <N> --commit <sha> --stub-file <path> --done-file <path>

--stub-file is the new name for --summary-file, which still works. An over-length stub is
refused before anything is written, so the fix is to move prose into the done-file and retry
against an untouched repo. It is a hard reject, not a stop-and-ask: unlike splitting a spec file,
moving a paragraph into the archive loses nothing, so there is no judgment to put to the user. Blank
lines and the pointer line don't count against the cap.

The queue preamble is capped

Everything above the first ## Batch heading in BUILD_QUEUE.md is not an entry, so no retention
rule ever reached it. That preamble is where an agent parks a durable fact when it cannot decide
which spec/ file owns it: at finish time the queue is already open, writing there is one edit, and
nothing ever prunes it. It fills.

The preamble is now capped at 45 lines (the shipped template is 33), using the same
specflow:size-ok waiver as the 600-line spec cap and re-asking every +15. prune-ledgers section 3
audits the paragraphs into delete / relocate via spec-edit / keep. That section does
stop and ask, unlike the rest of pruning, because deciding which spec file should own a stranded
paragraph is a judgment call about concerns.

next and verify report ledger weight

ledger weight: BUILD_QUEUE.md 119 lines (preamble 28/45) · CLAIMS.md 228 lines (5 completed)

Printed every time, with a warning past a bound — more completed entries than the retention of 5, or
a preamble over its cap (honoring a waiver). specflow next --json carries the same numbers under
weight. This is reporting, not a second retention rule: the cut stays a count, for the
determinism reasons in spec/architecture.md → Ledger lifecycle. What a count cannot reveal is a
file that grew heavy while staying correct.

Behavior changes

  • specflow finish gains --stub-file and refuses a stub over 8 prose lines (exit 1, nothing
    written). --summary-file keeps working as the old name.
  • specflow next and specflow verify print a ledger weight line; verify skips it for
    --spec-only installs, and it never changes verify's verdict.
  • specflow next --json gains a weight object.

Install

curl -fsSL https://raw.githubusercontent.com/MatanKoby/specflow/main/install.sh | sh
# or
go install github.com/MatanKoby/specflow/cmd/specflow@v0.1.8

Full diff: v0.1.7...v0.1.8

Assets 8
Loading