npm - arreio - Versions diffs - 1.0.4 → 1.1.0 - Mend

arreio 1.0.4 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md CHANGED Viewed

@@ -12,7 +12,15 @@ Install Arreio as a dependency to enable all skills in your workspace:
 npm install arreio
 ```
-The post-install script will automatically copy all Arreio skills to your project's `.agents/skills/` directory, making them available to your AI coding agent. (Note: npm may show an advisory about unallowed install scripts—this is informational and won't block the installation.)
+The post-install script will automatically copy all Arreio skills to your project's `.agents/skills/` directory, making them available to your AI coding agent.
+> **Note on npm 10+ install scripts:** npm 10+ blocks lifecycle scripts by default and will print a warning like `npm warn install-scripts arreio@x.y.z (postinstall: ...)`. The script is not run automatically until you allow it. Run:
+>
+> ```bash
+> npm install-scripts approve arreio
+> ```
+>
+> If you skip the postinstall, run `/arreio-init` in your AI coding agent — it will install the skills for you.
 Then initialize your project to set up the Arreio folder structure and documentation:

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "arreio",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Arreio transforms agentic coding workflows into a predictable, safe, and high-quality software delivery pipeline. Master the four core phases—Plan, Work, Review, Learn—to orchestrate a highly reliable development cycle.",
   "license": "MIT",
   "author": "Wicttor",

package/scripts/postinstall.js CHANGED Viewed

@@ -11,7 +11,11 @@ const path = require('path');
 // Determine the source and destination paths
 const packageDir = path.dirname(__dirname);
 const skillsSource = path.join(packageDir, 'skills');
-const agentsDir = path.join(process.cwd(), '.agents');
+// INIT_CWD is set by npm to the project root during lifecycle scripts.
+// Fallback to process.cwd() for direct/manual runs.
+const projectRoot = process.env.INIT_CWD || process.cwd();
+const agentsDir = path.join(projectRoot, '.agents');
 const skillsDestination = path.join(agentsDir, 'skills');
 // Function to recursively copy directories

package/skills/arreio-init/SKILL.md CHANGED Viewed

@@ -54,7 +54,7 @@ Creates the organizational spine for Arreio artifacts:
 - `docs/plans/` — Stores generated plans and design artifacts
 - `docs/learn/` — Stores extracted learnings and insights
-- `docs/reports/` — Stores review reports and analysis
+- `docs/review/` — Stores review reports and analysis
 - `docs/tasks/` — Stores task lists and execution records
 - `docs/archives/` — Stores historical artifacts
@@ -92,15 +92,7 @@ Creates the organizational spine for Arreio artifacts:
 **Action:** If `docs/learn/index.md` doesn't exist, create it using the [Learn Index Template](references/learn-index-template.md).
-### Step 7: Create Reports Folder
-**Folder:** `docs/reports/`
-**Rationale:** Stores review reports and analysis artifacts. The `review/SKILL.md` module generates reports here.
-**Action:** Create the `docs/reports/` folder if it doesn't exist.
-### Step 8: Create Plan Skill Hidden Artifact Directories
+### Step 7: Create Plan Skill Hidden Artifact Directories
 **Folders:**
@@ -112,7 +104,7 @@ Creates the organizational spine for Arreio artifacts:
 **Action:** Create all three directories if they don't exist.
-### Step 9: Create Work Skill Hidden Artifact Directories
+### Step 8: Create Work Skill Hidden Artifact Directories
 **Folders:**
@@ -125,22 +117,22 @@ Creates the organizational spine for Arreio artifacts:
 **Action:** Create all four directories if they don't exist.
-### Step 10: Create Review Skill Hidden Artifact Directories and Registry
+### Step 9: Create Review Skill Hidden Artifact Directories and Registry
 **Folders:**
-- `docs/plans/.review/.scope/` — Stores Review Scope phase artifacts
-- `docs/plans/.review/.prepare/` — Stores Review Prepare phase artifacts
-- `docs/plans/.review/.analyze/` — Stores Review Analyze phase artifacts
-- `docs/plans/.review/.report/` — Stores Review Report phase artifacts
+- `docs/review/.scope/` — Stores Review Scope phase artifacts
+- `docs/review/.prepare/` — Stores Review Prepare phase artifacts
+- `docs/review/.analyze/` — Stores Review Analyze phase artifacts
+- `docs/review/.report/` — Stores Review Report phase artifacts
 **File:**
-- `docs/plans/.review/index.md` — Central registry of all review reports
+- `docs/review/index.md` — Central registry of all review reports
 **Rationale:** The `review/SKILL.md` orchestrator saves phase artifacts in these hidden directories and maintains a central index of all review reports.
-**Action:** Create all four directories if they don't exist. If `docs/plans/.review/index.md` doesn't exist, create it with a header:
+**Action:** Create all four directories if they don't exist. If `docs/review/index.md` doesn't exist, create it with a header:
 ```markdown
 ---
@@ -161,20 +153,20 @@ This is the index of all review reports for the project. Reports are organized b
 _No review reports yet._
 ```
-### Step 11: Create Learn Skill Hidden Artifact Directories
+### Step 10: Create Learn Skill Hidden Artifact Directories
 **Folders:**
-- `docs/plans/.learn/.capture/` — Stores Capture phase artifacts
-- `docs/plans/.learn/.refine/` — Stores Refine phase artifacts
-- `docs/plans/.learn/.index/` — Stores Index phase artifacts
-- `docs/plans/.learn/.maintain/` — Stores Maintain phase artifacts
+- `docs/learn/.capture/` — Stores Capture phase artifacts
+- `docs/learn/.refine/` — Stores Refine phase artifacts
+- `docs/learn/.index/` — Stores Index phase artifacts
+- `docs/learn/.maintain/` — Stores Maintain phase artifacts
 **Rationale:** The `learn/SKILL.md` orchestrator saves phase artifacts in these hidden directories to preserve the knowledge entry authoring trail.
 **Action:** Create all four directories if they don't exist.
-### Step 12: Create End-Session Skill Hidden Artifact Directory
+### Step 11: Create End-Session Skill Hidden Artifact Directory
 **Folder:**
@@ -184,7 +176,7 @@ _No review reports yet._
 **Action:** Create the directory if it doesn't exist.
-### Step 13: Create Learn Category Folders
+### Step 12: Create Learn Category Folders
 **Folders:**
@@ -208,7 +200,7 @@ After initialization, verify:
   - `.agents/skills/learn/`
   - `.agents/skills/end-session/`
   - `.agents/skills/arreio-init/`
-- ✓ All five core folders exist: `docs/plans/`, `docs/learn/`, `docs/reports/`, `docs/tasks/`, `docs/archives/`
+- ✓ All five core folders exist: `docs/plans/`, `docs/learn/`, `docs/review/`, `docs/tasks/`, `docs/archives/`
 - ✓ `ARCHITECTURE.md` exists at project root
 - ✓ Root-level index files exist:
   - `docs/plans/index.md` (registry of all plans)
@@ -218,10 +210,10 @@ After initialization, verify:
 - ✓ Work skill hidden artifact directories exist:
   - `docs/plans/.work/.triage/`, `docs/plans/.work/.prepare/`, `docs/plans/.work/.execute/`, `docs/plans/.work/.review/`
 - ✓ Review skill hidden artifact directories exist:
-  - `docs/plans/.review/.scope/`, `docs/plans/.review/.prepare/`, `docs/plans/.review/.analyze/`, `docs/plans/.review/.report/`
-  - `docs/plans/.review/index.md` (review reports registry)
+  - `docs/review/.scope/`, `docs/review/.prepare/`, `docs/review/.analyze/`, `docs/review/.report/`
+  - `docs/review/index.md` (review reports registry)
 - ✓ Learn skill hidden artifact directories exist:
-  - `docs/plans/.learn/.capture/`, `docs/plans/.learn/.refine/`, `docs/plans/.learn/.index/`, `docs/plans/.learn/.maintain/`
+  - `docs/learn/.capture/`, `docs/learn/.refine/`, `docs/learn/.index/`, `docs/learn/.maintain/`
 - ✓ End-session skill hidden artifact directory exists:
   - `docs/plans/.end-session/`
 - ✓ Learn category folders exist:
@@ -235,8 +227,8 @@ Downstream skills (plan, learn, work, review) automatically create missing folde
 - **plan** skill creates missing `docs/plans/` core folders, and allocates `docs/plans/.scope/`, `.research/`, `.design/` directories on first use.
 - **work** skill creates missing `docs/plans/.work/` directories (`.triage/`, `.prepare/`, `.execute/`, `.review/`) on first execution.
-- **review** skill creates missing `docs/plans/.review/` directories and `index.md` registry on first review.
-- **learn** skill creates missing `docs/plans/.learn/` directories and `docs/learn/` category folders on first learning capture.
+- **review** skill creates missing `docs/review/` directories and `index.md` registry on first review.
+- **learn** skill creates missing phase-artifact directories under `docs/learn/` and the `docs/learn/` category folders on first learning capture.
 - **end-session** skill creates missing `docs/plans/.end-session/` directory (and the `## Session Ends` section in `docs/plans/index.md`) on first session end.
 **However**, running `arreio-init` upfront provides several benefits:

package/skills/learn/SKILL.md CHANGED Viewed

@@ -49,7 +49,7 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
 - Receives a context object from the user, a saved prompt, a document, or a combination.
 - **Three input shapes:**
   1. **Explicit** — `/learn <type> <text>`. Capture drafts an entry of the named type from the text. The canonical path for authoring a decision/pattern/gotcha/workflow.
-  2. **Candidate** — `/learn <candidate-ref>`. The ref resolves to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/plans/.review/.report/<id>.md`); Capture reads its `learnings-to-capture` list and, for each candidate, drafts the corresponding entry. The user confirms which candidates become durable entries.
+  2. **Candidate** — `/learn <candidate-ref>`. The ref resolves to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/review/.report/<id>.md`); Capture reads its `learnings-to-capture` list and, for each candidate, drafts the corresponding entry. The user confirms which candidates become durable entries.
   3. **Maintain** — `/learn maintain`. Runs only the Maintain phase (dedup / refresh / prune); bypasses Capture → Refine → Index (no new entry is authored).
 - **If no context is provided**, ask: "What would you like to capture? Provide a type and text, a candidate ref, or `maintain`."
 - **Unified key:** downstream phases key off a `learn-id` umbrella (`YYYY-MM-DD-NNN`), allocated by Capture. For Maintain-only runs, Maintain allocates its own `maintain-id` (no `learn-id` umbrella — there is no newly authored entry).
@@ -60,7 +60,7 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
 Before starting the learn pipeline, the orchestrator verifies that required folders exist:
 - `docs/learn/` — must exist for writing entries and the index; the seed `docs/learn/index.md` must exist (empty `entries:` block is valid — the legacy migration populates 28 entries)
-- `docs/plans/.learn/.capture/`, `docs/plans/.learn/.refine/`, `docs/plans/.learn/.index/`, `docs/plans/.learn/.maintain/` — must exist for saving the phase artifacts
+- `docs/learn/.capture/`, `docs/learn/.refine/`, `docs/learn/.index/`, `docs/learn/.maintain/` — must exist for saving the phase artifacts
 **Self-Healing:** If any are missing, the orchestrator automatically creates them (`mkdir -p`), and seeds `docs/learn/index.md` from the [index-format.md](references/index-format.md) template. This allows the Learn skill to run even if `arreio-init` wasn't explicitly run.
@@ -70,10 +70,10 @@ For **explicit** input, verify `<type>` is one of the four; if not, ask to pick
 | Phase | Phase Module                          | Output Artifact                                                              | Saved to                               |
 | ----- | ------------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------- |
-| 1     | [Capture](modules/capture.md)        | [Captured entry](references/templates/artifacts/captured-entry.md)           | `docs/plans/.learn/.capture/<id>.md`   |
-| 2     | [Refine](modules/refine.md)          | [Refined entry](references/templates/artifacts/refined-entry.md)             | `docs/plans/.learn/.refine/<id>.md`    |
-| 3     | [Index](modules/index.md)            | [Index update](references/templates/artifacts/index-update.md)               | `docs/plans/.learn/.index/<id>.md`     |
-| 4     | [Maintain](modules/maintain.md) _(on demand)_ | [Maintain log](references/templates/artifacts/maintain-log.md)   | `docs/plans/.learn/.maintain/<id>.md`  |
+| 1     | [Capture](modules/capture.md)        | [Captured entry](references/templates/artifacts/captured-entry.md)           | `docs/learn/.capture/<id>.md`   |
+| 2     | [Refine](modules/refine.md)          | [Refined entry](references/templates/artifacts/refined-entry.md)             | `docs/learn/.refine/<id>.md`    |
+| 3     | [Index](modules/index.md)            | [Index update](references/templates/artifacts/index-update.md)               | `docs/learn/.index/<id>.md`     |
+| 4     | [Maintain](modules/maintain.md) _(on demand)_ | [Maintain log](references/templates/artifacts/maintain-log.md)   | `docs/learn/.maintain/<id>.md`  |
 **Phase 4 is on-demand.** A normal `/learn <type> <text>` run executes Phases 1–3 and writes one entry; Maintain runs only via `/learn maintain`. The migration procedure (legacy → canonical) is a Maintain operation, run once.
@@ -104,7 +104,7 @@ The **Index phase** is the skill's only index writer for authored entries; the *
 - **Entry file:** Saved to `docs/learn/<type>/<slug>.md` with the [entry-schema.md](references/entry-schema.md) frontmatter (`type`, `domain`, `tags`, `applicability`, `summary`, plus `created_at`/`updated_at`, `source`, `confidence`, and `related`).
 - **Index:** `docs/learn/index.md` updated — a YAML `entries:` block (the `filename` / `domain` / `tags` / `applicability` / `summary` record per entry — the **read contract** that Plan/Work/Review's [learnings-gate-logic.md](../plan/references/learnings-gate-logic.md) parses) plus the human-readable By Category / By Domain tables.
-- **Maintain Log (if `/learn maintain`):** Saved to `docs/plans/.learn/.maintain/<maintain-id>.md`, recording the dedup/refresh/prune operations performed and any migration applied.
+- **Maintain Log (if `/learn maintain`):** Saved to `docs/learn/.maintain/<maintain-id>.md`, recording the dedup/refresh/prune operations performed and any migration applied.
 - **Not produced:** This skill produces **no session log, no event transcript, no "what we did."** Only durable entries and the index.
 ## References

package/skills/learn/modules/capture.md CHANGED Viewed

@@ -30,7 +30,7 @@ If the input is empty or ambiguous, ask the user one question: "What would you l
 Determine which of the two authoring shapes applies (maintain is rejected in Step 0):
 1. **Explicit** — the input carries a `<type>` (one of `decision` / `pattern` / `gotcha` / `workflow`) and `<text>` (prose, a file/commit ref, or a short description to expand).
-2. **Candidate** — the input carries a ref to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/plans/.review/.report/<id>.md`).
+2. **Candidate** — the input carries a ref to a Work `review-id` (`docs/plans/.work/.review/<id>.md`) or a Review `report-id` (`docs/review/.report/<id>.md`).
 Record `input-shape: explicit | candidate`. If `<type>` is provided but is not one of the four, ask the user to pick from the four (Step 2 confirms intent either way).
@@ -48,7 +48,7 @@ Capture produces **one** Captured Entry per run (single-shape artifact). The sha
 1. Resolve the ref to the artifact file:
    - Work `review-id` → `docs/plans/.work/.review/<review-id>.md` → read its `learnings-to-capture` list.
-   - Review `report-id` → `docs/plans/.review/.report/<report-id>.md` → read its `learnings-to-capture` list.
+   - Review `report-id` → `docs/review/.report/<report-id>.md` → read its `learnings-to-capture` list.
 2. If the list is empty, inform the user (no candidates to curate) and stop — do not fabricate an entry.
 3. Present the candidate list to the user (each has a `title`, `domain`, `source` {finding-id or task-id+gate}, `summary`, `type`) and ask which to author **first** (one entry per Captured Entry). If the candidate's recorded `type` is one of the four, use it; otherwise map: `confirmed-pattern` → `pattern`, `refuted-assumption` → `gotcha`, `gotcha` → `gotcha`, `forced-decision` → `decision`. The user may override the inferred type.
 4. Record the selected candidate as `capture.source-candidate` (carried for traceability into the entry's `source` frontmatter).
@@ -70,8 +70,8 @@ Draft the entry's frontmatter and body per the authoritative write contract **[e
 ### Step 4: Propose slug and Allocate the learn-id Umbrella
 1. **Propose a `slug`** — a kebab-case, globally-unique stable key for the entry. Derive from the title (concise, descriptive); for time-bound decisions a date suffix is allowed (`critical-risk-tier-security-payments-2026-07-04`). The slug is the upsert key for the entry file and its index record. Refine checks uniqueness; Capture only **proposes**.
-2. **Allocate a `learn-id`** umbrella of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/plans/.learn/.capture/YYYY-MM-DD-NNN-capture.md` files for today. The `learn-id` is the pipeline umbrella carried through Capture → Refine → Index (Maintain-only runs allocate their own `maintain-id` and have no `learn-id`).
-3. **Assign a `capture-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-capture`, saved to `docs/plans/.learn/.capture/`). Reuse it if the user later picks **Edit & Retry**.
+2. **Allocate a `learn-id`** umbrella of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/learn/.capture/YYYY-MM-DD-NNN-capture.md` files for today. The `learn-id` is the pipeline umbrella carried through Capture → Refine → Index (Maintain-only runs allocate their own `maintain-id` and have no `learn-id`).
+3. **Assign a `capture-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-capture`, saved to `docs/learn/.capture/`). Reuse it if the user later picks **Edit & Retry**.
 ### Step 5: Generate the Captured Entry Artifact
@@ -95,7 +95,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
-Then save the artifact to `docs/plans/.learn/.capture/<capture-id>.md` (ensure `interactionMode` and `target-type` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Refine).
+Then save the artifact to `docs/learn/.capture/<capture-id>.md` (ensure `interactionMode` and `target-type` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Refine).
 ## Output: Captured Entry Artifact
@@ -103,6 +103,6 @@ Then save the artifact to `docs/plans/.learn/.capture/<capture-id>.md` (ensure `
 - Verify that `target-type` is one of `decision` / `pattern` / `gotcha` / `workflow`.
 - Verify that the frontmatter and body conform to [entry-schema.md](../references/entry-schema.md) (the per-type section template), without re-encoding the schema inline.
 - Verify that the `learn-id` umbrella was allocated (Capture is the allocating phase) and the `slug` is kebab-case and descriptive.
-- Verify that the artifact is saved to `docs/plans/.learn/.capture/<capture-id>.md`.
+- Verify that the artifact is saved to `docs/learn/.capture/<capture-id>.md`.
 > Pass the Captured Entry to `refine` (Phase 2) for type/frontmatter validation and the duplicate + analog check against existing entries.

package/skills/learn/modules/index.md CHANGED Viewed

@@ -55,7 +55,7 @@ Update `docs/learn/index.md` per the authoritative **[index-format.md](../refere
 ### Step 4: Allocate the index-id
-Assign an `index-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-index`, saved to `docs/plans/.learn/.index/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
+Assign an `index-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-index`, saved to `docs/learn/.index/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
 ### Step 5: Generate the Index Update Artifact
@@ -79,7 +79,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
-Then save the artifact to `docs/plans/.learn/.index/<index-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the authoring run complete — the durable entry now lives at `docs/learn/<type>/<slug>.md` and `docs/learn/index.md` reflects it.
+Then save the artifact to `docs/learn/.index/<index-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the authoring run complete — the durable entry now lives at `docs/learn/<type>/<slug>.md` and `docs/learn/index.md` reflects it.
 ## Output: Index Update Artifact
@@ -89,6 +89,6 @@ Then save the artifact to `docs/plans/.learn/.index/<index-id>.md` (ensure `inte
 - Verify **index coherence** (orchestrator gate #5): the YAML block length matches the on-disk entry-file count; the per-type count headings match; no duplicate index rows.
 - Verify that a merge **de-indexed** (not deleted) the analog and recorded the `superseded-by` lineage in the analog's file — lineage preserved per [dedup-rules.md](../references/dedup-rules.md).
 - Verify that the derived `index-applicability` enum was **read from** [index-format.md](../references/index-format.md) (the derivation rule) rather than re-encoded inline.
-- Verify that the artifact is saved to `docs/plans/.learn/.index/<index-id>.md`.
+- Verify that the artifact is saved to `docs/learn/.index/<index-id>.md`.
 > The Index Update is the authoring run's final artifact. The Orchestrator marks the workflow complete; the durable knowledge entry lives at `docs/learn/<type>/<slug>.md` and is discoverable via `docs/learn/index.md` (the source-of-truth index Plan/Work/Review search).

package/skills/learn/modules/maintain.md CHANGED Viewed

@@ -74,7 +74,7 @@ Rebuild `docs/learn/index.md` from the on-disk file tree — the file tree is th
 ### Step 6: Allocate the maintain-id
-Assign a `maintain-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-maintain`, saved to `docs/plans/.learn/.maintain/`). Maintain has **no `learn-id` umbrella** (it authors no new entry). Reuse the `maintain-id` if the user picks **Edit & Retry**.
+Assign a `maintain-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-maintain`, saved to `docs/learn/.maintain/`). Maintain has **no `learn-id` umbrella** (it authors no new entry). Reuse the `maintain-id` if the user picks **Edit & Retry**.
 ### Step 7: Generate the Maintain Log Artifact
@@ -101,7 +101,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed (but destructive operations — migration, prune, merge — always surface for confirmation even in Smart, per the principle that destructive writes are never silent).
 - **Autopilot:** auto-proceed for non-destructive steps (refresh, rebuild); **still pause** for destructive operations (migration, prune) — Autopilot never silently deletes or rewrites paths.
-Then save the artifact to `docs/plans/.learn/.maintain/<maintain-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the Maintain run complete — the canonical knowledge base is reconciled.
+Then save the artifact to `docs/learn/.maintain/<maintain-id>.md` (ensure `interactionMode` included) and return it to the Orchestrator. The Orchestrator marks the Maintain run complete — the canonical knowledge base is reconciled.
 ## Output: Maintain Log Artifact
@@ -111,6 +111,6 @@ Then save the artifact to `docs/plans/.learn/.maintain/<maintain-id>.md` (ensure
 - Verify that every prune was explicitly confirmed (no silent deletion); a delete leaves no file; a de-index keeps the file with `status: obsolete`.
 - Verify **index coherence** (orchestrator gate #5): the rebuilt `docs/learn/index.md` YAML length matches the on-disk entry-file count; per-type totals consistent; no duplicate rows.
 - Verify that the rebuild was **applied from** [index-format.md](../references/index-format.md) (and the applicability-enum derivation) rather than re-encoded inline.
-- Verify that the artifact is saved to `docs/plans/.learn/.maintain/<maintain-id>.md`.
+- Verify that the artifact is saved to `docs/learn/.maintain/<maintain-id>.md`.
 > The Maintain Log is the Maintain run's deliverable. The Orchestrator marks the workflow complete; the canonical knowledge base at `docs/learn/` is reconciled and `docs/learn/index.md` reflects the on-disk truth.

package/skills/learn/modules/refine.md CHANGED Viewed

@@ -65,7 +65,7 @@ Record the matches (`dup-status: exact | analog | none`, the matched `slug`/file
 ### Step 4: Allocate the refine-id
-Assign a `refine-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-refine`, saved to `docs/plans/.learn/.refine/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
+Assign a `refine-id` per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-refine`, saved to `docs/learn/.refine/`). Reuse it if the user later picks **Edit & Retry**. The `learn-id` umbrella is inherited unchanged.
 ### Step 5: Generate the Refined Entry Artifact
@@ -91,7 +91,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
-Then save the artifact to `docs/plans/.learn/.refine/<refine-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Index).
+Then save the artifact to `docs/learn/.refine/<refine-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Index).
 ## Output: Refined Entry Artifact
@@ -99,6 +99,6 @@ Then save the artifact to `docs/plans/.learn/.refine/<refine-id>.md` (ensure `in
 - Verify that the frontmatter conforms to [entry-schema.md](../references/entry-schema.md) (every required field valid; the per-type body template present) without re-encoding the schema inline.
 - Verify that the duplicate/analog check ran per [dedup-rules.md](../references/dedup-rules.md) and that any conflict was resolved with a recorded `resolution` (never silently two entries).
 - Verify that a merge recorded `lineage` (the analog `slug` + `superseded-by` note) — lineage preserved, never deleted.
-- Verify that the artifact is saved to `docs/plans/.learn/.refine/<refine-id>.md`.
+- Verify that the artifact is saved to `docs/learn/.refine/<refine-id>.md`.
 > Pass the Refined Entry to `index` (Phase 3) to write the entry file and upsert the canonical index.

package/skills/learn/references/id-generation.md CHANGED Viewed

@@ -14,10 +14,10 @@ Shared ID algorithm for the `capture`, `refine`, `index`, and `maintain` phases,
 | Phase    | ID format                            | Saved to                            |
 | -------- | ----------------------------------- | ----------------------------------- |
-| Capture  | `YYYY-MM-DD-NNN-capture`            | `docs/plans/.learn/.capture/<id>.md`   |
-| Refine   | `YYYY-MM-DD-NNN-refine`             | `docs/plans/.learn/.refine/<id>.md`    |
-| Index    | `YYYY-MM-DD-NNN-index`              | `docs/plans/.learn/.index/<id>.md`     |
-| Maintain | `YYYY-MM-DD-NNN-maintain`           | `docs/plans/.learn/.maintain/<id>.md`  |
+| Capture  | `YYYY-MM-DD-NNN-capture`            | `docs/learn/.capture/<id>.md`   |
+| Refine   | `YYYY-MM-DD-NNN-refine`             | `docs/learn/.refine/<id>.md`    |
+| Index    | `YYYY-MM-DD-NNN-index`              | `docs/learn/.index/<id>.md`     |
+| Maintain | `YYYY-MM-DD-NNN-maintain`           | `docs/learn/.maintain/<id>.md`  |
 `learn-id` (see below) is the umbrella shared across Capture → Refine → Index. **Maintain has no `learn-id`** — it authors no new entry; it allocates only a standalone `maintain-id`.
@@ -27,7 +27,7 @@ Allocated **only in Capture** Step 4:
 ```
 1. Get the current date in UTC
-2. List existing files under docs/plans/.learn/.capture/ matching YYYY-MM-DD-NNN-capture.md for that date
+2. List existing files under docs/learn/.capture/ matching YYYY-MM-DD-NNN-capture.md for that date
 3. NNN = (highest existing NNN for that date), zero-padded to 3 digits
    - if none exist for that date, start at 001
 4. learn-id = "<date>-<NNN>"  (the same NNN as the capture-id being allocated)
@@ -42,7 +42,7 @@ Allocated **only in Maintain** Step 6:
 ```
 1. Get the current date in UTC
-2. List existing files under docs/plans/.learn/.maintain/ matching YYYY-MM-DD-NNN-maintain.md for that date
+2. List existing files under docs/learn/.maintain/ matching YYYY-MM-DD-NNN-maintain.md for that date
 3. NNN = (count + 1), zero-padded to 3 digits
 4. maintain-id = "<date>-<NNN>-maintain"
 ```
@@ -74,10 +74,10 @@ The `slug` is the stable, globally-unique key for a knowledge entry — it keys
 ```
 1. Get the current date in UTC (e.g., 2026-08-08)
 2. List existing files for today in the phase's save directory:
-   - capture  -> docs/plans/.learn/.capture/  matching YYYY-MM-DD-*-capture.md
-   - refine   -> docs/plans/.learn/.refine/   matching YYYY-MM-DD-*-refine.md
-   - index    -> docs/plans/.learn/.index/    matching YYYY-MM-DD-*-index.md
-   - maintain -> docs/plans/.learn/.maintain/ matching YYYY-MM-DD-*-maintain.md
+   - capture  -> docs/learn/.capture/  matching YYYY-MM-DD-*-capture.md
+   - refine   -> docs/learn/.refine/   matching YYYY-MM-DD-*-refine.md
+   - index    -> docs/learn/.index/    matching YYYY-MM-DD-*-index.md
+   - maintain -> docs/learn/.maintain/ matching YYYY-MM-DD-*-maintain.md
 3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
 4. id = "<date>-<NNN>-<phase>"
 ```
@@ -108,7 +108,7 @@ The legacy `docs/learnings/` store uses filenames, not slugs, as the key. The mi
 ## Notes
-- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan`, `/work`, and `/review`; the Learn skill's counters are independent from those skills (separate save directories under `docs/plans/.learn/`).
+- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan`, `/work`, and `/review`; the Learn skill's counters are independent from those skills (separate save directories under `docs/learn/`).
 - `learn-id` carries through Capture → Refine → Index; Maintain uses the standalone `maintain-id` only. Cross-phase chaining is `capture-id → refine-id → index-id`, all sharing one `learn-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
 - The `slug` is a **separate** key from the phase ids — it identifies the durable knowledge entry across re-authors, not the pipeline run. A single `slug` may be authored by many `learn-id` runs over time (each upsert overwrites); the `slug` is stable, the `learn-id` is per-run.
 - Counter collisions are impossible within a date because each phase writes to its own directory and recomputes the count from the directory listing.

package/skills/learn/references/templates/artifacts/captured-entry.md CHANGED Viewed

@@ -53,7 +53,7 @@ inferred: true | false                     # true when drafted from a short desc
                                            # false when grounded in a concrete ref/file the user provided
 ```
-Also save the Captured Entry Artifact to `docs/plans/.learn/.capture/<capture-id>.md`.
+Also save the Captured Entry Artifact to `docs/learn/.capture/<capture-id>.md`.
 ## Validation Rules

package/skills/learn/references/templates/artifacts/index-update.md CHANGED Viewed

@@ -50,7 +50,7 @@ entry-written: true                           # the entry file was written (fals
 index-updated: true                           # docs/learn/index.md was upserted
 ```
-Also save the Index Update Artifact to `docs/plans/.learn/.index/<index-id>.md`.
+Also save the Index Update Artifact to `docs/learn/.index/<index-id>.md`.
 ## Validation Rules

package/skills/learn/references/templates/artifacts/learn-input.md CHANGED Viewed

@@ -95,6 +95,6 @@ maintain:
 ## Notes
-- The Orchestrator's Pre-Flight Check ensures `docs/learn/`, `docs/plans/.learn/.{capture,refine,index,maintain}/` exist, and seeds `docs/learn/index.md` if missing (self-healing via `mkdir -p`), before routing the artifact.
+- The Orchestrator's Pre-Flight Check ensures `docs/learn/`, `docs/learn/.{capture,refine,index,maintain}/` exist, and seeds `docs/learn/index.md` if missing (self-healing via `mkdir -p`), before routing the artifact.
 - `interactionMode` flows from this artifact into every downstream artifact (Capture → Refine → Index for authoring; straight to Maintain otherwise); the orchestrator quality gate #2 cross-checks it is identical across the authoring chain (Maintain carries it standalone).
 - The shape **determines the route**, not just the allocation: a `maintain` shape never reaches Capture, Refine, or Index. The phase ids reflect this — `maintain-id` is standalone (no `learn-id` umbrella) per [id-generation.md](../../id-generation.md).

package/skills/learn/references/templates/artifacts/maintain-log.md CHANGED Viewed

@@ -56,7 +56,7 @@ summary:                                    # a one-line human-readable summary
   "<N> entries migrated; <M> merged; <R> normalized, <F> flagged; <P> pruned; <I> indexed"
 ```
-Also save the Maintain Log Artifact to `docs/plans/.learn/.maintain/<maintain-id>.md`.
+Also save the Maintain Log Artifact to `docs/learn/.maintain/<maintain-id>.md`.
 ## Validation Rules

package/skills/learn/references/templates/artifacts/refined-entry.md CHANGED Viewed

@@ -58,7 +58,7 @@ lineage:                                        # set ONLY when resolution == me
 source-candidate: <carried from Capture> | null
 ```
-Also save the Refined Entry Artifact to `docs/plans/.learn/.refine/<refine-id>.md`.
+Also save the Refined Entry Artifact to `docs/learn/.refine/<refine-id>.md`.
 ## Validation Rules

package/skills/review/SKILL.md CHANGED Viewed

@@ -58,8 +58,8 @@ Each phase runs sequentially: the orchestrator calls the phase module, receives
 Before starting the review pipeline, the orchestrator verifies that required folders exist:
-- `docs/plans/.review/.scope/`, `docs/plans/.review/.prepare/`, `docs/plans/.review/.analyze/`, `docs/plans/.review/.report/` — must exist for saving the four phase artifacts
-- `docs/plans/.review/index.md` — must exist as the review registry (Report appends to it)
+- `docs/review/.scope/`, `docs/review/.prepare/`, `docs/review/.analyze/`, `docs/review/.report/` — must exist for saving the four phase artifacts
+- `docs/review/index.md` — must exist as the review registry (Report appends to it)
 **Self-Healing:** If any are missing, the orchestrator automatically creates them (`mkdir -p`, and a seed `index.md` with a registry header). This allows the Review skill to run even if `arreio-init` wasn't explicitly run.
@@ -73,10 +73,10 @@ For **task-in-review** input, verify the `work-id` exists and contains at least
 | Phase | Phase Module                  | Output Artifact                                                  | Saved to                              |
 | ----- | ----------------------------- | ---------------------------------------------------------------- | ------------------------------------- |
-| 1     | [Scope](modules/scope.md)     | [Review scope](references/templates/artifacts/review-scope.md)   | `docs/plans/.review/.scope/<id>.md`   |
-| 2     | [Prepare](modules/prepare.md) | [Review kit](references/templates/artifacts/review-kit.md)       | `docs/plans/.review/.prepare/<id>.md` |
-| 3     | [Analyze](modules/analyze.md) | [Findings](references/templates/artifacts/findings.md)           | `docs/plans/.review/.analyze/<id>.md` |
-| 4     | [Report](modules/report.md)   | [Review report](references/templates/artifacts/review-report.md) | `docs/plans/.review/.report/<id>.md`  |
+| 1     | [Scope](modules/scope.md)     | [Review scope](references/templates/artifacts/review-scope.md)   | `docs/review/.scope/<id>.md`   |
+| 2     | [Prepare](modules/prepare.md) | [Review kit](references/templates/artifacts/review-kit.md)       | `docs/review/.prepare/<id>.md` |
+| 3     | [Analyze](modules/analyze.md) | [Findings](references/templates/artifacts/findings.md)           | `docs/review/.analyze/<id>.md` |
+| 4     | [Report](modules/report.md)   | [Review report](references/templates/artifacts/review-report.md) | `docs/review/.report/<id>.md`  |
 ### Quality Gates
@@ -99,7 +99,7 @@ Each phase is responsible for its own index updates:
 | Scope   | _(none — produces artifact only)_                                      | Allocates the `review-id`; no index write.                                                                                     |
 | Prepare | _(none)_                                                               | Gathers the review kit; no index write.                                                                                        |
 | Analyze | _(none)_                                                               | Produces findings; no index write.                                                                                             |
-| Report  | `docs/plans/.review/index.md`                                          | Append a registry row: `<report-id>`, review target summary, approval status, link to the report file.                         |
+| Report  | `docs/review/index.md`                                          | Append a registry row: `<report-id>`, review target summary, approval status, link to the report file.                         |
 | Report  | `docs/tasks/<work-id>/index.md` _(work-linked or task-in-review only)_ | Append a distinct `## Review Report — <report-id>` block (separate from Work's own `## Work Report` block).                    |
 | Report  | Task frontmatter _(task-in-review only)_                               | Update task file `status:` field to `completed` (if approved) or `blocked` (if changes-requested, with reason in frontmatter). |
@@ -107,8 +107,8 @@ Each phase is responsible for its own index updates:
 ### FINAL OUTPUT
-- **Review Report:** Saved to `docs/plans/.review/.report/<report-id>.md`, with: the change boundary, the approval status (`approved` / `changes-requested` / `rejected`), the graded findings rollup, recommendations, and (when requirements were available) the scope-creep summary.
-- **Registry row:** `docs/plans/.review/index.md` updated with the new review.
+- **Review Report:** Saved to `docs/review/.report/<report-id>.md`, with: the change boundary, the approval status (`approved` / `changes-requested` / `rejected`), the graded findings rollup, recommendations, and (when requirements were available) the scope-creep summary.
+- **Registry row:** `docs/review/index.md` updated with the new review.
 - **(Work-linked or task-in-review only) Index cross-link:** `docs/tasks/<work-id>/index.md` gets a `## Review Report — <report-id>` block so a future glance at the work index shows that an external Review ran over it.
 - **(Task-in-review only) Task Status Update:** ✅ **NEW**: For each task with `status: for-review`:
   - If approval status = `approved` → update task file's frontmatter `status: completed`

package/skills/review/modules/analyze.md CHANGED Viewed

@@ -69,7 +69,7 @@ Tools never **create** a finding on their own outside the change boundary; they
 ### Step 5: Aggregate Tallies and Generate the Findings Artifact
 1. **Aggregate** findings by category and count by severity. Compute preliminary tallies (Report derives the final approval status from these — Analyze does not pre-derive approval).
-2. **Assign an `analyze-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-analyze`, saved to `docs/plans/.review/.analyze/`). Reuse it if the user later picks **Edit & Retry**.
+2. **Assign an `analyze-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-analyze`, saved to `docs/review/.analyze/`). Reuse it if the user later picks **Edit & Retry**.
 3. Produce a **Findings** block (as markdown) following the schema in [findings.md](../references/templates/artifacts/findings.md). Include:
    - `analyze-id`, inherited `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`
    - the findings list: per finding — `id`, `severity`, `category`, `location` (repository-relative `file:line` or `file:hunk`), `message`, `trace` **or** `scope-creep: true`, and an optional non-binding `suggested-fix` (Review is read-only — suggestions are informational, never applied)
@@ -90,7 +90,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
-Then save the artifact to `docs/plans/.review/.analyze/<analyze-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Report).
+Then save the artifact to `docs/review/.analyze/<analyze-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 4 (Report).
 ## Output: Findings Artifact
@@ -99,6 +99,6 @@ Then save the artifact to `docs/plans/.review/.analyze/<analyze-id>.md` (ensure
 - Verify the **scope-creep** category either ran (with `spec-content` not `none`) or is recorded `skipped (no requirements)` — never silently absent, never inventing requirements.
 - Verify severities were **assigned from** [severity-rubric.md](../references/severity-rubric.md) rather than re-defined inline (no second rubric contradicting the authoritative reference).
 - Verify the category checks were **run from** [review-categories.md](../references/review-categories.md) rather than re-encoded inline.
-- Verify that the artifact is saved to `docs/plans/.review/.analyze/<analyze-id>.md`.
+- Verify that the artifact is saved to `docs/review/.analyze/<analyze-id>.md`.
 > Pass the Findings to `report` (Phase 4) for the approval-status derivation, the report write, and the registry / work-index cross-link.

package/skills/review/modules/prepare.md CHANGED Viewed

@@ -68,7 +68,7 @@ If **no** linter/type-checker is configured for the repo, that is a Smart pause
 ### Step 5: Generate the Review Kit Artifact
-1. **Assign a `prepare-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-prepare`, saved to `docs/plans/.review/.prepare/`). Reuse it if the user later picks **Edit & Retry**.
+1. **Assign a `prepare-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-prepare`, saved to `docs/review/.prepare/`). Reuse it if the user later picks **Edit & Retry**.
 2. Produce a **Review Kit** block (as markdown) following the schema in [review-kit.md](../references/templates/artifacts/review-kit.md). Include:
    - `prepare-id`, inherited `scope-id` and `review-id`, `input-shape`, `interactionMode`
@@ -90,7 +90,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
-Then save the artifact to `docs/plans/.review/.prepare/<prepare-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Analyze).
+Then save the artifact to `docs/review/.prepare/<prepare-id>.md` (ensure `interactionMode` included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 3 (Analyze).
 ## Output: Review Kit Artifact
@@ -98,6 +98,6 @@ Then save the artifact to `docs/plans/.review/.prepare/<prepare-id>.md` (ensure
 - Verify that every `required` file has a diff entry (or is recorded as deleted / `current-contents`) and that `context` is separated from `required`.
 - Verify that `test-context` records covering tests per changed file and whether the change ships its own tests.
 - Verify that `requirements-source: none` propagated as `spec: none` (so Analyze skips the requirements-vs-scope-creep category rather than guessing).
-- Verify that the artifact is saved to `docs/plans/.review/.prepare/<prepare-id>.md`.
+- Verify that the artifact is saved to `docs/review/.prepare/<prepare-id>.md`.
 > Pass the Review Kit to `analyze` (Phase 3) for the categorized, severity-graded review of the diffs.

package/skills/review/modules/report.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 title: Report
-description: Fourth and final step in the Review workflow. Derives the final approval status (approved / changes-requested / rejected) from the Findings per the authoritative approval criteria, composes non-binding recommendations, generates the Review Report, registers it in docs/plans/.review/index.md, and (work-linked only) appends a distinct ## Review Report — <report-id> block to the work task index. Returns the Review Report as the Review skill's final deliverable.
+description: Fourth and final step in the Review workflow. Derives the final approval status (approved / changes-requested / rejected) from the Findings per the authoritative approval criteria, composes non-binding recommendations, generates the Review Report, registers it in docs/review/index.md, and (work-linked only) appends a distinct ## Review Report — <report-id> block to the work task index. Returns the Review Report as the Review skill's final deliverable.
 type: module
 version: 1.0
 timestamp: "2026-08-08"
@@ -8,7 +8,7 @@ timestamp: "2026-08-08"
 # Phase 4 - Report
-**Purpose:** Fourth and final step in the Review workflow. Reads the [Findings](../references/templates/artifacts/findings.md) from Analyze, derives the final **approval status** (`approved` / `changes-requested` / `rejected`) per the authoritative criteria, composes non-binding recommendations, writes the [Review Report](../references/templates/artifacts/review-report.md), registers it in `docs/plans/.review/index.md`, and — for work-linked input only — appends a distinct `## Review Report — <report-id>` block to `docs/tasks/<work-id>/index.md` (clearly separate from Work's own `## Work Report` block). Returns the Review Report as the Review skill's final deliverable.
+**Purpose:** Fourth and final step in the Review workflow. Reads the [Findings](../references/templates/artifacts/findings.md) from Analyze, derives the final **approval status** (`approved` / `changes-requested` / `rejected`) per the authoritative criteria, composes non-binding recommendations, writes the [Review Report](../references/templates/artifacts/review-report.md), registers it in `docs/review/index.md`, and — for work-linked input only — appends a distinct `## Review Report — <report-id>` block to `docs/tasks/<work-id>/index.md` (clearly separate from Work's own `## Work Report` block). Returns the Review Report as the Review skill's final deliverable.
 ## Workflow
@@ -44,7 +44,7 @@ Derive the status deterministically from the tallies (count of `blocker`/`major`
 ### Step 3: Generate the Review Report Artifact
-1. **Assign a `report-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-report`, saved to `docs/plans/.review/.report/`). Reuse it if the user later picks **Edit & Retry**.
+1. **Assign a `report-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-report`, saved to `docs/review/.report/`). Reuse it if the user later picks **Edit & Retry**.
 2. Produce a **Review Report** block (as markdown) following the schema in [review-report.md](../references/templates/artifacts/review-report.md). Include:
    - `report-id`, inherited `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`
@@ -57,10 +57,10 @@ Derive the status deterministically from the tallies (count of `blocker`/`major`
 ### Step 4: Register in the Review Registry
-Append a registry row to `docs/plans/.review/index.md`:
+Append a registry row to `docs/review/index.md`:
 ```
-- <report-id> — <target-summary> — <approval-status> — docs/plans/.review/.report/<report-id>.md
+- <report-id> — <target-summary> — <approval-status> — docs/review/.report/<report-id>.md
 ```
 Create the index with a registry header (`# Reviews`) if it does not yet exist. The row is **idempotent on `report-id`**: a re-run overwrites the row with the same id, never duplicates it.
@@ -76,7 +76,7 @@ When `input-shape: work-linked`, append a **distinct** status block to `docs/tas
 - **Findings:** <blocker> blocker, <major> major, <minor> minor, <nit> nit
 - **Scope creep:** none | <count> | skipped (no requirements)
 - **Learnings to capture:** <count> (run `/learn` to persist)
-- **Review Report:** docs/plans/.review/.report/<report-id>.md
+- **Review Report:** docs/review/.report/<report-id>.md
 ```
 The block is **append-only** and **idempotent on `report-id`** (a re-run overwrites the block with the same id, never duplicates it). If the work index does not exist, skip the cross-link and note it in the report (do not fabricate a work index).
@@ -92,7 +92,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
-Then save the artifact to `docs/plans/.review/.report/<report-id>.md` (ensure `interactionMode` included).
+Then save the artifact to `docs/review/.report/<report-id>.md` (ensure `interactionMode` included).
 ### Step 7: Return to Orchestrator
@@ -103,7 +103,7 @@ Return the Review Report to the Orchestrator — `path`, `report-id`, `review-id
 - Verify that the Review Report is complete and valid: `report-id`, `analyze-id`, `prepare-id`, `scope-id`, `review-id`, `input-shape`, `interactionMode`, `approval-status`, the findings rollup, `recommendations`, `scope-creep-summary`, and `learnings-to-capture`.
 - Verify that **findings coherence** held (re-verified in Step 0): every finding has a severity, category, repo-relative location, and a `trace` or `scope-creep: true`.
 - Verify that the approval status was **derived from** [approval-criteria.md](../references/approval-criteria.md) rather than re-defined inline (no second rule contradicting the authoritative reference).
-- Verify the registry row was appended to `docs/plans/.review/index.md` (idempotent on `report-id`), and — for work-linked input — the distinct `## Review Report — <report-id>` block was appended to `docs/tasks/<work-id>/index.md` (idempotent, never colliding with Work's `## Work Report` block).
-- Verify that the artifact is saved to `docs/plans/.review/.report/<report-id>.md`.
+- Verify the registry row was appended to `docs/review/index.md` (idempotent on `report-id`), and — for work-linked input — the distinct `## Review Report — <report-id>` block was appended to `docs/tasks/<work-id>/index.md` (idempotent, never colliding with Work's `## Work Report` block).
+- Verify that the artifact is saved to `docs/review/.report/<report-id>.md`.
 > The Review Report is the primary deliverable of the Review Skill. The Orchestrator marks the workflow complete; optionally chains to `/learn` when learnings were surfaced.

package/skills/review/modules/scope.md CHANGED Viewed

@@ -89,9 +89,9 @@ Search `docs/learn/index.md` for entries relevant to the review domains (the cha
 ### Step 6: Allocate review-id and Generate the Review Scope Artifact
-1. **Allocate a `review-id`** of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/plans/.review/.scope/YYYY-MM-DD-NNN-scope.md` files (or registry rows) for today. This is the pipeline umbrella id (distinct from any Work `review-id` for work-linked input — the two skills produce independent artifacts; the `work-id` is carried alongside for traceability).
+1. **Allocate a `review-id`** of the form `YYYY-MM-DD-NNN` per [id-generation.md](../references/id-generation.md), counting existing `docs/review/.scope/YYYY-MM-DD-NNN-scope.md` files (or registry rows) for today. This is the pipeline umbrella id (distinct from any Work `review-id` for work-linked input — the two skills produce independent artifacts; the `work-id` is carried alongside for traceability).
-2. **Assign a `scope-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-scope`, saved to `docs/plans/.review/.scope/`). Reuse it if the user later picks **Edit & Retry**.
+2. **Assign a `scope-id`** per [id-generation.md](../references/id-generation.md) (format `YYYY-MM-DD-NNN-scope`, saved to `docs/review/.scope/`). Reuse it if the user later picks **Edit & Retry**.
 3. Produce a **Review Scope Artifact** block (as markdown) following the schema in [review-scope.md](../references/templates/artifacts/review-scope.md). Include:
    - `scope-id`, `review-id`, `input-shape`, `interactionMode`
@@ -113,7 +113,7 @@ Apply the **[phase confirmation behavior](../references/interaction-mode-propaga
 - **Smart:** pause only when a pause trigger above is true; otherwise auto-proceed.
 - **Autopilot:** auto-proceed (no confirmation).
-Then save the artifact to `docs/plans/.review/.scope/<scope-id>.md` (ensure `interactionMode`, `input-shape`, and `review-id` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Prepare).
+Then save the artifact to `docs/review/.scope/<scope-id>.md` (ensure `interactionMode`, `input-shape`, and `review-id` are included) and return it, with the `interactionMode` value, to the Orchestrator for the transition to Phase 2 (Prepare).
 ## Output: Review Scope Artifact
@@ -121,6 +121,6 @@ Then save the artifact to `docs/plans/.review/.scope/<scope-id>.md` (ensure `int
 - Verify that the change boundary is in **dependency-safe** form: `required` files are repository-relative and carry a status; `context` is separated from `required`.
 - Verify that `review-id` was allocated (scope is the allocating phase) and that `work-id` is carried for work-linked input.
 - Verify that scope-creep detection was run only when requirements were present (else explicitly skipped with a note), per [scope-creep-detection.md](../references/scope-creep-detection.md).
-- Verify that the artifact is saved to `docs/plans/.review/.scope/<scope-id>.md`.
+- Verify that the artifact is saved to `docs/review/.scope/<scope-id>.md`.
 > Pass the Review Scope to `prepare` (Phase 2) to gather the diffs, spec content, test context, and tool inventory.

package/skills/review/references/error-handling.md CHANGED Viewed

@@ -85,7 +85,7 @@ Errors encountered while saving or reading artifact files.
 | Target directory does not exist                  | Create directory (`mkdir -p`); treat counter as 0; start from 001 | No                 |
 | Counter directory exists but no files match date | Start counter at 001                                              | No                 |
 | File write permission denied                     | Log error; ask user to check permissions; retry once              | Yes, after 1 retry |
-| `docs/plans/.review/index.md` registry missing  | Create it with a `# Reviews` header (Pre-Flight already creates; idempotent) | No     |
+| `docs/review/index.md` registry missing  | Create it with a `# Reviews` header (Pre-Flight already creates; idempotent) | No     |
 | `docs/tasks/<work-id>/index.md` missing (Report cross-link) | Skip the cross-link; note the absence in the report (do not fabricate a work index) | No |
 ### Category 5: Interaction Mode Errors

package/skills/review/references/id-generation.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 title: Artifact ID Generation
-description: Reference for Scope, Prepare, Analyze, and Report phases. Defines the daily-counter algorithm for unique artifact IDs, the review-id umbrella allocation (distinct from a Work review-id), the recycle-on-edit rule, and the shared counter layout under docs/plans/.review/.
+description: Reference for Scope, Prepare, Analyze, and Report phases. Defines the daily-counter algorithm for unique artifact IDs, the review-id umbrella allocation (distinct from a Work review-id), the recycle-on-edit rule, and the shared counter layout under docs/review/.
 type: reference
 version: 1.0
 timestamp: "2026-08-08"
@@ -14,10 +14,10 @@ Shared ID algorithm for the `scope`, `prepare`, `analyze`, and `report` phases,
 | Phase    | ID format                            | Saved to                            |
 | -------- | ----------------------------------- | ----------------------------------- |
-| Scope    | `YYYY-MM-DD-NNN-scope`              | `docs/plans/.review/.scope/<id>.md`    |
-| Prepare  | `YYYY-MM-DD-NNN-prepare`            | `docs/plans/.review/.prepare/<id>.md`  |
-| Analyze  | `YYYY-MM-DD-NNN-analyze`            | `docs/plans/.review/.analyze/<id>.md`  |
-| Report   | `YYYY-MM-DD-NNN-report`             | `docs/plans/.review/.report/<id>.md`   |
+| Scope    | `YYYY-MM-DD-NNN-scope`              | `docs/review/.scope/<id>.md`    |
+| Prepare  | `YYYY-MM-DD-NNN-prepare`            | `docs/review/.prepare/<id>.md`  |
+| Analyze  | `YYYY-MM-DD-NNN-analyze`            | `docs/review/.analyze/<id>.md`  |
+| Report   | `YYYY-MM-DD-NNN-report`             | `docs/review/.report/<id>.md`   |
 `review-id` (see below) is the umbrella shared across all four artifacts of a single review run.
@@ -25,19 +25,19 @@ Shared ID algorithm for the `scope`, `prepare`, `analyze`, and `report` phases,
 The `review-id` is the umbrella key that ties all four phase artifacts together and keys the registry row / work-index block. It is allocated **once** in Scope Step 2 (the allocating phase) and carried through Prepare/Analyze/Report unchanged.
-**Format:** `YYYY-MM-DD-NNN` (date + zero-padded 3-digit daily counter), counting existing `docs/plans/.review/.scope/YYYY-MM-DD-NNN-scope.md` files for that date (the scope phase is the allocating phase, so its counter is the source of truth for the umbrella id).
+**Format:** `YYYY-MM-DD-NNN` (date + zero-padded 3-digit daily counter), counting existing `docs/review/.scope/YYYY-MM-DD-NNN-scope.md` files for that date (the scope phase is the allocating phase, so its counter is the source of truth for the umbrella id).
-> **Distinct from a Work `review-id`.** When Review is invoked over a `/work` run (`input-shape: work-linked`), the Work skill's own `review-id` (`docs/plans/.work/.review/...`) **already exists**. The Review skill allocates its **own** `review-id` (`docs/plans/.review/...`) — the two skills produce independent artifacts and never share an id. The `work-id` is carried alongside in the Review artifacts for traceability and the work-index cross-link, but `review-id` ≠ Work `review-id`.
+> **Distinct from a Work `review-id`.** When Review is invoked over a `/work` run (`input-shape: work-linked`), the Work skill's own `review-id` (`docs/plans/.work/.review/...`) **already exists**. The Review skill allocates its **own** `review-id` (`docs/review/...`) — the two skills produce independent artifacts and never share an id. The `work-id` is carried alongside in the Review artifacts for traceability and the work-index cross-link, but `review-id` ≠ Work `review-id`.
 ## Algorithm (new phase artifact)
 ```
 1. Get the current date in UTC (e.g., 2026-08-08)
 2. List existing files for today in the phase's save directory:
-   - scope    -> docs/plans/.review/.scope/     matching YYYY-MM-DD-*-scope.md
-   - prepare  -> docs/plans/.review/.prepare/   matching YYYY-MM-DD-*-prepare.md
-   - analyze  -> docs/plans/.review/.analyze/   matching YYYY-MM-DD-*-analyze.md
-   - report   -> docs/plans/.review/.report/    matching YYYY-MM-DD-*-report.md
+   - scope    -> docs/review/.scope/     matching YYYY-MM-DD-*-scope.md
+   - prepare  -> docs/review/.prepare/   matching YYYY-MM-DD-*-prepare.md
+   - analyze  -> docs/review/.analyze/   matching YYYY-MM-DD-*-analyze.md
+   - report   -> docs/review/.report/    matching YYYY-MM-DD-*-report.md
 3. NNN = (count + 1), zero-padded to 3 digits (001, 002, ..., 010, ...)
 4. id = "<date>-<NNN>-<phase>"
 ```
@@ -50,7 +50,7 @@ Allocated **only** in Scope Step 2:
 ```
 1. Get the current date in UTC
-2. List existing files under docs/plans/.review/.scope/ matching YYYY-MM-DD-NNN-scope.md for that date
+2. List existing files under docs/review/.scope/ matching YYYY-MM-DD-NNN-scope.md for that date
 3. NNN = (highest existing NNN for that date), zero-padded to 3 digits
    - if none exist for that date, start at 001
 4. review-id = "<date>-<NNN>"  (the same NNN as the scope-id being allocated)
@@ -61,7 +61,7 @@ Because `review-id` reuses the scope counter's NNN, the umbrella id and the `sco
 ## Recycle on Edit & Retry
-When the user picks **Edit & Retry** at a phase confirmation, **reuse the original ID** and overwrite the existing artifact file. Do **not** increment the counter. This keeps IDs stable across iterations and prevents orphaned artifacts. The Report phase's registry row in `docs/plans/.review/index.md` and the `## Review Report — <report-id>` block in the work index are likewise idempotent on `report-id` (overwritten, never duplicated).
+When the user picks **Edit & Retry** at a phase confirmation, **reuse the original ID** and overwrite the existing artifact file. Do **not** increment the counter. This keeps IDs stable across iterations and prevents orphaned artifacts. The Report phase's registry row in `docs/review/index.md` and the `## Review Report — <report-id>` block in the work index are likewise idempotent on `report-id` (overwritten, never duplicated).
 ## Error Handling
@@ -69,12 +69,12 @@ When the user picks **Edit & Retry** at a phase confirmation, **reuse the origin
 | ----------------------------------------------- | -------------------------------------------- |
 | Phase save directory does not exist              | Create it; treat count as 0; start from 001  |
 | Directory exists but no files match today's date | Start counter at 001                         |
-| `docs/plans/.review/` missing                   | Create it (Pre-Flight already creates; idempotent) |
+| `docs/review/` missing                   | Create it (Pre-Flight already creates; idempotent) |
 | Write permission denied                         | Log error; ask the user; retry once          |
 ## Notes
-- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan` and `/work`; the Review skill's counters are independent from those skills (separate save directories under `docs/plans/.review/` vs `.work/`).
+- IDs reuse the daily-counter algorithm for cross-skill consistency with `/plan` and `/work`; the Review skill's counters are independent from those skills (separate save directories under `docs/review/` vs `.work/`).
 - `review-id` carries through every artifact (`scope-id` artifacts record it; Prepare/Analyze/Report inherit it), so cross-phase chaining is `scope-id → prepare-id → analyze-id → report-id`, all sharing one `review-id` (see [error-handling.md](error-handling.md) "Cross-Phase Consistency Checks").
 - For work-linked input, `work-id` is **additionally** carried (inherited from the Review Input Artifact), distinct from `review-id`, for the registry cross-link only.
 - Counter collisions are impossible within a date because each phase writes to its own directory and recomputes the count from the directory listing.

package/skills/review/references/templates/artifacts/findings.md CHANGED Viewed

@@ -53,7 +53,7 @@ scope-creep-ran: true | "skipped (no requirements)"   # false only via the skipp
 work-id: YYYY-MM-DD-NNN | null          # work-linked only; null otherwise
 ```
-Also save the Findings to `docs/plans/.review/.analyze/<analyze-id>.md`.
+Also save the Findings to `docs/review/.analyze/<analyze-id>.md`.
 ## Validation Rules

package/skills/review/references/templates/artifacts/review-input.md CHANGED Viewed

@@ -111,6 +111,6 @@ references: null
 ## Notes
-- The Orchestrator's Pre-Flight Check ensures `docs/plans/.review/.{scope,prepare,analyze,report}/` and `docs/plans/.review/index.md` exist (self-healing via `mkdir -p`) before handing the Review Input Artifact to Scope.
+- The Orchestrator's Pre-Flight Check ensures `docs/review/.{scope,prepare,analyze,report}/` and `docs/review/index.md` exist (self-healing via `mkdir -p`) before handing the Review Input Artifact to Scope.
 - `interactionMode` flows from this artifact into every downstream artifact (Scope → Prepare → Analyze → Report); the orchestrator quality gate #2 cross-checks it is identical across all.
 - For work-linked input, the Work `review-id` and the Review skill's own `review-id` are **distinct** (see [id-generation.md](../../id-generation.md)); the `work-review-id` here is only an input resolver, never reused as the Review skill's umbrella id.

package/skills/review/references/templates/artifacts/review-kit.md CHANGED Viewed

@@ -60,7 +60,7 @@ tool-inventory:
 work-id: YYYY-MM-DD-NNN | null    # work-linked only; null otherwise
 ```
-Also save the Review Kit to `docs/plans/.review/.prepare/<prepare-id>.md`.
+Also save the Review Kit to `docs/review/.prepare/<prepare-id>.md`.
 ## Validation Rules

package/skills/review/references/templates/artifacts/review-report.md CHANGED Viewed

@@ -8,7 +8,7 @@ timestamp: "2026-08-08"
 # Review Report Artifact
-The product of the **Report** phase is the Review Report — the Review skill's final deliverable. It records the **approval status** (`approved` / `changes-requested` / `rejected`) derived deterministically from the Findings tallies per [approval-criteria.md](../../approval-criteria.md), with a one-line rationale tied to the counts; the findings rollup (by severity and by category); non-binding **recommendations**; the **scope-creep summary**; **learnings-to-capture** candidates (handed to `/learn`); and the registration state. A registry row is appended to `docs/plans/.review/index.md` always; for work-linked input, a distinct `## Review Report — <report-id>` block is appended to `docs/tasks/<work-id>/index.md`.
+The product of the **Report** phase is the Review Report — the Review skill's final deliverable. It records the **approval status** (`approved` / `changes-requested` / `rejected`) derived deterministically from the Findings tallies per [approval-criteria.md](../../approval-criteria.md), with a one-line rationale tied to the counts; the findings rollup (by severity and by category); non-binding **recommendations**; the **scope-creep summary**; **learnings-to-capture** candidates (handed to `/learn`); and the registration state. A registry row is appended to `docs/review/index.md` always; for work-linked input, a distinct `## Review Report — <report-id>` block is appended to `docs/tasks/<work-id>/index.md`.
 ## Schema
@@ -54,18 +54,18 @@ learning-gaps:
 work-id: YYYY-MM-DD-NNN | null          # work-linked only; null otherwise
 registration:
-  registry-row-appended: true          # appended to docs/plans/.review/index.md (idempotent on report-id)
+  registry-row-appended: true          # appended to docs/review/index.md (idempotent on report-id)
   work-index-block-appended: true | skipped   # work-linked only; skipped if the work index is missing
 ```
-Also save the Review Report to `docs/plans/.review/.report/<report-id>.md`.
+Also save the Review Report to `docs/review/.report/<report-id>.md`.
 ## Closing Blocks
-### Registry row (appended to `docs/plans/.review/index.md`, always)
+### Registry row (appended to `docs/review/index.md`, always)
 ```
-- <report-id> — <target-summary> — <approval-status> — docs/plans/.review/.report/<report-id>.md
+- <report-id> — <target-summary> — <approval-status> — docs/review/.report/<report-id>.md
 ```
 ### Work-index block (appended to `docs/tasks/<work-id>/index.md`, work-linked only)
@@ -77,7 +77,7 @@ Also save the Review Report to `docs/plans/.review/.report/<report-id>.md`.
 - **Findings:** <blocker> blocker, <major> major, <minor> minor, <nit> nit
 - **Scope creep:** none | <count> | skipped (no requirements)
 - **Learnings to capture:** <count> (run `/learn` to persist)
-- **Review Report:** docs/plans/.review/.report/<report-id>.md
+- **Review Report:** docs/review/.report/<report-id>.md
 ```
 Both the registry row and the work-index block are **append-only** and **idempotent on `report-id`**: a re-run overwrites the entry with the same id, never duplicates it. The work-index block is deliberately distinct from Work's own `## Work Report — <review-id>` block (different label, different skill, different `report-id`).

package/skills/review/references/templates/artifacts/review-scope.md CHANGED Viewed

@@ -56,7 +56,7 @@ learning-gaps:
 work-id: YYYY-MM-DD-NNN | null             # work-linked only, for the index cross-link; null otherwise
 ```
-Also save the Review Scope to `docs/plans/.review/.scope/<scope-id>.md`.
+Also save the Review Scope to `docs/review/.scope/<scope-id>.md`.
 ## Validation Rules