@4-r-c-4-n-4/todo 0.1.6 → 0.2.0

package/BIBLE.md

@@ -148,13 +148,32 @@ For `main`, enable:
 
 - **Require a pull request before merging** — the agent stops at the PR; you click Merge.
 - **Require status checks to pass** — your CI's `Lint, typecheck, test` job. Catches the kind of regression that this session's commit `b6709ed` (missing `pretest` hook) would have stopped on red.
-- **Require linear history** — enforces the skill's `--no-ff` rule. Squash merges would orphan the resolution-commit SHAs stored in `.todo/done/<id>.json`.
+- **Require linear history** — enforces the skill's `--no-ff` rule for *deliverable* commits, keeping the resolution-commit SHAs stored in `.todo/done/<id>.json` resolvable. (The `.todo/`-only state commits carry no such reference and are safe to squash or batch.)
 - **Require approvals (optional)** — even for a solo repo, setting "1 approval" forces you to actually open the PR and skim the diff before clicking through. Cheap insurance against autopilot merges.
 
 Once protected, the closing step becomes `todo pr` (push branch + open PR + stop) instead of a local merge. The local-merge sequence in the previous sections remains valid for unprotected repos or quick solo work.
 
 ---
 
+## Configuration
+
+Settings live in `.todo/config.json` (created by `todo init`). The keys that shape the git workflow:
+
+| Key | Values | Default | Effect |
+|-----|--------|---------|--------|
+| `behavior.commit_prefix` | string | `todo:` | Prefix that ties commits to tickets |
+| `behavior.branch_mode` | `per-ticket` \| `managed` | `per-ticket` | `per-ticket`: todo manages a `todo/<id>` branch and runs the branch guards. `managed`: **you** (or a PR flow) own branching — `todo work` does no git ops and `todo close` drops the branch guards and auto-records state |
+| `behavior.guard_mode` | `advisory` \| `strict` | `advisory` | `advisory`: a failed branch/commit-prefix guard warns and proceeds. `strict`: it's a hard error (exit 1) — opt in when you want git to enforce the conventions |
+
+**Pick a profile:**
+- **PR-based / protected `main`** → `branch_mode: "managed"`. todo becomes a pure state-and-rationale tracker and leaves git entirely to you.
+- **Agent-driven, todo owns the branches** → `branch_mode: "per-ticket"` + `guard_mode: "strict"` (this repo's own setting) to make the conventions enforced rather than suggested.
+- **Default** (`per-ticket` + `advisory`) suits solo/local work: the structure is there, but a guard never blocks you.
+
+`todo doctor` reconciles committed `.todo/` state against git reality (missing/unreachable resolution commits, done-parents with open children, active tickets whose branch is gone, misfiled tickets, dangling references). Run it in CI — it exits non-zero on errors (`--strict` also fails on warnings).
+
+---
+
 ## Ticket Types
 
 | Type | When to use |
@@ -164,6 +183,7 @@ Once protected, the closing step becomes `todo pr` (push branch + open PR + stop
 | `refactor` | Code change with no behavior change |
 | `chore` | Tooling, config, dependency updates, cleanup |
 | `debt` | Known-bad code that needs to be addressed later |
+| `investigation` | A question to answer or decision to make; the deliverable is a documented conclusion, not code |
 
 ---
 
@@ -178,9 +198,12 @@ What's required before closing each ticket type:
 | `refactor` | Commit SHA, tests still passing |
 | `chore` | Commit SHA |
 | `debt` | Commit SHA, note explaining what changed |
+| `investigation` | A resolution **note** (the conclusion); commit optional, no test required |
 
 Close command: `todo close <id> --note "what you did" --test tests/foo.ts::test_name`
 
+`todo close --commit-state` records the `.todo/` state change in the same step, so a failed close can never be followed by a stray "close" commit. It's the recommended way to close.
+
 ---
 
 ## Commit Message Convention
@@ -203,9 +226,9 @@ The `<id>` is the full 8-char ticket ID. Always include it. This ties commits to
 
 1. **Closing before committing** — `todo close` captures HEAD. If you haven't committed the fix, the resolution commit is wrong. Always commit code first.
 
-2. **Forgetting `git add .todo/`** — Ticket files live in `.todo/`. They must be committed. After any `todo` command that writes, stage `.todo/`.
+2. **Forgetting `git add .todo/`** — Ticket files live in `.todo/`. They must be committed. After any `todo` command that writes, stage `.todo/`. (`todo close --commit-state` does this for you atomically — see Workflow — which is the recommended way to avoid this footgun entirely.)
 
-3. **Squash merging breaks commit refs** — Tickets store resolution commits. Squash merging replaces them with a new SHA. The linked commit disappears. Use `--no-ff` merges or update the resolution commit after squash.
+3. **Squash merging can break commit refs** — A ticket's `resolution.commit` points at a real *code* commit. Squash-merging that commit replaces its SHA and orphans the reference, so never squash the deliverable commits — use `--no-ff` (or update the resolution commit after a squash). This does **not** apply to the `.todo/`-only state commits (`todo:<id> — close`, plan commits): nothing points at them — the resolution SHA lives *inside* the ticket file, not in `.todo/` history — so they may be squashed or batched (e.g. one `.todo/` commit per PR) to keep mainline history clean.
 
 4. **Using a short prefix when IDs are ambiguous** — If two tickets share a prefix, commands fail. Use more characters of the ID.
 

package/README.md

@@ -1,4 +1,207 @@
 # todo
-Making working on work work
 
-https://www.npmjs.com/package/@4-r-c-4-n-4/todo
+**Git-native work tracking for coding agents.**
+
+[![npm](https://img.shields.io/npm/v/@4-r-c-4-n-4/todo)](https://www.npmjs.com/package/@4-r-c-4-n-4/todo)
+
+`todo` is a ticket tracker that lives *inside* your repository. Tickets are JSON files committed alongside your code in `.todo/`, so work state travels with the branch, survives clones, and is reviewable in a diff. It's designed so a coding agent can run the whole loop — capture a problem, attach reasoning, do the work, and close with proof — but it's just as usable by hand.
+
+Two things make it more than a TODO list:
+
+- **A rationale trail.** `todo analyze` attaches structured reasoning (blame → hypothesis → evidence → conclusion) to a ticket, turning it into a lightweight ADR that's there when you reopen the work months later.
+- **A done contract.** A ticket can't close without proof — a resolution commit, and (for bugs) a test reference. Closes are self-documenting by construction.
+
+---
+
+## Install
+
+```bash
+npm install -g @4-r-c-4-n-4/todo
+```
+
+Requires **Node ≥ 20** and a **git repository**. Then, from the repo root:
+
+```bash
+todo init          # creates .todo/ and a config file
+git add .todo && git commit -m "chore: init todo"
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Capture a problem
+id=$(todo new "Login throws on empty password" --type bug --source human)
+
+# 2. Start work (creates branch todo/<id>, marks the ticket active)
+todo work "$id"
+
+# 3. ...write the fix and a test, then commit with the ticket prefix
+git commit -am "todo:$id — guard against empty password"
+
+# 4. Close with proof, recording the .todo/ state in the same step
+todo close "$id" \
+  --test tests/auth.test.ts::rejects_empty_password \
+  --note "Restored the null guard dropped in 3f9a1c2" \
+  --commit-state
+```
+
+That's the standalone-ticket loop. For multi-step features, see **Feature builds** below.
+
+---
+
+## Core concepts
+
+**Tickets** are JSON files under `.todo/open/` (live) and `.todo/done/` (terminal). Each has a stable 8-char id, a type, a state, a summary, and optional analysis, relationships, and resolution.
+
+**States:** `open` → `active` → `done` (plus `blocked`, and the terminal `wontfix` / `duplicate`).
+
+**Types and what it takes to close each (the done contract):**
+
+| Type | Required to close |
+|------|-------------------|
+| `bug` | Commit + test file **and** function |
+| `feature` | Commit + a test *or* a note |
+| `refactor` | Commit |
+| `chore` | Commit |
+| `debt` | Commit (note recommended) |
+| `investigation` | A **note** (the documented conclusion) — commit optional, no test needed |
+| *parent* | A note, and every child in a terminal state |
+
+`investigation` exists for work whose deliverable is a *decision*, not code — a benchmark, a design call, a "where should this live?" question. It closes on the conclusion.
+
+---
+
+## Two workflow modes
+
+`todo` does not force a branching workflow on you. Pick the one that matches your repo with `behavior.branch_mode`:
+
+### `per-ticket` (default) — todo manages branches
+
+`todo work <id>` creates `todo/<id>` (children share the parent's branch); you merge it back with `--no-ff` when done. Branch-convention guards run on `close`. Best for agent-driven repos where todo owns the git choreography.
+
+```bash
+todo work <id>
+git commit -am "todo:<id> — ..."
+todo close <id> --note "..." --commit-state
+git checkout main && git merge --no-ff todo/<id> && git branch -d todo/<id>
+```
+
+### `managed` — you own branches (PRs, protected `main`)
+
+`todo work` performs **no git operations**, and `close` drops the branch guards and records state automatically. `todo` becomes a pure state-and-rationale tracker and leaves git entirely to you and your PR flow.
+
+```jsonc
+// .todo/config.json
+{ "behavior": { "branch_mode": "managed" } }
+```
+
+```bash
+git checkout -b feature/login-fix   # your branch, your rules
+todo work <id>                       # just marks the ticket active
+# ...commit however you like...
+todo close <id> --note "..."         # no branch guard; state auto-committed
+```
+
+### Strict vs. advisory guards
+
+In `per-ticket` mode, the branch-convention checks (are you on the right branch? does a commit reference this ticket?) are **advisory by default** — they warn and proceed. Set `behavior.guard_mode: "strict"` to make them hard errors (exit 1) when you want git to enforce the conventions. The real done contract (commit exists, test/note present) is always enforced.
+
+---
+
+## Feature builds (parent + children)
+
+Decompose a feature into an ordered parent + children. Children share the parent's branch and are worked in sequence.
+
+```bash
+parent=$(todo new "OAuth2 login" --type feature --source agent)
+c1=$(todo new "Add /auth/callback route" --type chore --parent "$parent")
+c2=$(todo new "Validate session middleware" --type chore --parent "$parent")
+
+todo work "$c1"   # creates todo/<parent>
+# ...implement, commit, close $c1 --commit-state...
+todo next "$parent"   # activates the next open child on the same branch
+# ...repeat...
+todo close "$parent" --note "All subtasks shipped" --commit-state
+```
+
+---
+
+## Command reference
+
+| Command | What it does |
+|---------|--------------|
+| `todo init` | Initialize `.todo/` in the current git repo |
+| `todo new [summary]` | Create a ticket (`--type`, `--source`, `--parent`, `--tags`, `--file`, `--pipe`) |
+| `todo list` | List tickets (`--state`, `--type`, `--tag`, `--file`, `--sort`, `--json`) |
+| `todo show <id>` | Show ticket detail (`--raw` for JSON) |
+| `todo edit <id>` | Edit fields (`--summary`, `--type`, `--tags`, `--parent`, …) |
+| `todo work <id>` | Start/resume work (`--skip-branch`, `--branch`, `--actor`) |
+| `todo next <parent>` | Activate the next open child on the current branch |
+| `todo analyze <id>` | Append a reasoning entry (`--type`, `--content`, `--confidence`) |
+| `todo transition <id> <state>` | Move a ticket to any state |
+| `todo close <id>` | Close as done (`--commit`, `--test`, `--note`, `--commit-state`, `--force`) |
+| `todo link <id> --to <target>` | Link to a commit, file, or ticket (`--relation`) |
+| `todo scan` | Create tickets from `TODO`/`FIXME`/… comments in the tree |
+| `todo dedup` | Find potential duplicate tickets |
+| `todo doctor` | Reconcile `.todo/` against git reality and report drift |
+| `todo export` | Dump tickets to stdout as JSON |
+| `todo pr` | Push the `todo/<id>` branch and open/update a GitHub PR |
+| `todo sync` | Push ticket state to a Hermes Kanban board |
+| `todo install-hooks` | Install git hooks that enforce the conventions |
+
+Run `todo <command> --help` for full options.
+
+---
+
+## Configuration
+
+Settings live in `.todo/config.json` (created by `todo init`). The keys that shape the workflow:
+
+| Key | Values | Default | Effect |
+|-----|--------|---------|--------|
+| `behavior.commit_prefix` | string | `todo:` | Prefix that ties commits to tickets |
+| `behavior.branch_mode` | `per-ticket` \| `managed` | `per-ticket` | Whether todo manages branches or leaves git to you (see above) |
+| `behavior.guard_mode` | `advisory` \| `strict` | `advisory` | Whether failed branch guards warn or hard-fail |
+| `intake.scan_patterns` | string[] | `TODO, FIXME, HACK, XXX` | Comment markers `todo scan` picks up |
+| `intake.dedup_strategy` | `fingerprint` \| `file-line` \| `semantic` | `fingerprint` | How duplicates are detected |
+| `display.id_length` | number | `8` | Characters of the id shown in lists |
+| `display.date_format` | `relative` \| `iso` | `relative` | Date rendering |
+
+**Profiles at a glance:**
+- **PR-based / protected `main`** → `branch_mode: "managed"`.
+- **Agent-driven, todo owns branches** → `branch_mode: "per-ticket"` + `guard_mode: "strict"`.
+- **Solo / local** → the defaults: structure is there, but a guard never blocks you.
+
+---
+
+## `todo doctor`
+
+Because state lives in git and is edited by agents, the `.todo/` store can drift from reality. `todo doctor` reconciles them and reports:
+
+- done tickets whose resolution commit is missing (orphaned by a squash/rebase) or unreachable from `HEAD`
+- done parents with a still-open child
+- active tickets whose branch was deleted
+- tickets misfiled in the wrong directory for their state
+- dangling parent/child/dependency references
+
+It exits non-zero on errors (and on warnings too with `--strict`), so it drops straight into CI. `--json` for machine output.
+
+---
+
+## For coding agents
+
+`todo` ships a set of **skills** (under `skills/`) that drive the lifecycle end-to-end: `todo-capture` (intake any signal into a ticket), `todo-triage` (classify raw captures), `todo-plan` (decompose a feature), and `todo-implement` (write the code and close with proof). They encode the conventions so an agent follows them reliably.
+
+`TODO_ACTOR` sets the identity recorded on transitions when git's `user.name` isn't the right attribution.
+
+---
+
+## Learn more
+
+[**BIBLE.md**](./BIBLE.md) is the full doctrine — the lifecycle, the branch workflow, branch-protection setup, and the reasoning behind the done contract.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/branch-guard.js

@@ -1,9 +1,14 @@
 "use strict";
 // Branch-convention guards used by `todo close` and `todo work`.
 //
-// These turn the conventions documented in the todo-implement skill into
-// hard preconditions: agents follow exit codes far more reliably than
-// prose, so every drift gets a clear, actionable error.
+// These encode the conventions documented in the todo-implement skill. They
+// are *advisory by default* — the caller warns and proceeds — because a
+// standalone tool should not litigate a branching workflow its user did not
+// choose. A project that wants git to enforce the conventions opts in with
+// behavior.guard_mode = "strict", which turns these into hard preconditions
+// (agents follow exit codes far more reliably than prose). managed branch_mode
+// skips them entirely. Each function therefore just *reports* a check result;
+// the severity decision lives in the command.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.expectedBranchFor = expectedBranchFor;
 exports.checkOnExpectedBranch = checkOnExpectedBranch;
@@ -39,9 +44,7 @@ function checkBranchHasTodoCommit(ticket, repoRoot, commitPrefix) {
         return { ok: true };
     return {
         ok: false,
-        message: `Refusing to close ${ticket.id}: no commit since ${base} has message containing '${needle}'.\n` +
-            `  Either amend a commit to include the prefix, or pass --force ` +
-            `if this ticket genuinely has no code change attached.`,
+        message: `no commit since ${base} has a message containing '${needle}'.`,
     };
 }
 /**

package/dist/cli.js

@@ -7,6 +7,7 @@ const commander_1 = require("commander");
 const analyze_js_1 = require("./commands/analyze.js");
 const close_js_1 = require("./commands/close.js");
 const dedup_js_1 = require("./commands/dedup.js");
+const doctor_js_1 = require("./commands/doctor.js");
 const edit_js_1 = require("./commands/edit.js");
 const export_js_1 = require("./commands/export.js");
 const init_js_1 = require("./commands/init.js");
@@ -46,4 +47,5 @@ program
 (0, install_hooks_js_1.registerInstallHooks)(program);
 (0, sync_js_1.registerSync)(program);
 (0, pr_js_1.registerPr)(program);
+(0, doctor_js_1.registerDoctor)(program);
 program.parse(process.argv);

package/dist/commands/close.js

@@ -16,14 +16,31 @@ function registerClose(program) {
         .option("--test <file::func>", "test file and function (colon-separated)")
         .option("--note <text>", "resolution note")
         .option("--checkout", "git checkout base_branch after closing")
+        .option("--commit-state", "atomically git-commit the .todo/ state change (no separate manual commit needed)")
         .option("--force", "skip branch and commit-message guards")
         .action((id, opts) => {
         const ctx = (0, context_js_1.getContext)(true);
         const { repoRoot, config } = ctx;
         try {
             const ticket = (0, ticket_js_1.readTicketByPrefix)(repoRoot, id);
-            // Branch-convention guards (skippable with --force).
-            if (!opts.force) {
+            const managed = (0, config_js_1.getBranchMode)(config) === "managed";
+            const strict = (0, config_js_1.getGuardMode)(config) === "strict";
+            // Branch-convention guards. Skipped entirely in managed mode (the
+            // user owns branching) or with --force. Otherwise they are advisory
+            // by default — warn and proceed — and only hard-fail when the
+            // project opts into behavior.guard_mode = "strict". This keeps the
+            // tool from litigating a workflow you are not using, while still
+            // letting agent-driven repos enforce the conventions.
+            if (!opts.force && !managed) {
+                // Report a guard failure at the configured severity. In strict
+                // mode it exits 1; otherwise it warns and execution continues.
+                const reportGuard = (message) => {
+                    if (strict) {
+                        console.error(`Error: ${message}`);
+                        process.exit(1);
+                    }
+                    console.error(`Warning: ${message} (advisory — proceeding)`);
+                };
                 let currentBranch = "";
                 try {
                     currentBranch = (0, git_js_1.getCurrentBranch)(repoRoot);
@@ -32,22 +49,21 @@ function registerClose(program) {
                     // Detached HEAD or other; treat as a branch mismatch.
                 }
                 const branchCheck = (0, branch_guard_js_1.checkOnExpectedBranch)(ticket, currentBranch);
-                if (!branchCheck.ok) {
-                    console.error(`Error: ${branchCheck.message}`);
-                    process.exit(1);
-                }
-                // Parents with all-terminal children carry no code commit of
-                // their own — skip the commit-prefix check for them. The
-                // branch-match check above still fires.
-                if (!(0, branch_guard_js_1.isParentWithAllChildrenClosed)(ticket, repoRoot)) {
+                if (!branchCheck.ok)
+                    reportGuard(branchCheck.message ?? "");
+                // The commit-prefix grep is a heuristic over commit messages, not
+                // the real done-contract (commit-exists + test/note, enforced in
+                // state.ts). An explicit --commit names the deliverable, so skip
+                // it; a parent with all children closed carries no commit of its
+                // own.
+                if (!opts.commit && !(0, branch_guard_js_1.isParentWithAllChildrenClosed)(ticket, repoRoot)) {
                     const commitCheck = (0, branch_guard_js_1.checkBranchHasTodoCommit)(ticket, repoRoot, (0, config_js_1.getCommitPrefix)(config));
                     if (!commitCheck.ok) {
-                        console.error(`Error: ${commitCheck.message}`);
-                        process.exit(1);
+                        reportGuard(`${commitCheck.message} Pass --commit <sha> to point close at the deliverable`);
                     }
                 }
             }
-            else {
+            else if (opts.force) {
                 console.error("Warning: --force used; skipping branch guards.");
             }
             // Resolve commit
@@ -88,6 +104,23 @@ function registerClose(program) {
             }
             (0, ticket_js_1.writeTicket)(repoRoot, updated);
             console.log(`Closed ${updated.id}`);
+            // Atomically record the state change. This only runs once the
+            // close has already succeeded on disk, so the "close" commit can
+            // never describe a ticket that did not actually close — the
+            // phantom-commit hazard of a manual `git commit` after a failed
+            // close. Runs before --checkout so the commit lands on the ticket
+            // branch before switching away.
+            if (opts.commitState || managed) {
+                const message = `${(0, config_js_1.getCommitPrefix)(config)}${updated.id} — close`;
+                try {
+                    (0, git_js_1.commitTodoState)(message, repoRoot);
+                    console.log(`Recorded .todo/ state: ${message}`);
+                }
+                catch (err) {
+                    console.error(`Warning: closed ${updated.id} but could not commit .todo/ state: ${err.message}\n` +
+                        "  Commit it manually: git add -A .todo && git commit");
+                }
+            }
             // Checkout base branch if requested
             if (opts.checkout) {
                 const targetBranch = updated.work?.base_branch ?? (0, git_js_1.getDefaultBranch)(repoRoot);

package/dist/commands/doctor.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+type Severity = "error" | "warning";
+interface Issue {
+    severity: Severity;
+    ticket: string;
+    message: string;
+}
+/**
+ * Reconcile committed .todo/ state against git reality and report drift.
+ * Because state lives in git and is edited by agents, the file can silently
+ * diverge from what actually happened (a done ticket whose resolution commit
+ * was never merged, an active ticket whose branch was deleted, a ticket in
+ * the wrong directory for its state). `doctor` turns that into a report.
+ */
+export declare function collectIssues(repoRoot: string): Issue[];
+export declare function registerDoctor(program: Command): void;
+export {};

package/dist/commands/doctor.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectIssues = collectIssues;
+exports.registerDoctor = registerDoctor;
+const context_js_1 = require("../context.js");
+const errors_js_1 = require("../errors.js");
+const git_js_1 = require("../git.js");
+const ticket_js_1 = require("../ticket.js");
+/**
+ * Reconcile committed .todo/ state against git reality and report drift.
+ * Because state lives in git and is edited by agents, the file can silently
+ * diverge from what actually happened (a done ticket whose resolution commit
+ * was never merged, an active ticket whose branch was deleted, a ticket in
+ * the wrong directory for its state). `doctor` turns that into a report.
+ */
+function collectIssues(repoRoot) {
+    const issues = [];
+    const add = (severity, ticket, message) => issues.push({ severity, ticket, message });
+    const openTickets = (0, ticket_js_1.listTickets)(repoRoot, "open");
+    const doneTickets = (0, ticket_js_1.listTickets)(repoRoot, "done");
+    const all = [...openTickets, ...doneTickets];
+    const byId = new Map(all.map((t) => [t.id, t]));
+    let head;
+    try {
+        head = (0, git_js_1.resolveHEAD)(repoRoot);
+    }
+    catch {
+        head = undefined;
+    }
+    // Directory must agree with state: open/ holds non-terminal, done/ terminal.
+    for (const t of openTickets) {
+        if (ticket_js_1.TERMINAL_STATES.includes(t.state)) {
+            add("error", t.id, `is in .todo/open/ but its state is '${t.state}' (terminal) — file is in the wrong directory`);
+        }
+    }
+    for (const t of doneTickets) {
+        if (!ticket_js_1.TERMINAL_STATES.includes(t.state)) {
+            add("error", t.id, `is in .todo/done/ but its state is '${t.state}' (non-terminal) — file is in the wrong directory`);
+        }
+    }
+    for (const t of all) {
+        // Resolution integrity for done tickets.
+        if (t.state === "done") {
+            const sha = t.resolution?.commit;
+            if (!sha) {
+                add("error", t.id, "is done but records no resolution commit");
+            }
+            else if (!(0, git_js_1.commitExists)(sha, repoRoot)) {
+                add("error", t.id, `resolution commit ${sha} does not exist in the repository (orphaned by a squash/rebase?)`);
+            }
+            else if (head && !(0, git_js_1.isAncestor)(sha, "HEAD", repoRoot)) {
+                add("warning", t.id, `resolution commit ${sha.slice(0, 8)} is not reachable from HEAD (closed on an unmerged branch?)`);
+            }
+        }
+        // A done parent must have no non-terminal children.
+        const children = t.relationships?.children ?? [];
+        if (ticket_js_1.TERMINAL_STATES.includes(t.state) && children.length > 0) {
+            for (const childId of children) {
+                const child = byId.get(childId);
+                if (child && !ticket_js_1.TERMINAL_STATES.includes(child.state)) {
+                    add("error", t.id, `is ${t.state} but child ${childId} is still '${child.state}'`);
+                }
+            }
+        }
+        // An active ticket whose branch was deleted has lost its working context.
+        if (t.state === "active" && t.work?.branch) {
+            if (!(0, git_js_1.branchExists)(t.work.branch, repoRoot)) {
+                add("warning", t.id, `is active but its branch '${t.work.branch}' no longer exists`);
+            }
+        }
+        // Dangling relationship references.
+        const rel = t.relationships;
+        if (rel?.parent && !byId.has(rel.parent)) {
+            add("warning", t.id, `references missing parent ${rel.parent}`);
+        }
+        for (const childId of children) {
+            if (!byId.has(childId)) {
+                add("warning", t.id, `references missing child ${childId}`);
+            }
+        }
+        for (const depId of rel?.depends_on ?? []) {
+            if (!byId.has(depId)) {
+                add("warning", t.id, `references missing dependency ${depId}`);
+            }
+        }
+    }
+    return issues;
+}
+function registerDoctor(program) {
+    program
+        .command("doctor")
+        .description("Reconcile committed .todo/ state against git reality and report drift")
+        .option("--json", "output issues as a JSON array")
+        .option("--strict", "exit non-zero when any issue is found, including warnings")
+        .action((opts) => {
+        const ctx = (0, context_js_1.getContext)(true);
+        const { repoRoot } = ctx;
+        try {
+            const issues = collectIssues(repoRoot);
+            const errors = issues.filter((i) => i.severity === "error");
+            const warnings = issues.filter((i) => i.severity === "warning");
+            if (opts.json) {
+                console.log(JSON.stringify(issues, null, 2));
+            }
+            else if (issues.length === 0) {
+                console.log("todo doctor: no issues found — .todo/ is consistent.");
+            }
+            else {
+                for (const i of issues) {
+                    const tag = i.severity === "error" ? "ERROR" : "warn ";
+                    console.log(`${tag}  ${i.ticket}  ${i.message}`);
+                }
+                console.log(`\n${errors.length} error(s), ${warnings.length} warning(s).`);
+            }
+            const failed = opts.strict ? issues.length > 0 : errors.length > 0;
+            if (failed)
+                process.exit(1);
+        }
+        catch (err) {
+            (0, errors_js_1.handleError)(err);
+        }
+    });
+}

package/dist/commands/edit.js

@@ -10,6 +10,7 @@ const VALID_TYPES = [
     "refactor",
     "chore",
     "debt",
+    "investigation",
 ];
 function registerEdit(program) {
     program

package/dist/commands/new.js

@@ -12,6 +12,7 @@ const VALID_TYPES = [
     "refactor",
     "chore",
     "debt",
+    "investigation",
 ];
 const VALID_SOURCES = [
     "log",
@@ -24,7 +25,7 @@ function registerNew(program) {
     program
         .command("new [summary]")
         .description("Create a new ticket")
-        .option("-t, --type <type>", "ticket type: bug|feature|refactor|chore|debt", "chore")
+        .option("-t, --type <type>", "ticket type: bug|feature|refactor|chore|debt|investigation", "chore")
         .option("-s, --source <source>", "source type: log|test|agent|human|comment", "human")
         .option("-f, --file <path>", "associate a file path")
         .option("-l, --lines <start,end>", "line range for the file (e.g. 10,20)")

package/dist/commands/scan.js

@@ -14,6 +14,7 @@ const VALID_TYPES = [
     "refactor",
     "chore",
     "debt",
+    "investigation",
 ];
 function registerScan(program) {
     program

package/dist/commands/work.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerWork = registerWork;
 const branch_guard_js_1 = require("../branch-guard.js");
+const config_js_1 = require("../config.js");
 const context_js_1 = require("../context.js");
 const errors_js_1 = require("../errors.js");
 const git_js_1 = require("../git.js");
@@ -16,9 +17,12 @@ function registerWork(program) {
         .option("--actor <name>", "override actor (also reads TODO_ACTOR env)")
         .action((id, opts) => {
         const ctx = (0, context_js_1.getContext)(true);
-        const { repoRoot } = ctx;
+        const { repoRoot, config } = ctx;
         try {
             const ticket = (0, ticket_js_1.readTicketByPrefix)(repoRoot, id);
+            // In managed branch_mode the user (or a PR flow) owns branching,
+            // so `work` performs no git ops — same as passing --skip-branch.
+            const skipBranch = opts.skipBranch || (0, config_js_1.getBranchMode)(config) === "managed";
             // Check not terminal
             if (ticket_js_1.TERMINAL_STATES.includes(ticket.state)) {
                 console.error(`Error: ticket ${ticket.id} is in terminal state '${ticket.state}'. Cannot work on it.`);
@@ -55,7 +59,7 @@ function registerWork(program) {
             // Dirty-tree guard: refuse to leave a different todo/* branch
             // with uncommitted work. We let `main`/other branches through —
             // only the cross-ticket case is the one that loses work.
-            if (!opts.skipBranch) {
+            if (!skipBranch) {
                 let currentBranch = "";
                 try {
                     currentBranch = (0, git_js_1.getCurrentBranch)(repoRoot);
@@ -73,7 +77,7 @@ function registerWork(program) {
                     }
                 }
             }
-            if (opts.skipBranch) {
+            if (skipBranch) {
                 // --no-branch: orchestrator mode — activate on current branch without any git ops
                 const currentBranch = (0, git_js_1.getCurrentBranch)(repoRoot);
                 if (ticket.state !== "active") {

package/dist/config.d.ts

@@ -1,7 +1,9 @@
-import type { Config } from "./types.js";
+import type { BranchMode, Config, GuardMode } from "./types.js";
 export declare const DEFAULT_CONFIG: Config;
 export declare function loadConfig(repoRoot: string): Config;
 export declare function getTodoDir(repoRoot: string): string;
 export declare function ensureTodoDir(repoRoot: string): void;
 export declare function getIdLength(config: Config): number;
 export declare function getCommitPrefix(config: Config): string;
+export declare function getBranchMode(config: Config): BranchMode;
+export declare function getGuardMode(config: Config): GuardMode;

package/dist/config.js

@@ -7,11 +7,17 @@ exports.getTodoDir = getTodoDir;
 exports.ensureTodoDir = ensureTodoDir;
 exports.getIdLength = getIdLength;
 exports.getCommitPrefix = getCommitPrefix;
+exports.getBranchMode = getBranchMode;
+exports.getGuardMode = getGuardMode;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 exports.DEFAULT_CONFIG = {
     project: { name: "" },
-    behavior: { commit_prefix: "todo:" },
+    behavior: {
+        commit_prefix: "todo:",
+        branch_mode: "per-ticket",
+        guard_mode: "advisory",
+    },
     intake: {
         dedup_strategy: "fingerprint",
         scan_patterns: ["TODO", "FIXME", "HACK", "XXX"],
@@ -75,3 +81,9 @@ function getIdLength(config) {
 function getCommitPrefix(config) {
     return config.behavior?.commit_prefix ?? "todo:";
 }
+function getBranchMode(config) {
+    return config.behavior?.branch_mode ?? "per-ticket";
+}
+function getGuardMode(config) {
+    return config.behavior?.guard_mode ?? "advisory";
+}

package/dist/git.d.ts

@@ -17,6 +17,17 @@ export declare function getLastCommitForFile(path: string, cwd?: string): string
 export declare function createBranch(name: string, cwd?: string): void;
 export declare function checkoutBranch(name: string, cwd?: string): void;
 export declare function getGitUserName(cwd?: string): string;
+/**
+ * Stage the .todo/ directory (additions, modifications, AND deletions — a
+ * close moves the file from open/ to done/) and commit it. Used by
+ * `todo close --commit-state` to make close-and-record atomic: the state
+ * file is recorded by the same command that closed the ticket, so a failed
+ * close can never be followed by a stray manual "close" commit that desyncs
+ * committed .todo/ from reality. Returns the resulting HEAD sha. If nothing
+ * is staged (state already committed), no commit is made and current HEAD is
+ * returned — a close that already succeeded on disk must not error out here.
+ */
+export declare function commitTodoState(message: string, cwd?: string): string;
 export declare function hasUncommittedChanges(cwd?: string): boolean;
 export declare function getCommitMessagesBetween(base: string, head: string, cwd?: string): string[];
 export declare function getGitDir(cwd?: string): string;

package/dist/git.js

@@ -17,6 +17,7 @@ exports.getLastCommitForFile = getLastCommitForFile;
 exports.createBranch = createBranch;
 exports.checkoutBranch = checkoutBranch;
 exports.getGitUserName = getGitUserName;
+exports.commitTodoState = commitTodoState;
 exports.hasUncommittedChanges = hasUncommittedChanges;
 exports.getCommitMessagesBetween = getCommitMessagesBetween;
 exports.getGitDir = getGitDir;
@@ -120,6 +121,24 @@ function checkoutBranch(name, cwd = process.cwd()) {
 function getGitUserName(cwd = process.cwd()) {
     return exec(["config", "user.name"], cwd);
 }
+/**
+ * Stage the .todo/ directory (additions, modifications, AND deletions — a
+ * close moves the file from open/ to done/) and commit it. Used by
+ * `todo close --commit-state` to make close-and-record atomic: the state
+ * file is recorded by the same command that closed the ticket, so a failed
+ * close can never be followed by a stray manual "close" commit that desyncs
+ * committed .todo/ from reality. Returns the resulting HEAD sha. If nothing
+ * is staged (state already committed), no commit is made and current HEAD is
+ * returned — a close that already succeeded on disk must not error out here.
+ */
+function commitTodoState(message, cwd = process.cwd()) {
+    exec(["add", "-A", ".todo"], cwd);
+    const staged = exec(["diff", "--cached", "--name-only", "--", ".todo"], cwd);
+    if (staged.length === 0)
+        return resolveHEAD(cwd);
+    exec(["commit", "-m", message], cwd);
+    return resolveHEAD(cwd);
+}
 function hasUncommittedChanges(cwd = process.cwd()) {
     const out = exec(["status", "--porcelain"], cwd);
     return out.length > 0;

package/dist/state.js

@@ -58,6 +58,19 @@ function validateTransition(ticket, targetState, params, repoRoot) {
             }
             // commit is optional for parent (defaults to HEAD — caller handles HEAD resolution)
         }
+        else if (ticket.type === "investigation") {
+            // Investigation/decision: the deliverable is a documented conclusion,
+            // not a code change. Require a resolution note (the conclusion, which
+            // should reference any doc/finding). A commit is optional — close
+            // still defaults it to HEAD for provenance — but if one is given it
+            // must exist.
+            if (!params.note) {
+                throw new Error(`Investigation ticket requires a resolution note (the documented conclusion)`);
+            }
+            if (commit && !(0, git_js_1.commitExists)(commit, repoRoot)) {
+                throw new Error(`Commit '${commit}' does not exist in the repository`);
+            }
+        }
         else {
             // Non-parent: commit always required
             if (!commit) {

package/dist/types.d.ts

@@ -1,6 +1,8 @@
-export type TicketType = "bug" | "feature" | "refactor" | "chore" | "debt";
+export type TicketType = "bug" | "feature" | "refactor" | "chore" | "debt" | "investigation";
 export type State = "open" | "active" | "blocked" | "done" | "wontfix" | "duplicate";
 export type SourceType = "log" | "test" | "agent" | "human" | "comment";
+export type BranchMode = "per-ticket" | "managed";
+export type GuardMode = "advisory" | "strict";
 export type AnalysisType = "blame" | "hypothesis" | "evidence" | "conclusion";
 export type Source = {
     type: "log";
@@ -87,6 +89,8 @@ export interface Config {
     };
     behavior?: {
         commit_prefix?: string;
+        branch_mode?: BranchMode;
+        guard_mode?: GuardMode;
     };
     intake?: {
         dedup_strategy?: "fingerprint" | "file-line" | "semantic";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4-r-c-4-n-4/todo",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Git-native work tracking for coding agents",
   "main": "dist/cli.js",
   "bin": {