@open-agent-toolkit/cli 0.1.64 → 0.1.65

package/assets/docs/cli-utilities/backlog-lifecycle.md

@@ -42,11 +42,11 @@ oat backlog archive BL-260705-example --wont-do --summary "superseded by BL-2607
 A single `oat backlog archive` run performs the whole close-out so its parts cannot drift apart:
 
 1. Sets the terminal `status` (`closed` by default, `wont_do` with `--wont-do`) and stamps `updated`.
-2. Appends a canonical newest-first entry to `completed.md`. `closed` items always get an entry (with a visible `TODO: summarize outcome` placeholder when `--summary` is omitted, so the gap stays visible); `wont_do` items get one only when you pass `--summary`.
+2. Validates and trims a nonblank `--summary` before mutating a `closed` item, then appends its canonical newest-first `completed.md` entry. `wont_do` items may omit the summary and get an entry only when one is provided.
 3. Moves `items/<id>.md` into `archived/` — with `git mv` inside a work tree, or a plain rename outside git.
 4. Regenerates the managed backlog index.
 
-The command is safe to re-run: an item already in `archived/` produces a no-op warning with no writes. An out-of-enum current status (for example a hand-set `done`) is a hard error that names the file, lists the valid statuses, and tells you how to recover. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
+The command is safe to re-run: an item already in `archived/` produces a no-op warning with no writes. A missing closed-item summary or an out-of-enum current status (for example a hand-set `done`) is a hard error before mutation and includes recovery guidance. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
 
 ## Catching lifecycle drift
 

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -14,6 +14,7 @@ Use these commands when you need operational support around the toolkit rather t
 Use the `oat backlog` group when you want direct CLI support for the file-backed backlog under `.oat/repo/pjm/backlog/`.
 
 - `oat backlog init` - scaffold `.oat/repo/pjm/backlog/` with starter files and directories for a fresh repo
+- `oat backlog new <title>` - validate and create a file-backed backlog item from the canonical template, then regenerate the managed index
 - `oat backlog generate-id <title>` - generate a deterministic `BL-YYMMDD-slug` backlog ID from a title
 - `oat backlog generate-id <title> --created-at <timestamp>` - generate a reproducible ID for a known creation timestamp
 - `oat backlog archive <id>` - atomic close-out: set a terminal status, record the completion in `completed.md`, move the item into `archived/`, and regenerate the index in one step
@@ -21,10 +22,18 @@ Use the `oat backlog` group when you want direct CLI support for the file-backed
 
 Backlog IDs are deterministic date+slug identifiers (`BL-YYMMDD-slug`) derived from the creation date and title, so two machines or worktrees produce the same ID for the same record without scanning the local checkout. The slug is capped at 30 characters at the last whole-word boundary (with trailing stop-words trimmed), so prefer concise, meaningful titles. Index regeneration is deterministic and safe to re-run when resolving an index merge conflict.
 
-Run `oat backlog init` first when the local backlog scaffold does not exist yet in a fresh repo. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
+Run `oat backlog init` directly when you need to create or repair only the backlog scaffold. `oat backlog new` initializes a missing scaffold automatically after validating its inputs. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
 
 For the end-to-end states an item moves through — and how `oat backlog archive` and `oat pjm doctor` keep the backlog honest — see [Backlog Lifecycle](backlog-lifecycle.md).
 
+### `oat backlog new`
+
+`oat backlog new <title> [--priority <priority>] [--scope <scope>] [--scope-estimate <size>] [--labels <labels>] [--description <text>] [--backlog-root <path>]` creates one active item and refreshes the managed backlog index.
+
+Defaults are `priority: medium` and `scope: task`. Valid priorities are `urgent`, `high`, `medium`, `low`, and `none`; valid scopes are `idea`, `task`, `feature`, and `initiative`; scope estimates accept `XS`, `S`, `M`, `L`, `XL`, or `XXL`. Pass labels as a comma-delimited list.
+
+The command validates all inputs before creating the scaffold or writing an item. It uses the repo-local canonical backlog template when available, falls back to the CLI's bundled template, writes structured YAML frontmatter, and rejects an ID collision in either `items/` or `archived/` without overwriting the existing record. If managed-index regeneration fails after the item write, OAT removes only the new item and restores the prior index.
+
 ### `oat backlog archive`
 
 `oat backlog archive <id> [--wont-do] [--summary <text>] [--json] [--backlog-root <path>]` performs the full close-out for a backlog item so status flip, completed-log entry, file move, and index regeneration never drift apart.
@@ -33,22 +42,23 @@ For the end-to-end states an item moves through — and how `oat backlog archive
 
 - `<id>` (required) - the backlog item id (`BL-YYMMDD-slug`); the item file must live under `items/`.
 - `--wont-do` - close the item as `wont_do` instead of the default terminal status `closed`.
-- `--summary <text>` - one-line outcome summary recorded in `completed.md`.
+- `--summary <text>` - one-line outcome summary recorded in `completed.md`; required and nonblank for the default `closed` path.
 - `--backlog-root <path>` - override the backlog root (defaults to `.oat/repo/pjm/backlog`).
 - `--json` - emit the machine-readable result payload instead of human log lines.
 
 **Behavior:**
 
 - Validates the item's current `status` against the enum (`open | in_progress | closed | wont_do`); an out-of-enum value such as `done` is a hard error with a fix hint. Archiving is legal from any valid status — a `closed` item still in `items/` just gets its move finished.
+- For the default `closed` path, validates and trims a nonblank `--summary` before any file or index mutation. The `wont_do` path may omit the summary and completion-ledger entry.
 - Rewrites only the `status:` and `updated:` frontmatter lines (preserving any inline enum comment), then moves the item from `items/` to `archived/` with `git mv` inside a work tree, falling back to a plain rename (with a warning) outside git or if `git mv` fails.
-- `closed` archives always append a canonical newest-first `completed.md` entry (`YYYY-MM-DD — <id> — Title — summary`); when `--summary` is omitted the entry carries a visible `TODO: summarize outcome` placeholder. `wont_do` archives append an entry only when `--summary` is provided. A missing `completed.md` is scaffolded from the starter template; a missing `## Completed Items` heading is scaffolded with a warning.
+- `closed` archives append a canonical newest-first `completed.md` entry (`YYYY-MM-DD — <id> — Title — summary`). `wont_do` archives append an entry only when `--summary` is provided. A missing `completed.md` is scaffolded from the starter template; a missing `## Completed Items` heading is scaffolded with a warning.
 - Regenerates the managed backlog index after the move.
 - Idempotent: re-running on an item already in `archived/` is a no-op warning with no writes.
 
 **Exit codes:**
 
 - `0` - item archived, or already-archived no-op.
-- `1` - actionable error: unknown id (no file under `items/`) or an out-of-enum current status. The message names the file path, the valid statuses, and the fix.
+- `1` - actionable error: unknown id, out-of-enum current status, duplicate active/archived ID, or a missing closed-item summary. The message includes the recovery action.
 - `2` - reserved for unexpected system/runtime failures.
 
 **JSON payload (`--json`):**
@@ -76,10 +86,12 @@ For full project-management repo-reference setup, use [`oat pjm init`](tool-pack
 Use the `oat decision` group for file-per-record decisions under `.oat/repo/reference/decisions/`. Each decision is its own file with a deterministic `DR-YYMMDD-slug` ID (the slug is capped at 30 characters at the last whole-word boundary, with trailing stop-words trimmed), and the human-facing index is a committed generated view.
 
 - `oat decision init` - scaffold `.oat/repo/reference/decisions/` and the managed decision index
-- `oat decision new <title>` - create a new decision record; supports `--status`, `--context`, and `--created-at`
+- `oat decision new <title>` - create a new decision record; supports `--status`, `--context`, `--decision`, `--consequences`, and `--created-at`
 - `oat decision regenerate-index` - rebuild the managed decision index table from record frontmatter
 - `oat decision migrate` - convert a legacy single `decision-record.md` into file-per-record decisions, preserving each old `ADR-NNN`/`DR-NNN` ID as `legacy_id`; applies by default, so pass `--dry-run` to preview the legacy-to-new mappings without writing, and `--delete-legacy` to remove the source file after a verified migration (unlike `oat pjm migrate`, which defaults to dry-run)
 
+Pass `--context`, `--decision`, and `--consequences` together when creating a resolved decision so every substantive template section is complete in the same atomic creation step. Callers that omit them retain the template's placeholder content for later editing.
+
 The decision index uses managed marker pairs and is deterministic, so an index merge conflict can be resolved by re-running `oat decision regenerate-index` and staging the result. Decision records replace the legacy single `decision-record.md`; repos still on the old layout migrate with `oat decision migrate` (or the broader `oat pjm migrate`).
 
 ## `oat local ...`
@@ -239,4 +251,6 @@ For the full state model, repair semantics, and examples, see [Instruction Sync]
 - `oat internal validate-oat-skills` - validate `oat-*` skill contracts and metadata
 - `oat doctor` - run environment and setup diagnostics, including installed-vs-bundled skill version checks
 
-`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.
+`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. At project scope it also scans bounded repository script and documentation surfaces for known-stale CLI grammar, such as `oat --scope all sync`, and reports file/line evidence plus the current `oat sync --scope all` form. Generated provider views, OAT lifecycle artifacts, archived content, dependencies, build output, and nested worktrees are excluded.
+
+The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.

package/assets/docs/cli-utilities/tool-packs.md

@@ -171,6 +171,7 @@ Purpose:
 Key behavior:
 
 - Accepts a tool name, `--pack <pack>`, or `--all` (mutually exclusive)
+- With no target, exits without mutation and suggests the explicit bulk command `oat tools update --all`; invalid packs and conflicting targets keep their own targeted diagnostics
 - Compares installed versions against bundled versions and copies updated assets
 - For `--pack <pack>` and `--all`, an already-installed pack is reconciled to include newly added bundled skills or agents in that same scope
 - Pack-targeted updates intentionally rewrite bundled template and script companions in place, even when the pack's installed skills are already current

package/assets/docs/cli-utilities/workflow-gates.md

@@ -451,7 +451,9 @@ By default the dispatcher:
 5. Applies `--avoid same-family`.
 6. Checks candidate availability in descending priority order, with target id as
    the tie-breaker.
-7. Runs the chosen `baseCommand` with the selected model and prompt appended.
+7. Runs the chosen `baseCommand` with the selected model and prompt appended. The
+   prompt is carried in argv, stdin is closed, and stdout/stderr remain captured
+   for diagnostics and liveness tracking.
 8. Exits with the child process status.
 
 Use `--target <id>` to pin one target and skip detection/avoidance:

package/assets/docs/contributing/code.md

@@ -96,6 +96,24 @@ not the steady-state path.
 - Make verification explicit in commit-adjacent notes or review artifacts.
 - If docs behavior changes, update the docs surface in the same change window.
 
+### Breaking CLI grammar changes
+
+When a command, option name, or option placement changes, make the migration visible to both reviewers and release-note readers:
+
+- Use a `BREAKING:` PR title or prominent callout so generated release notes retain the warning.
+- Include the old and new copy-pasteable commands.
+- State the migration action for scripts, docs, and automation that use the old grammar.
+
+For example:
+
+**Breaking change title/callout:** `BREAKING: move scope after the sync command`
+
+**Before:** `oat --scope all sync` <!-- oat-doctor: allow-stale-invocation -->
+
+**After:** `oat sync --scope all`
+
+**Migration action:** Update repository scripts and documentation, then run `oat doctor --scope project` to find known-stale invocations.
+
 ## Related Guides
 
 - [Contributing Docs](documentation.md)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.64",
-  "docs-config": "0.1.64",
-  "docs-theme": "0.1.64",
-  "docs-transforms": "0.1.64"
+  "cli": "0.1.65",
+  "docs-config": "0.1.65",
+  "docs-theme": "0.1.65",
+  "docs-transforms": "0.1.65"
 }

package/assets/skills/oat-pjm-add-backlog-item/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-add-backlog-item
-version: 1.3.0
+version: 1.3.1
 description: Use when the user requests or confirms adding a new repo backlog item — e.g. "add a backlog item for X", "capture that as backlog", "track that follow-up", "file a backlog ticket", or confirms a previously offered backlog capture. Do NOT auto-invoke when a follow-up is mentioned. Creates the item file in the file-per-item backlog structure, regenerates the index, and prompts for curated overview updates.
 disable-model-invocation: false
 user-invocable: true
@@ -29,8 +29,8 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 - Before multi-step work, print short step indicators, e.g.:
   - `[1/4] Resolving item details…`
-  - `[2/4] Generating ID + populating template…`
-  - `[3/4] Regenerating backlog index…`
+  - `[2/4] Creating the item + managed index atomically…`
+  - `[3/4] Enriching acceptance criteria…`
   - `[4/4] Updating curated overview guidance…`
 
 ## Process
@@ -47,85 +47,30 @@ Collect the item details from the user or surrounding context:
 If the title is missing, ask the user.
 If the description is missing, ask for 1-3 sentences of context.
 
-### Step 2: Ensure Backlog Scaffold
+Propose an initial scope estimate (`XS`, `S`, `M`, `L`, `XL`, or `XXL`) from the described work, then ask the user to confirm or adjust it before creation.
 
-Before generating IDs or editing backlog files, run:
+### Step 2: Create the Backlog Item Atomically
 
-```bash
-oat backlog init
-```
-
-This command is idempotent. Use it even in existing repos so the canonical backlog scaffold and exact managed index markers are present before `oat backlog regenerate-index` runs.
-
-Do not hand-create the managed marker block in `backlog/index.md`. The scaffold writes the exact markers required by the CLI:
-
-```md
-<!-- OAT BACKLOG-INDEX -->
-<!-- END OAT BACKLOG-INDEX -->
-```
-
-### Step 3: Generate ID
-
-Run:
-
-```bash
-oat backlog generate-id "{title}"
-```
-
-The CLI returns a deterministic `BL-YYMMDD-slug` value derived from the creation date and the title. It performs no scan, hash, counter, or random allocation.
-
-If the command reports a same-day same-slug filename collision against an existing `items/<id>.md` or `archived/<id>.md`, do not overwrite the existing record. Disambiguate by using a more specific title and re-running `oat backlog generate-id`.
-
-### Step 4: Prepare Output Path
-
-Set the output path using the returned ID so the filename stem equals the ID:
+Run the single creation command with the confirmed values:
 
 ```bash
-ITEM_PATH=".oat/repo/pjm/backlog/items/{id}.md"
+oat backlog new "{title}" --priority "<priority>" --scope "<scope>" --scope-estimate "<confirmed-scope-estimate>" --labels "<comma-delimited-labels>" --description "<description>"
 ```
 
-### Step 5: Copy Template and Fill Frontmatter
-
-1. Use `.oat/templates/backlog-item.md` as the source template.
-2. Fill:
-   - `id`
-   - `title`
-   - `created`
-   - `updated`
-   - `status` (default `open`)
-   - `priority` (default `medium` unless the user says otherwise)
-   - `scope` (default `task` unless the user says otherwise)
-   - `labels`
-   - `assignee`
-   - `associated_issues`
-   - `external_plans` (initialize to `[]`; `oat-repo-improve` owns later reverse-link additions)
-3. Keep `external_plans` as a YAML string array of repo-relative paths under `.oat/repo/reference/external-plans/`. Do not pre-populate it from discussion or anticipated work.
-4. The agent should propose an initial `scope_estimate` based on the described work, then ask the user to confirm or adjust it.
-5. Write the item body with:
-   - `## Description`
-   - `## Acceptance Criteria`
-
-### Step 6: Write the Backlog Item
-
-Write the completed file to the path resolved in Step 4:
+The command validates all inputs, initializes the scaffold when needed, generates and collision-checks the `BL-YYMMDD-slug` ID, renders the canonical template, writes the item, and regenerates the managed index. If it reports a collision, do not overwrite the existing active or archived record; use a more specific title and rerun the same command.
 
-```bash
-.oat/repo/pjm/backlog/items/{id}.md
-```
-
-Use the template field order from `.oat/templates/backlog-item.md`.
+Use the item path and ID reported by the command. Do not hand-author frontmatter or edit the managed index block. The command initializes `external_plans: []`; `oat-repo-improve` owns later reverse-link additions.
 
-### Step 7: Regenerate Managed Index
+### Step 3: Enrich Acceptance Criteria
 
-Run:
+Read the created item and replace only the placeholder bullets under `## Acceptance Criteria` with the acceptance criteria confirmed in Step 1. Preserve the command-generated frontmatter and description. This post-create enrichment is safe because Acceptance Criteria are not index-visible fields.
 
-```bash
-oat backlog regenerate-index
-```
+The item must retain both required body sections:
 
-This refreshes the managed table inside `.oat/repo/pjm/backlog/index.md`.
+- `## Description`
+- `## Acceptance Criteria`
 
-### Step 8: Update Curated Overview
+### Step 4: Update Curated Overview
 
 Read `.oat/repo/pjm/backlog/index.md` and update the `## Curated Overview` section with a brief human-written note when helpful, for example:
 
@@ -135,7 +80,7 @@ Read `.oat/repo/pjm/backlog/index.md` and update the `## Curated Overview` secti
 
 Do not edit inside the managed marker section.
 
-### Step 9: Summarize to the User
+### Step 5: Summarize to the User
 
 Report:
 
@@ -151,5 +96,5 @@ Report:
 - Item includes populated frontmatter and both required body sections
 - Item initializes `external_plans: []` for future reverse links
 - `scope_estimate` was proposed and confirmed
-- `oat backlog regenerate-index` ran successfully
+- `oat backlog new` created the item and regenerated the managed index successfully
 - `.oat/repo/pjm/backlog/index.md` remains valid, with managed section untouched except by regeneration

package/assets/skills/oat-project-summary/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-summary
-version: 1.3.1
+version: 1.3.2
 description: Use when the user requests or confirms summarizing an active OAT project — e.g. "summarize the project", "generate the summary", "run oat-project-summary", or confirms a previously offered summary run. Do NOT auto-invoke when implementation completes. Generates summary.md from project artifacts as institutional memory.
 disable-model-invocation: false
 user-invocable: true
@@ -278,7 +278,12 @@ test -f .oat/repo/reference/decisions/index.md || oat decision init
 
 **6.4 — Idempotent, date-independent promotion (critical).** For each decision in `## Key Decisions`:
 
-1. **Derive title + rationale.** The decision's bold lead-in / first clause becomes the **title** (a short noun phrase). The remaining explanatory text becomes the **rationale**, passed verbatim as `--context`.
+1. **Derive title + complete sections.** Ground every value in the Key Decision and its project artifacts:
+   - The bold lead-in / first clause becomes the **title** (a short noun phrase).
+   - The problem, constraint, or motivating rationale becomes **context**.
+   - The choice that was made becomes the **decision**.
+   - The resulting tradeoffs, follow-on effects, or operational implications become **consequences**.
+     Each section must contain concrete grounded prose; do not pass placeholder content.
 2. **Compute the slug the CLI would use.** The CLI generates the record ID as `DR-<YYMMDD>-<slug>`, where `<slug>` is the lowercased, ASCII-folded, hyphen-collapsed form of the title, capped at 30 characters at the last whole-word boundary with trailing stop-words (`a, an, the, of, for, and, to, in, on, as, with`) trimmed (the same slug rule the CLI applies). Compute that `<slug>` for the title.
 3. **Dedup on the exact slug, ignoring only the date prefix.** A record ID is `DR-<YYMMDD>-<slug>`, where the date is exactly six digits. Check whether a record for this slug already exists by stripping that fixed `DR-<6 digits>-` prefix from existing record IDs and comparing the remaining slug for **exact equality**. Anchor the date to exactly six characters so the slug must match in full:
 
@@ -294,10 +299,10 @@ test -f .oat/repo/reference/decisions/index.md || oat decision init
    - Otherwise → create it:
 
      ```bash
-     oat decision new "<title>" --status accepted --context "<rationale>"
+     oat decision new "<title>" --status accepted --context "<context>" --decision "<decision>" --consequences "<consequences>"
      ```
 
-     The command generates the deterministic `DR-YYMMDD-slug` ID, seeds the body from `.oat/templates/decision.md`, and regenerates the managed index automatically — do not hand-edit `index.md`. Optionally pass `--created-at "<project completion date>"` when a project completion date is available, so the record's date reflects when the decision was made.
+     The command generates the deterministic `DR-YYMMDD-slug` ID, fills every decision body section, and regenerates the managed index automatically — do not hand-edit `index.md`. Optionally pass `--created-at "<project completion date>"` when a project completion date is available, so the record's date reflects when the decision was made.
 
 Because of the date-independent slug dedup, this step is **safe to run every time `summary.md` is (re)generated** — including the pr-final refresh and revision re-runs — without ever creating duplicate decision records. Already-promoted decisions are skipped; only genuinely new Key Decisions become new records.
 

package/assets/templates/plan.md

@@ -65,6 +65,8 @@ Codex effort values are preferred controls. `oat-project-implement` caps them wh
 
 ---
 
+RED/GREEN/Refactor is the recommended default where work is testable, not a validator requirement. Other task-body shapes, including non-TDD shapes, are allowed when appropriate, provided the plan preserves stable `pNN-tNN` IDs, per-task verification, and atomic commits.
+
 ## Phase 1: {Phase Name}
 
 ### Task p01-t01: {Task Name}

package/dist/commands/backlog/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/archive.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,iBAAiB,EAGvB,MAAM,sBAAsB,CAAC;AAoB9B,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,CAAK;CAKjD;AAkID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAkHnC"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/archive.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,iBAAiB,EAGvB,MAAM,sBAAsB,CAAC;AAmB9B,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,CAAK;CAKjD;AAkID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAqHnC"}

package/dist/commands/backlog/archive.js

@@ -8,7 +8,6 @@ import { regenerateBacklogIndex } from './regenerate-index.js';
 import { BACKLOG_ITEM_STATUSES, extractBacklogStatus, isValidBacklogStatus, } from './shared/item-status.js';
 const execFileAsync = promisify(execFile);
 const COMPLETED_HEADING = '## Completed Items';
-const TODO_SUMMARY = 'TODO: summarize outcome';
 const STARTER_COMPLETED = [
     '# OAT Backlog Completed',
     '',
@@ -178,6 +177,10 @@ export async function archiveBacklogItem(backlogRoot, id, options = {}) {
         throw new BacklogArchiveError(`Backlog item ${itemsPath} has invalid status "${currentStatus ?? ''}". Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}. Fix: correct the \`status\` field manually, then re-run \`oat backlog archive ${id}\`.`);
     }
     const targetStatus = options.wontDo ? 'wont_do' : 'closed';
+    const summary = options.summary?.trim() ?? '';
+    if (targetStatus === 'closed' && summary.length === 0) {
+        throw new BacklogArchiveError(`Closing backlog item ${id} requires a non-empty outcome summary. Fix: rerun with \`--summary "<outcome>"\`.`);
+    }
     const now = options.now ?? new Date();
     const updatedIso = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
     const entryDate = updatedIso.slice(0, 10);
@@ -188,11 +191,8 @@ export async function archiveBacklogItem(backlogRoot, id, options = {}) {
     // 5. completed.md entry — always for `closed`; only with a summary for
     //    `wont_do`.
     let completedEntry = 'skipped';
-    const shouldWriteEntry = targetStatus === 'closed' || Boolean(options.summary);
+    const shouldWriteEntry = targetStatus === 'closed' || summary.length > 0;
     if (shouldWriteEntry) {
-        const summary = options.summary?.trim()
-            ? options.summary.trim()
-            : TODO_SUMMARY;
         const entryLine = `- ${entryDate} — ${id} — ${title} — ${summary}`;
         const completedPath = join(backlogRoot, 'completed.md');
         let scaffoldedFile = false;

package/dist/commands/backlog/index.d.ts

@@ -1,14 +1,18 @@
 import { buildCommandContext } from '../../app/command-context.js';
+import { resolveAssetsRoot } from '../../fs/assets.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
 import { archiveBacklogItem } from './archive.js';
 import { initializeBacklog } from './init.js';
+import { createBacklogItem } from './new.js';
 import { regenerateBacklogIndex } from './regenerate-index.js';
 interface BacklogCommandDependencies {
     buildCommandContext: typeof buildCommandContext;
     resolveProjectRoot: typeof resolveProjectRoot;
+    resolveAssetsRoot: typeof resolveAssetsRoot;
     initializeBacklog: typeof initializeBacklog;
     regenerateBacklogIndex: typeof regenerateBacklogIndex;
+    createBacklogItem: typeof createBacklogItem;
     archiveBacklogItem: typeof archiveBacklogItem;
     pathExists: (path: string) => Promise<boolean>;
 }

package/dist/commands/backlog/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAqB5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AA0CD,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAiMT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AA8B5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AA4CD,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAqQT"}

package/dist/commands/backlog/index.js

@@ -2,10 +2,12 @@ import { access } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { buildCommandContext } from '../../app/command-context.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
+import { resolveAssetsRoot } from '../../fs/assets.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
 import { archiveBacklogItem, BacklogArchiveError } from './archive.js';
 import { initializeBacklog } from './init.js';
+import { createBacklogItem } from './new.js';
 import { regenerateBacklogIndex } from './regenerate-index.js';
 import { generateBacklogId } from './shared/generate-id.js';
 async function pathExistsDefault(path) {
@@ -26,8 +28,10 @@ async function pathExistsDefault(path) {
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
+    resolveAssetsRoot,
     initializeBacklog,
     regenerateBacklogIndex,
+    createBacklogItem,
     archiveBacklogItem,
     pathExists: pathExistsDefault,
 };
@@ -60,6 +64,57 @@ export function createBacklogCommand(overrides = {}) {
         }
         process.exitCode = 0;
     });
+    cmd
+        .command('new')
+        .description('Create a new file-backed backlog item')
+        .argument('<title>', 'Backlog item title')
+        .option('--priority <priority>', 'Item priority', 'medium')
+        .option('--scope <scope>', 'Item scope', 'task')
+        .option('--scope-estimate <size>', 'Optional scope estimate (XS|S|M|L|XL|XXL)')
+        .option('--labels <labels>', 'Comma-delimited labels', (value) => value.split(','))
+        .option('--description <text>', 'Initial description body text')
+        .option('--backlog-root <path>', 'Backlog root directory (defaults to .oat/repo/pjm/backlog)')
+        .action(async (title, options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        try {
+            const projectRoot = await dependencies.resolveProjectRoot(context.cwd);
+            const backlogRoot = await resolveBacklogRoot(context, options.backlogRoot, dependencies);
+            const assetsRoot = await dependencies.resolveAssetsRoot();
+            const result = await dependencies.createBacklogItem({
+                backlogRoot,
+                assetsRoot,
+                templatesRoot: resolve(projectRoot, '.oat', 'templates'),
+                title,
+                priority: options.priority,
+                scope: options.scope,
+                scopeEstimate: options.scopeEstimate,
+                labels: options.labels,
+                description: options.description,
+            });
+            if (context.json) {
+                context.logger.json({ status: 'ok', ...result });
+            }
+            else {
+                for (const warning of result.index.warnings) {
+                    context.logger.warn(warning);
+                }
+                context.logger.info(`Created backlog item ${result.id}`);
+                context.logger.info(`Wrote ${result.filePath}`);
+                context.logger.info(`Regenerated backlog index with ${result.index.itemCount} ${result.index.itemCount === 1 ? 'item' : 'items'}.`);
+            }
+            process.exitCode = 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (context.json) {
+                context.logger.json({ status: 'error', message });
+            }
+            else {
+                context.logger.error(message);
+            }
+            process.exitCode = 1;
+        }
+    });
     cmd
         .command('regenerate-index')
         .description('Regenerate the managed backlog index table')

package/dist/commands/backlog/new.d.ts

@@ -0,0 +1,27 @@
+import { initializeBacklog } from './init.js';
+import { regenerateBacklogIndex, type RegenerateBacklogIndexResult } from './regenerate-index.js';
+export interface CreateBacklogItemOptions {
+    backlogRoot: string;
+    assetsRoot: string;
+    templatesRoot?: string;
+    title: string;
+    priority?: string;
+    scope?: string;
+    scopeEstimate?: string;
+    labels?: string[];
+    description?: string;
+    createdAt?: string;
+}
+export interface CreateBacklogItemResult {
+    id: string;
+    backlogRoot: string;
+    filePath: string;
+    templatePath: string;
+    index: RegenerateBacklogIndexResult;
+}
+export interface CreateBacklogItemDependencies {
+    initializeBacklog: typeof initializeBacklog;
+    regenerateBacklogIndex: typeof regenerateBacklogIndex;
+}
+export declare function createBacklogItem(options: CreateBacklogItemOptions, overrides?: Partial<CreateBacklogItemDependencies>): Promise<CreateBacklogItemResult>;
+//# sourceMappingURL=new.d.ts.map

package/dist/commands/backlog/new.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/new.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EACL,sBAAsB,EACtB,KAAK,4BAA4B,EAClC,MAAM,oBAAoB,CAAC;AAS5B,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,4BAA4B,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC5C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AAuLD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,SAAS,GAAE,OAAO,CAAC,6BAA6B,CAAM,GACrD,OAAO,CAAC,uBAAuB,CAAC,CAqDlC"}