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 ```sh 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: ```sh 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: ```sh 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: ```sh 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: ```sh 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: ```sh 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. ```sh 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`: ```sh 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.