@open-agent-toolkit/cli 0.1.30 → 0.1.32

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

@@ -11,16 +11,29 @@ Use these commands when you need operational support around the toolkit rather t
 
 ## `oat backlog ...`
 
-Use the `oat backlog` group when you want direct CLI support for the file-backed backlog under `.oat/repo/reference/backlog/`.
+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/reference/backlog/` with starter files and directories for a fresh repo
-- `oat backlog generate-id <filename>` - generate a unique backlog ID from a filename seed
-- `oat backlog generate-id <filename> --created-at <timestamp>` - generate a reproducible ID for a known creation timestamp
+- `oat backlog init` - scaffold `.oat/repo/pjm/backlog/` with starter files and directories for a fresh repo
+- `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 regenerate-index` - rebuild the managed backlog index table from item frontmatter
 
+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.
 
-For full project-management repo-reference setup, use [`oat pjm init`](tool-packs.md#install-vs-initialize). It scaffolds `current-state.md`, `roadmap.md`, `decision-record.md`, and delegates the backlog sub-surface to `oat backlog init`.
+For full project-management repo-reference setup, use [`oat pjm init`](tool-packs.md#install-vs-initialize). It scaffolds the two-layer PJM surface (`pjm/current-state.md`, `pjm/roadmap.md`, `reference/decisions/`, and AGENTS guides) and delegates the backlog sub-surface to `oat backlog init`.
+
+## `oat decision ...`
+
+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 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)
+
+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 ...`
 

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

@@ -20,7 +20,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 - `workflows` - project lifecycle skills, wrap-up reporting, reviewer agents, and core project templates
 - `ideas` - lightweight ideation and promotion flows
 - `utility` - review and repo-maintenance helpers
-- `project-management` - file-backed backlog/reference skills plus backlog, roadmap, current-state, and decision-record templates
+- `project-management` - file-backed backlog/reference skills plus backlog, roadmap, current-state, file-per-record decision, and AGENTS-guide templates
 - `research` - research, analysis, comparison, and synthesis skills
 - `brainstorm` - always-on brainstorming entry point with visual companion
 
@@ -33,7 +33,7 @@ The `oat tools` command group provides a unified interface for managing installe
 The `project-management` pack has two lifecycle steps:
 
 - **Install**: `oat tools install project-management` (or the legacy `oat init tools project-management`) copies project-management skills into `.agents/skills/` and template sources into `.oat/templates/`.
-- **Initialize**: `oat pjm init` instantiates the working repo-reference surface under `.oat/repo/reference/`.
+- **Initialize**: `oat pjm init` instantiates the two-layer working repo-reference surface under `.oat/repo/`.
 
 Installing the pack makes the skills and templates available; it does not create the repo's working project-management reference docs. Run `oat pjm init` when you want to scaffold the canonical PJM surface for a repo:
 
@@ -41,18 +41,23 @@ Installing the pack makes the skills and templates available; it does not create
 oat pjm init
 ```
 
-The command creates missing files and directories for:
+The canonical surface splits active operational state (under `pjm/`) from durable append-mostly references (under `reference/`). The command creates missing files and directories for:
 
-- `.oat/repo/reference/current-state.md`
-- `.oat/repo/reference/roadmap.md`
-- `.oat/repo/reference/decision-record.md`
-- `.oat/repo/reference/backlog/`
+- `.oat/repo/pjm/current-state.md`
+- `.oat/repo/pjm/roadmap.md`
+- `.oat/repo/pjm/backlog/`
+- `.oat/repo/reference/decisions/` (file-per-record decisions plus a generated index)
+- AGENTS guides at `.oat/repo/AGENTS.md`, `.oat/repo/pjm/AGENTS.md`, and `.oat/repo/reference/AGENTS.md`
+
+Decisions are now file-per-record under `reference/decisions/` (created and indexed with the [`oat decision`](config-and-local-state.md#oat-decision-) command group), replacing the legacy single `decision-record.md`. Repos still on the old `reference/` layout can migrate with `oat pjm migrate`.
 
 `oat pjm init` is idempotent and non-destructive. Existing reference docs are skipped and left unchanged, so curated repo state is not overwritten on repeated runs.
 
+Run `oat pjm doctor` to check an existing surface: it reports missing canonical files, leftover template frontmatter, and legacy/loose/second-roadmap drift, and accepts `--json` for machine-readable output. The same checks also run under project-scope `oat doctor` when `.oat/repo` exists.
+
 Useful options:
 
-- `--reference-root <path>` - scaffold a different reference root instead of `.oat/repo/reference/`
+- `--repo-root <path>` - scaffold a different repo-reference root instead of `.oat/repo`
 - `--json` - emit a machine-readable result with created and skipped paths
 
 Backlog scaffolding is delegated to the lower-level [`oat backlog init`](config-and-local-state.md#oat-backlog-) helper. Use `oat pjm init` for the full PJM repo-reference surface, and use `oat backlog init` directly only when you need to create or repair the backlog sub-surface by itself.

package/assets/docs/reference/cli-reference.md

@@ -37,19 +37,20 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 ## Command Groups
 
-| Command group                                   | What it covers                                                                                                                                            | Go deeper                                                                      |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                       | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                 |
-| `oat tools ...`                                 | Install, inspect, update, and remove bundled OAT tool packs and assets.                                                                                   | [Tool Packs](../cli-utilities/tool-packs.md)                                   |
-| `oat pjm ...`                                   | Initialize the project-management repo-reference surface after installing the project-management pack.                                                    | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize) |
-| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                         | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
-| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                      | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
-| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                                               | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
-| `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                                                 | [Docs Tooling Commands](../docs-tooling/commands.md)                           |
-| `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                                           | [Provider Sync](../provider-sync/index.md)                                     |
-| `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                          |
-| `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                                                | [Reviews](../workflows/projects/reviews.md)                                    |
-| `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                                  | [Repository Analysis](../workflows/projects/repo-analysis.md)                  |
+| Command group                                   | What it covers                                                                                                                                                                                                | Go deeper                                                                          |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                                                                           | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                     |
+| `oat tools ...`                                 | Install, inspect, update, and remove bundled OAT tool packs and assets.                                                                                                                                       | [Tool Packs](../cli-utilities/tool-packs.md)                                       |
+| `oat pjm ...`                                   | Initialize the two-layer repo-reference surface (`init`), run reference diagnostics (`doctor`), and migrate legacy layouts to `pjm/` + `reference/` (`migrate`) after installing the project-management pack. | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize)     |
+| `oat decision ...`                              | Create, index, and migrate file-per-record repo decisions under `reference/decisions/` (`init`, `new`, `regenerate-index`, `migrate`).                                                                        | [Config and Local State](../cli-utilities/config-and-local-state.md#oat-decision-) |
+| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                                                                             | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
+| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                          | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
+| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                                                                                                   | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
+| `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                                                                                                     | [Docs Tooling Commands](../docs-tooling/commands.md)                               |
+| `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                                                                                               | [Provider Sync](../provider-sync/index.md)                                         |
+| `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands.                                                     | [Workflow & Projects](../workflows/projects/index.md)                              |
+| `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                                                                                                    | [Reviews](../workflows/projects/reviews.md)                                        |
+| `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                                                                                      | [Repository Analysis](../workflows/projects/repo-analysis.md)                      |
 
 Notable commands introduced in the current CLI surface:
 

package/assets/docs/reference/file-locations.md

@@ -43,7 +43,8 @@ Config ownership note:
 - Templates: `.oat/templates/`
 - Runtime sync state: `.oat/sync/`
 - Repo knowledge: `.oat/repo/knowledge/`
-- Repo reference docs: `.oat/repo/reference/`
+- Active PJM operational layer: `.oat/repo/pjm/` (`current-state.md`, `roadmap.md`, `backlog/`)
+- Durable repo references: `.oat/repo/reference/` (file-per-record decisions under `decisions/`)
 - Repo reviews: `.oat/repo/reviews/`
 - Repo archive: `.oat/repo/archive/`
 

package/assets/docs/reference/oat-directory-structure.md

@@ -34,6 +34,7 @@ Project scope is used for project workflows and repo-local sync state. User scop
   scripts/
   repo/
     knowledge/
+    pjm/
     reference/
     reviews/
     archive/
@@ -41,16 +42,16 @@ Project scope is used for project workflows and repo-local sync state. User scop
 
 ## Top-level entries
 
-| Path                     | Purpose                                          | Notes                                                                                                   |
-| ------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `.oat/config.json`       | Shared repo runtime config for non-sync settings | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, and `documentation.*`     |
-| `.oat/config.local.json` | Local per-developer runtime state                | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                 |
-| `.oat/state.md`          | Generated repo state dashboard                   | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata     |
-| `.oat/projects/`         | OAT project artifacts                            | `shared`, `local`, `archived` scopes                                                                    |
-| `.oat/ideas/`            | Project-level ideas store                        | Often gitignored                                                                                        |
-| `.oat/sync/`             | Interop sync state/config                        | See details below                                                                                       |
-| `.oat/templates/`        | Artifact templates used by OAT skills            | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates. |
-| `.oat/repo/`             | Repo-level knowledge/reference/review artifacts  | Durable operational records                                                                             |
+| Path                     | Purpose                                             | Notes                                                                                                   |
+| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, and `documentation.*`     |
+| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                 |
+| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata     |
+| `.oat/projects/`         | OAT project artifacts                               | `shared`, `local`, `archived` scopes                                                                    |
+| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                        |
+| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                       |
+| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates. |
+| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`              |
 
 ## `.oat/sync/` details
 
@@ -210,23 +211,35 @@ Not all workflow modes require every artifact:
 
 ## `.oat/repo/` structure
 
-| Path                   | Purpose                                                                                                                                 |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `.oat/repo/knowledge/` | Generated codebase knowledge indexes                                                                                                    |
-| `.oat/repo/reference/` | Repo-level reference docs, including the canonical PJM surface (`current-state.md`, `roadmap.md`, `decision-record.md`, and `backlog/`) |
-| `.oat/repo/reviews/`   | Repo-scoped review artifacts (ad-hoc/non-project)                                                                                       |
-| `.oat/repo/archive/`   | Archived repo-level artifacts                                                                                                           |
+| Path                   | Purpose                                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `.oat/repo/knowledge/` | Generated codebase knowledge indexes                                                     |
+| `.oat/repo/pjm/`       | Active operational PJM layer (`current-state.md`, `roadmap.md`, and `backlog/`)          |
+| `.oat/repo/reference/` | Durable append-mostly references, including file-per-record decisions under `decisions/` |
+| `.oat/repo/reviews/`   | Repo-scoped review artifacts (ad-hoc/non-project)                                        |
+| `.oat/repo/archive/`   | Archived repo-level artifacts                                                            |
 
-Canonical project-management repo-reference surface:
+Canonical project-management repo-reference surface splits the active
+operational layer (`pjm/`) from durable references (`reference/`):
 
 ```text
-.oat/repo/reference/
-  current-state.md
-  roadmap.md
-  decision-record.md
-  backlog/
+.oat/repo/
+  AGENTS.md
+  pjm/
+    AGENTS.md
+    current-state.md
+    roadmap.md
+    backlog/
+  reference/
+    AGENTS.md
+    decisions/
 ```
 
+Decisions are file-per-record under `reference/decisions/` (managed with the
+`oat decision` command group), replacing the legacy single
+`reference/decision-record.md`. Repos still on the old single-`reference/`
+layout migrate with `oat pjm migrate`.
+
 ## User scope (`~/.oat/`)
 
 Common user-scope entries: