novusedge/docket/docket-feature

docket-feature

The feature store tracks work in flight: what a piece of work intends, the paths it declares, and what it actually changed. It never writes to the ledger. Use the absolute command path supplied by the session context. The examples use docket for readability.

When to start a feature

Start one before a change touches its third file, and before any work that spans more than one session, crosses a module boundary, or another agent might pick up later. Finishing within this turn is not a reason to skip it: done reports which changed files fell outside the declared paths and asks about the claims the change touched, and that check is worth as much on a short change as on a long one. Skip it only for a change confined to one or two files.

The edit hook says so when a session reaches its third edited file with no feature open. Start the feature then, declaring the paths the rest of the change will touch. Uncommitted edits made before start still count toward done once they are committed.

The session briefing opens with a # feature: none open line when the working tree carries uncommitted changes and no feature is open. Those changes came from an earlier session. Start a feature for them before editing further; commit a leftover edit instead if it is already finished.

Starting work

docket feature start opencode-discovery \
  --text "Installer places the OpenCode plugin where discovery finds it" \
  --path installer/**

A declared path needs a / or a glob character. --path installer or --path Makefile matches nothing and start refuses both.

Resuming work

Run docket feature brief first, before anything else, when picking up a feature already started:

docket feature brief opencode-discovery

The brief derives which ledger records govern the feature from its declared paths and prints each one with three numbers:

• strength is the same scope score docket context ranks records by.
• specificity is the length of the matching glob's literal prefix; a record

scoped to one file outranks one scoped to a directory glob even at equal strength.

• matches is how many of the feature's files that glob covers.

A rank you disagree with is visible on the line that produced it. Correct it with amend:

docket feature amend opencode-discovery --exclude d81
docket feature amend opencode-discovery --include q75

Each flag replaces the whole list. To drop an override rather than change it, clear the list by name:

docket feature amend opencode-discovery --clear exclude

Status and blocked

docket feature list and docket feature show report blocked when an attached decision derives as blocked, the same prerequisite relation docket context computes for every decision. An open question in the feature's scope does not block it on its own; scope overlap alone would fire on nearly every feature. Work stalled on a question is declared paused by hand:

docket feature amend opencode-discovery --status paused

After a ledger merge

A ledger merge can renumber the records a feature cites in --include or --exclude. The feature store keeps a key for each cited record, so the brief follows a renumbered record to its new ID, and docket check reports each ID that moved. Repoint the stored lists with:

docket feature remap

remap needs no argument: it follows those keys. Pass the map file from docket rebase --emit-map PATH to repoint through that map instead. features.jsonl merges through the same git merge driver as the ledger; docket init registers it.

Closing work

Run done before squashing or rebasing the branch. Once the fork point is no longer an ancestor of HEAD, done refuses and names the stale SHA.

docket feature done opencode-discovery

done prints two change-set lists: paths the branch changed that the feature declared, and paths it changed outside them. A file outside the declared paths is not an error, it is a fact to notice before merging.

The claim prompt at done

done asks only about claims whose scope intersects the paths the branch actually changed; a claim about code the work never touched gained no new evidence. Mark verdicts with --held and --failed:

docket feature done opencode-discovery --held c12 --failed c9

For each --failed claim, done prints the docket claim ... --supersedes command that would record the correction, then stops. Docket never writes that record. Run the printed command yourself.