@juicesharp/rpiv-pi 1.8.1 → 1.8.3

package/README.md

@@ -19,9 +19,9 @@ Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-m
 
 ## What you get
 
-- **A pipeline of chained AI skills** - discover → research → design → plan → implement → validate, each producing a reviewable artifact under `thoughts/shared/`.
+- **A pipeline of chained AI skills** - discover → research → design → plan → implement → validate, each producing a reviewable artifact under `.rpiv/artifacts/`.
 - **Named subagents for parallel analysis** - `codebase-analyzer`, `codebase-locator`, `codebase-pattern-finder`, `claim-verifier`, and 8 more, dispatched automatically by skills.
-- **Session lifecycle hooks** - agent profiles, guidance files, and pipeline directories scaffold themselves on first launch.
+- **Session lifecycle hooks** - agent profiles and guidance files install themselves on first launch.
 
 ## Prerequisites
 
@@ -93,7 +93,7 @@ pi install npm:@juicesharp/rpiv-pi
 On first Pi Agent session start, rpiv-pi automatically:
 - Copies agent profiles to `~/.pi/agent/agents/` (user-global, shared across all projects)
 - Detects outdated or removed agents on subsequent starts
-- Scaffolds `thoughts/shared/` directories for pipeline artifacts
+- Migrates legacy pipeline-artifact content into `.rpiv/artifacts/` (one-way) when an old `thoughts/shared/` tree is found; otherwise `.rpiv/artifacts/` is created lazily by the first skill that writes an artifact
 - Shows a warning if any sibling plugins are missing
 
 ## Usage
@@ -102,10 +102,10 @@ On first Pi Agent session start, rpiv-pi automatically:
 
 ```
 /skill:discover "add a /skill:fast that runs research+design+plan in one shot"
-/skill:research thoughts/shared/discover/<latest>.md
-/skill:design thoughts/shared/research/<latest>.md
-/skill:plan thoughts/shared/designs/<latest>.md
-/skill:implement thoughts/shared/plans/<latest>.md Phase <N>
+/skill:research .rpiv/artifacts/discover/<latest>.md
+/skill:design .rpiv/artifacts/research/<latest>.md
+/skill:plan .rpiv/artifacts/designs/<latest>.md
+/skill:implement .rpiv/artifacts/plans/<latest>.md Phase <N>
 ```
 
 Each skill produces an artifact consumed by the next. Run them in order, or jump in at any stage if you already have the input artifact.
@@ -114,14 +114,14 @@ Each skill produces an artifact consumed by the next. Run them in order, or jump
 
 Skills compose. Pick the entry point that matches your intent:
 
-- **Capture intent before research** - `/skill:discover "[feature description]"`. Walks you through a one-question-at-a-time interview to settle Goals/Non-Goals, Functional/Non-Functional Requirements, Acceptance Criteria, and a Decisions log into a Feature Requirements Document under `thoughts/shared/discover/`. Use as the canonical entry point of the pipeline before research, or to stress-test a feature idea before any codebase work. The FRD's Decisions are inherited by `design` through `research`'s Developer Context.
-- **Form context before a task** - `/skill:research "[topic]"` (or `/skill:research thoughts/shared/discover/<latest>.md` if you ran discover first). Produces a high-signal subspace of the codebase relevant to your topic, ready to feed directly into the next prompt. The `scope-tracer` subagent runs in-band to formulate trace-quality questions before analysis dispatch; when chained from discover, FRD Decisions translate into Developer Context Q/A entries verbatim.
+- **Capture intent before research** - `/skill:discover "[feature description]"`. Walks you through a one-question-at-a-time interview to settle Goals/Non-Goals, Functional/Non-Functional Requirements, Acceptance Criteria, and a Decisions log into a Feature Requirements Document under `.rpiv/artifacts/discover/`. Use as the canonical entry point of the pipeline before research, or to stress-test a feature idea before any codebase work. The FRD's Decisions are inherited by `design` through `research`'s Developer Context.
+- **Form context before a task** - `/skill:research "[topic]"` (or `/skill:research .rpiv/artifacts/discover/<latest>.md` if you ran discover first). Produces a high-signal subspace of the codebase relevant to your topic, ready to feed directly into the next prompt. The `scope-tracer` subagent runs in-band to formulate trace-quality questions before analysis dispatch; when chained from discover, FRD Decisions translate into Developer Context Q/A entries verbatim.
 - **Compare approaches before designing** - `/skill:explore "[problem]"` → `/skill:design <solutions artifact>`. Use when multiple valid solutions exist; the solutions artifact is a first-class input to `design` alongside a `research` artifact.
 - **One-shot plan from research** - `/skill:research <questions>` → `/skill:blueprint <research artifact>` → `/skill:implement`. Fuses `design` + `plan` into a single pass with the same slice-by-slice rigor, but spawns only `codebase-pattern-finder` upfront (vs `design`'s 4-agent fan-out) by trusting the research artifact's integration/precedent sections. Use for solo work or when no one else needs to review the design before implementation; pick `design` → `plan` when the design is itself a deliverable or when research is thin and you want the fuller verification sweep.
 - **Full feature build** - `/skill:discover` → `research` → `design` → `plan` → `implement` → `validate` → (`code-review` ↔ `commit`). The default pipeline; jump in at any stage if you already have the input artifact.
-- **Investigate a bug** - `/skill:discover "why does X fail"` → `/skill:research thoughts/shared/discover/<latest>.md`. The discover interview surfaces what you actually want to know before research grounds it; fix from research output without writing a plan when the change is small.
+- **Investigate a bug** - `/skill:discover "why does X fail"` → `/skill:research .rpiv/artifacts/discover/<latest>.md`. The discover interview surfaces what you actually want to know before research grounds it; fix from research output without writing a plan when the change is small.
 - **Adjust mid-implementation** - `/skill:revise <plan artifact>` → resume `/skill:implement`. Use when new constraints land after the plan is drafted.
-- **Review before shipping** - `/skill:code-review` ↔ `/skill:commit`. Order is your call: review `staged`/`working` before committing to catch issues at the smallest blast radius, or commit first and review the resulting branch (empty scope defaults to feature-branch-vs-default-branch, first-parent). Produces a Quality/Security/Dependencies artifact under `thoughts/shared/reviews/` with claim-verifier-grounded findings and `status: approved | needs_changes`.
+- **Review before shipping** - `/skill:code-review` ↔ `/skill:commit`. Order is your call: review `staged`/`working` before committing to catch issues at the smallest blast radius, or commit first and review the resulting branch (empty scope defaults to feature-branch-vs-default-branch, first-parent). Produces a Quality/Security/Dependencies artifact under `.rpiv/artifacts/reviews/` with claim-verifier-grounded findings and `status: approved | needs_changes`.
 - **Audit a specific scope** - `/skill:code-review <commit|staged|working|hash|A..B|branch>`. Targeted lenses over a commit, range, staged/working tree, or PR branch; advisor adjudication applies when configured (`/advisor`).
 - **Review-driven plan revision** - `/skill:code-review` → `/skill:revise <plan artifact>` → resume `/skill:implement`. When a mid-stream review surfaces structural findings that the existing plan can't absorb as spot fixes.
 - **Scaffold manual UI test specs** - `/skill:outline-test-cases` → `/skill:write-test-cases <feature>`. Outline first via Frontend-First Discovery to map project scope and avoid duplicate coverage, then generate flow-based manual test cases (with a regression suite) under `.rpiv/test-cases/<feature>/`.
@@ -136,17 +136,17 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 
 | Skill | Input | Output | Description |
 |---|---|---|---|
-| `discover` | Free-text feature description or existing artifact path | `thoughts/shared/discover/` | Interview-driven Feature Requirements Document producer; one question at a time with a recommended answer at every step. FRD Decisions inherited by `design` via `research`'s Developer Context |
-| `research` | Free-text prompt or `discover` artifact path | `thoughts/shared/research/` | Frame scope via the `scope-tracer` subagent, then answer via parallel analysis agents |
-| `explore` | - | `thoughts/shared/solutions/` | Compare solution approaches with pros/cons |
-| `design` | Research or solutions artifact | `thoughts/shared/designs/` | Design features via vertical-slice decomposition |
+| `discover` | Free-text feature description or existing artifact path | `.rpiv/artifacts/discover/` | Interview-driven Feature Requirements Document producer; one question at a time with a recommended answer at every step. FRD Decisions inherited by `design` via `research`'s Developer Context |
+| `research` | Free-text prompt or `discover` artifact path | `.rpiv/artifacts/research/` | Frame scope via the `scope-tracer` subagent, then answer via parallel analysis agents |
+| `explore` | - | `.rpiv/artifacts/solutions/` | Compare solution approaches with pros/cons |
+| `design` | Research or solutions artifact | `.rpiv/artifacts/designs/` | Design features via vertical-slice decomposition |
 
 #### Implementation
 
 | Skill | Input | Output | Description |
 |---|---|---|---|
-| `plan` | Design artifact | `thoughts/shared/plans/` | Create phased implementation plans |
-| `blueprint` | Research or solutions artifact | `thoughts/shared/plans/` | Fused `design` + `plan`: vertical-slice decomposition with micro-checkpoints, emits implement-ready phased plan in one pass. Lighter on subagent fan-out than `design` - trusts the research artifact's integration/precedent sections instead of re-dispatching. Use when a separate design artifact isn't needed for review or handoff |
+| `plan` | Design artifact | `.rpiv/artifacts/plans/` | Create phased implementation plans |
+| `blueprint` | Research or solutions artifact | `.rpiv/artifacts/plans/` | Fused `design` + `plan`: vertical-slice decomposition with micro-checkpoints, emits implement-ready phased plan in one pass. Lighter on subagent fan-out than `design` - trusts the research artifact's integration/precedent sections instead of re-dispatching. Use when a separate design artifact isn't needed for review or handoff |
 | `implement` | Plan artifact | Code changes | Execute plans phase by phase |
 | `revise` | Plan artifact | Updated plan | Revise plans based on feedback |
 | `validate` | Plan artifact | Validation report | Verify plan execution |
@@ -202,8 +202,8 @@ Agents are dispatched automatically by skills via the `Agent` tool - you don't i
 | `peer-comparator` | Compares a new file against a peer sibling and tags each invariant Mirrored / Missing / Diverged / Intentionally-absent |
 | `precedent-locator` | Finds similar past changes in git history - commits, blast radius, and follow-up fixes |
 | `test-case-locator` | Catalogs existing manual test cases under `.rpiv/test-cases/` and reports coverage stats |
-| `thoughts-analyzer` | Performs deep-dive analysis on a research topic in `thoughts/` |
-| `thoughts-locator` | Discovers relevant documents in the `thoughts/` directory |
+| `artifacts-analyzer` | Performs deep-dive analysis on a research topic in `.rpiv/artifacts/` |
+| `artifacts-locator` | Discovers relevant documents in the `.rpiv/artifacts/` directory |
 | `web-search-researcher` | Researches modern web-only information via deep search and fetch |
 
 ## Architecture
@@ -213,7 +213,7 @@ rpiv-pi/
 ├── extensions/rpiv-core/   - runtime extension: hooks, commands, guidance injection
 ├── skills/                 - AI workflow skills (research → design → plan → implement)
 ├── agents/                 - named subagent profiles dispatched by skills
-└── thoughts/shared/        - pipeline artifact store
+└── .rpiv/artifacts/        - pipeline artifact store
 ```
 
 Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills via `"skills": ["./skills"]` in `package.json`.

package/agents/{thoughts-analyzer.md → artifacts-analyzer.md}

@@ -1,11 +1,11 @@
 ---
-name: thoughts-analyzer
+name: artifacts-analyzer
 description: The research equivalent of codebase-analyzer. Use this subagent_type when wanting to deep dive on a research topic. Not commonly needed otherwise.
 tools: read, grep, find, ls
 isolated: true
 ---
 
-You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.
+You are a specialist at extracting HIGH-VALUE insights from .rpiv/artifacts/ documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.
 
 ## Core Responsibilities
 
@@ -113,28 +113,6 @@ Structure your analysis like this:
 - It's too vague to action
 - It's redundant with better sources
 
-## Example Transformation
-
-### From Document:
-"I've been thinking about rate limiting and there are so many options. We could use Redis, or maybe in-memory, or perhaps a distributed solution. Redis seems nice because it's battle-tested, but adds a dependency. In-memory is simple but doesn't work for multiple instances. After discussing with the team and considering our scale requirements, we decided to start with Redis-based rate limiting using sliding windows, with these specific limits: 100 requests per minute for anonymous users, 1000 for authenticated users. We'll revisit if we need more granular controls. Oh, and we should probably think about websockets too at some point."
-
-### To Analysis:
-```
-### Key Decisions
-1. **Rate Limiting Implementation**: Redis-based with sliding windows
-   - Rationale: Battle-tested, works across multiple instances
-   - Trade-off: Chose external dependency over in-memory simplicity
-
-### Technical Specifications
-- Anonymous users: 100 requests/minute
-- Authenticated users: 1000 requests/minute
-- Algorithm: Sliding window
-
-### Still Open/Unclear
-- Websocket rate limiting approach
-- Granular per-endpoint controls
-```
-
 ## Important Guidelines
 
 - **Be skeptical** - Not everything written is valuable

package/agents/artifacts-locator.md

@@ -0,0 +1,122 @@
+---
+name: artifacts-locator
+description: Finds relevant documents in .rpiv/artifacts/. The research equivalent of codebase-locator. Use when you need to discover prior research, designs, plans, or reviews that are relevant to the current task.
+tools: grep, find, ls
+isolated: true
+---
+
+You are a specialist at finding documents in the .rpiv/artifacts/ directory. Your job is to locate relevant artifact documents and categorize them, NOT to analyze their contents in depth.
+
+## Core Responsibilities
+
+1. **Search .rpiv/artifacts/ directory structure**
+   - Check .rpiv/artifacts/ for pipeline artifacts
+
+2. **Categorize findings by type**
+   - Research documents (in research/) — codebase analysis, patterns, dependencies
+   - Solution analyses (in solutions/) — multi-approach comparisons with recommendations
+   - Design artifacts (in designs/) — architectural designs with implementation signatures
+   - Implementation plans (in plans/) — phased plans with success criteria
+   - Code reviews (in reviews/) — code quality and compliance reviews
+   - Handoff documents (in handoffs/) — session context snapshots for resumption
+   - FRD documents (in discover/) — feature requirements from discover skill
+   - General notes and discussions
+
+3. **Return organized results**
+   - Group by document type
+   - Include brief one-line description from title/header
+   - Note document dates if visible in filename
+
+## Search Strategy
+
+First, think deeply about the search approach - consider which directories to prioritize based on the query, what search patterns and synonyms to use, and how to best categorize the findings for the user.
+
+### Directory Structure
+```
+.rpiv/artifacts/
+├── discover/      # Feature requirements documents (FRDs)
+├── research/      # Codebase analysis, patterns, dependencies
+├── solutions/     # Multi-approach comparisons with recommendations
+├── designs/       # Architectural designs with implementation signatures
+├── plans/         # Phased implementation plans, success criteria
+├── handoffs/      # Session context snapshots for resumption
+├── reviews/       # Code quality and compliance reviews
+└── tickets/       # Ticket documentation
+```
+
+### Search Patterns
+- Use grep for content searching
+- Use glob for filename patterns
+- Check standard subdirectories
+
+## Output Format
+
+Structure your findings like this:
+
+```
+## Artifact Documents about {Topic}
+
+### FRD Documents
+- `.rpiv/artifacts/discover/2026-05-17_13-29-24_rate-limiting.md` - Rate limit configuration FRD
+
+### Research Documents
+- `.rpiv/artifacts/research/2026-01-15_10-45-00_rate-limiting-approaches.md` - Research on rate limiting strategies
+  - tags: [research, codebase, rate-limiting, api]
+
+### Solution Analyses
+- `.rpiv/artifacts/solutions/2026-01-16_14-30-00_rate-limiting-strategies.md` - Comparison of Redis vs in-memory vs distributed approaches
+
+### Design Artifacts
+- `.rpiv/artifacts/designs/2026-01-17_09-00-00_rate-limiter-design.md` - Architectural design for sliding window rate limiter
+  - parent: `.rpiv/artifacts/research/2026-01-15_10-45-00_rate-limiting-approaches.md`
+
+### Implementation Plans
+- `.rpiv/artifacts/plans/2026-01-18_11-20-00_rate-limiter-implementation.md` - Phased plan for rate limits
+  - parent: `.rpiv/artifacts/designs/2026-01-17_09-00-00_rate-limiter-design.md`
+
+### Code Reviews
+- `.rpiv/artifacts/reviews/2026-01-25_16-00-00_rate-limiter-review.md` - Review of rate limiting implementation
+
+### Handoff Documents
+- `.rpiv/artifacts/handoffs/2026-01-20_17-30-00_rate-limiter-handoff.md` - Session snapshot: rate limiter phase 1 complete
+
+Total: 7 relevant documents found
+Artifact chain: research → design → plan (3 linked documents)
+```
+
+## Search Tips
+
+1. **Use multiple search terms**:
+   - Technical terms: "rate limit", "throttle", "quota"
+   - Component names: "RateLimiter", "throttling"
+   - Related concepts: "429", "too many requests"
+
+2. **Check all artifact subdirectories**:
+   - Each subdirectory corresponds to a pipeline stage
+   - Don't skip directories — relevant artifacts can appear at any stage
+
+3. **Look for patterns**:
+   - Skill-generated files use `YYYY-MM-DD_HH-MM-SS_topic.md` naming
+   - Documents have YAML frontmatter with searchable `topic:`, `tags:`, `status:`, `parent:` fields
+
+4. **Follow artifact chains**:
+   - Research → Solutions → Designs → Plans → Reviews → Handoffs
+   - Check `parent:` in frontmatter to find related documents
+   - When you find one artifact, look for upstream/downstream artifacts on the same topic
+
+## Important Guidelines
+
+- **Don't read full file contents** - Just scan for relevance
+- **Preserve directory structure** - Show where documents live
+- **Be thorough** - Check all relevant subdirectories
+- **Group logically** - Make categories meaningful
+- **Note patterns** - Help user understand naming conventions
+
+## What NOT to Do
+
+- Don't analyze document contents deeply
+- Don't make judgments about document quality
+- Don't skip subdirectories
+- Don't ignore old documents
+
+Remember: You're a document finder for the .rpiv/artifacts/ directory. Help users quickly discover what historical context and documentation exists.

package/agents/precedent-locator.md

@@ -1,11 +1,11 @@
 ---
 name: precedent-locator
-description: "Finds similar past changes in git history: commits, blast radius, follow-up fixes, and lessons from related thoughts/ docs. Use when planning a change and you need to know what went wrong last time something similar was done."
+description: "Finds similar past changes in git history: commits, blast radius, follow-up fixes, and lessons from related .rpiv/artifacts/ docs. Use when planning a change and you need to know what went wrong last time something similar was done."
 tools: bash, grep, find, read, ls
 isolated: true
 ---
 
-You are a specialist at finding PRECEDENTS for planned changes. Your job is to mine git history and thoughts/ documents to find the most similar past changes, extract what happened, and surface lessons that help a planner avoid repeating mistakes.
+You are a specialist at finding PRECEDENTS for planned changes. Your job is to mine git history and .rpiv/artifacts/ documents to find the most similar past changes, extract what happened, and surface lessons that help a planner avoid repeating mistakes.
 
 ## Pre-flight: Git Availability Check
 
@@ -16,7 +16,7 @@ git rev-parse --is-inside-work-tree 2>/dev/null
 
 **If this fails (not a git repo):**
 - Skip all git-based searches (Steps 2 and 3 of Search Strategy)
-- Still search thoughts/ for lessons (Step 4 — Grep/Glob-based, works without git)
+- Still search .rpiv/artifacts/ for lessons (Step 4 — Grep/Glob-based, works without git)
 - Return this format:
 
 ```
@@ -25,7 +25,7 @@ git rev-parse --is-inside-work-tree 2>/dev/null
 **No git history available** — not a git repository.
 
 ### Lessons from Documentation
-{Findings from thoughts/, or "No relevant documents found"}
+{Findings from .rpiv/artifacts/, or "No relevant documents found"}
 
 ### Composite Lessons
 - No git-based lessons available
@@ -48,7 +48,7 @@ git rev-parse --is-inside-work-tree 2>/dev/null
    - Identify what broke and how quickly it was discovered
 
 4. **Extract lessons from docs**
-   - Search thoughts/ for plans, research, or bug analyses related to each precedent
+   - Search .rpiv/artifacts/ for plans, research, or bug analyses related to each precedent
    - Read relevant documents to extract key lessons and warnings
 
 5. **Distill composite lessons**
@@ -73,7 +73,7 @@ git rev-parse --is-inside-work-tree 2>/dev/null
 - Look for fix/bug/hotfix keywords in follow-up commit messages
 
 ### Step 4: Correlate with Thoughts
-- `grep -r "keyword" thoughts/` to find related plans, research, bug analyses
+- `grep -r "keyword" .rpiv/artifacts/` to find related plans, research, bug analyses
 - Read the most relevant documents to extract lessons
 - Check if plans documented risks that materialized as bugs
 
@@ -98,7 +98,7 @@ CRITICAL: Use EXACTLY this format. Be concise — commit hashes and dates are th
 - `hash` — "message" (date) — what went wrong
 
 **Lessons from docs**:
-- thoughts/path/to/doc.md — key lesson extracted
+- .rpiv/artifacts/path/to/doc.md — key lesson extracted
 
 **Takeaway**: {one sentence — what to watch out for}
 

package/agents/scope-tracer.md

@@ -85,7 +85,7 @@ Using combined knowledge from Steps 1-4, write 5-10 dense paragraphs:
 - **Trace-quality** — names a complete path, not a generic theme
 - **>=3 code artifacts** per paragraph (file references, function names, type names)
 
-thoughts/ docs are NOT questions — surface them in the Discovery Summary, not as numbered items.
+.rpiv/artifacts/ docs are NOT questions — surface them in the Discovery Summary, not as numbered items.
 
 Coverage check: every key file read in Step 4 appears in at least one question. Files read but absent from all questions indicate either an unnecessary read or a missing question.
 
@@ -101,7 +101,7 @@ CRITICAL: Use EXACTLY this format. The `research` skill parses this block — fr
 # Research Questions: how does the plugin system load and initialize extensions
 
 ## Discovery Summary
-Swept the plugin loader and lifecycle anchors across `src/plugins/`. Key files for depth: `src/plugins/types.ts:8-30` (definition — PluginManifest interface), `src/plugins/registry.ts:23` (entry — scan + manifest validation), `src/plugins/loader.ts:45` (factory — instantiation), `src/plugins/lifecycle.ts:12-44` (contract — hook ordering), `tests/plugins/registry.test.ts` (coverage). Two thoughts/ docs surfaced: `thoughts/shared/research/2026-03-12_plugin-architecture.md` (prior architectural decisions) and `thoughts/shared/plans/2026-04-01_plugin-lifecycle-extension.md` (recent lifecycle hook addition). The shape is a synchronous scan + lazy instantiate + lifecycle-hook chain pattern; no async loaders or hot-reload paths found.
+Swept the plugin loader and lifecycle anchors across `src/plugins/`. Key files for depth: `src/plugins/types.ts:8-30` (definition — PluginManifest interface), `src/plugins/registry.ts:23` (entry — scan + manifest validation), `src/plugins/loader.ts:45` (factory — instantiation), `src/plugins/lifecycle.ts:12-44` (contract — hook ordering), `tests/plugins/registry.test.ts` (coverage). Two .rpiv/artifacts/ docs surfaced: `.rpiv/artifacts/research/2026-03-12_plugin-architecture.md` (prior architectural decisions) and `.rpiv/artifacts/plans/2026-04-01_plugin-lifecycle-extension.md` (recent lifecycle hook addition). The shape is a synchronous scan + lazy instantiate + lifecycle-hook chain pattern; no async loaders or hot-reload paths found.
 
 ## Questions
 
@@ -118,7 +118,7 @@ Swept the plugin loader and lifecycle anchors across `src/plugins/`. Key files f
 - **Don't make recommendations** — no "we should…", no architectural advice; that's `design` / `blueprint` territory
 - **Don't read more than 10 files in Step 4** — context budget is real; rank ruthlessly
 - **Don't synthesize generic titles** — every question must cite >=3 specific files / functions / types; vague themes are too thin
-- **Don't include thoughts/ docs as numbered questions** — surface them in the Discovery Summary; numbered questions are about live code paths
+- **Don't include .rpiv/artifacts/ docs as numbered questions** — surface them in the Discovery Summary; numbered questions are about live code paths
 - **Don't write any file** — the artifact body lives in your final assistant message; the calling skill parses it in-memory
 - **Don't dispatch other agents** — `Agent` is not in the allowlist by design; the anchor sweep is sequential within this agent's own toolkit
 

package/extensions/rpiv-core/guidance.ts

@@ -32,6 +32,7 @@ const AGENTS_MD = "AGENTS.md";
 const CLAUDE_MD = "CLAUDE.md";
 const RPIV_DIR = ".rpiv";
 const GUIDANCE_SUBDIR = "guidance";
+export const ARTIFACTS_SUBDIR = "artifacts";
 const ARCHITECTURE_MD = "architecture.md";
 /** Forward-slash dedup key for root guidance — must NOT use join() for cross-platform compat. */
 const ROOT_GUIDANCE_KEY = `${RPIV_DIR}/${GUIDANCE_SUBDIR}/${ARCHITECTURE_MD}`;

package/extensions/rpiv-core/session-hooks.test.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { createMockCtx, createMockPi, stubGitExec } from "@juicesharp/rpiv-test-utils";
@@ -65,22 +65,128 @@ describe("registerSessionHooks — event wiring", () => {
 	});
 });
 
-describe("session_start hook", () => {
-	it("scaffolds thoughts dirs under ctx.cwd", async () => {
+describe("session_start hook — migration", () => {
+	it("does NOT create .rpiv/artifacts/ on fresh project (no migration source) — issue #31", async () => {
 		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
 		registerSessionHooks(pi);
 		const handler = captured.events.get("session_start")?.[0];
 		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
 		await handler?.({ reason: "startup" } as never, ctx as never);
-		for (const d of [
-			"thoughts/shared/discover",
-			"thoughts/shared/research",
-			"thoughts/shared/designs",
-			"thoughts/shared/plans",
-			"thoughts/shared/handoffs",
-			"thoughts/shared/reviews",
-		]) {
-			expect(existsSync(join(projectDir, d))).toBe(true);
+		expect(existsSync(join(projectDir, ".rpiv", "artifacts"))).toBe(false);
+	});
+
+	it("migrates thoughts/shared/ to .rpiv/artifacts/ with content preservation", async () => {
+		const oldResearch = join(projectDir, "thoughts", "shared", "research");
+		mkdirSync(oldResearch, { recursive: true });
+		writeFileSync(join(oldResearch, "test.md"), "# Test Research");
+
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const handler = captured.events.get("session_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await handler?.({ reason: "startup" } as never, ctx as never);
+
+		// Content preserved
+		expect(existsSync(join(projectDir, ".rpiv", "artifacts", "research", "test.md"))).toBe(true);
+		// Old dir removed
+		expect(existsSync(join(projectDir, "thoughts", "shared"))).toBe(false);
+		// thoughts/ root removed (was empty after shared/ deleted)
+		expect(existsSync(join(projectDir, "thoughts"))).toBe(false);
+	});
+
+	it("preserves thoughts/ root when non-shared content exists", async () => {
+		const oldResearch = join(projectDir, "thoughts", "shared", "research");
+		mkdirSync(oldResearch, { recursive: true });
+		writeFileSync(join(oldResearch, "test.md"), "content");
+		const meDir = join(projectDir, "thoughts", "me");
+		mkdirSync(meDir, { recursive: true });
+		writeFileSync(join(meDir, "notes.md"), "personal");
+
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const handler = captured.events.get("session_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await handler?.({ reason: "startup" } as never, ctx as never);
+
+		expect(existsSync(join(projectDir, ".rpiv", "artifacts", "research", "test.md"))).toBe(true);
+		expect(existsSync(join(projectDir, "thoughts", "shared"))).toBe(false);
+		expect(existsSync(join(projectDir, "thoughts", "me", "notes.md"))).toBe(true);
+		expect(existsSync(join(projectDir, "thoughts"))).toBe(true);
+	});
+
+	it("does NOT create .rpiv/artifacts/ when thoughts/shared/ exists but is empty", async () => {
+		// Edge case: thoughts/shared/ pre-exists (created by tool, partial migration, etc.) but holds no entries.
+		// Migration must not leak an empty .rpiv/artifacts/ tree, and must not delete the empty source.
+		mkdirSync(join(projectDir, "thoughts", "shared"), { recursive: true });
+
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const handler = captured.events.get("session_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await handler?.({ reason: "startup" } as never, ctx as never);
+
+		expect(existsSync(join(projectDir, ".rpiv", "artifacts"))).toBe(false);
+		expect(existsSync(join(projectDir, "thoughts", "shared"))).toBe(true);
+	});
+
+	it("preserves loose files at thoughts/shared/ root (copies them, not just subdirectories)", async () => {
+		// Regression: prior implementation filtered to directories only, dropping loose .md files
+		// at the shared/ root on rmSync. Now cpSync copies both files and directories.
+		const oldShared = join(projectDir, "thoughts", "shared");
+		mkdirSync(oldShared, { recursive: true });
+		writeFileSync(join(oldShared, "loose.md"), "loose content");
+		const oldResearch = join(oldShared, "research");
+		mkdirSync(oldResearch, { recursive: true });
+		writeFileSync(join(oldResearch, "nested.md"), "nested content");
+
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const handler = captured.events.get("session_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await handler?.({ reason: "startup" } as never, ctx as never);
+
+		expect(existsSync(join(projectDir, ".rpiv", "artifacts", "loose.md"))).toBe(true);
+		expect(existsSync(join(projectDir, ".rpiv", "artifacts", "research", "nested.md"))).toBe(true);
+		expect(existsSync(join(projectDir, "thoughts"))).toBe(false);
+	});
+
+	it("no-ops when thoughts/shared/ does not exist (fresh project)", async () => {
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const handler = captured.events.get("session_start")?.[0];
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await handler?.({ reason: "startup" } as never, ctx as never);
+
+		// No migration source → no .rpiv/artifacts/ tree, no thoughts/ tree
+		expect(existsSync(join(projectDir, ".rpiv", "artifacts"))).toBe(false);
+		expect(existsSync(join(projectDir, "thoughts"))).toBe(false);
+	});
+
+	it.skipIf(process.platform === "win32")("never crashes session_start even when migration step fails", async () => {
+		// ESM module namespaces are not configurable under this Vitest config
+		// (see agents.test.ts Q7), so induce the failure at the filesystem layer:
+		// chmod 0o000 on thoughts/shared makes the inner readdirSync throw EACCES,
+		// hitting the migration's catch block.
+		const sharedDir = join(projectDir, "thoughts", "shared");
+		const oldResearch = join(sharedDir, "research");
+		mkdirSync(oldResearch, { recursive: true });
+		writeFileSync(join(oldResearch, "test.md"), "content");
+
+		const originalMode = statSync(sharedDir).mode & 0o777;
+		chmodSync(sharedDir, 0o000);
+		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+		try {
+			const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+			registerSessionHooks(pi);
+			const handler = captured.events.get("session_start")?.[0];
+			const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+			// Must not throw — migration is best-effort
+			await expect(handler?.({ reason: "startup" } as never, ctx as never)).resolves.toBeUndefined();
+			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("migration"));
+		} finally {
+			chmodSync(sharedDir, originalMode);
+			warnSpy.mockRestore();
 		}
 	});
 });

package/extensions/rpiv-core/session-hooks.ts

@@ -5,7 +5,7 @@
  * Ordering and invariants preserved verbatim from the pre-refactor index.ts.
  */
 
-import { mkdirSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import {
 	type ExtensionAPI,
@@ -27,18 +27,9 @@ import {
 	resetInjectedMarker,
 	takeGitContextIfChanged,
 } from "./git-context.js";
-import { clearInjectionState, handleToolCallGuidance, injectRootGuidance } from "./guidance.js";
+import { ARTIFACTS_SUBDIR, clearInjectionState, handleToolCallGuidance, injectRootGuidance } from "./guidance.js";
 import { findMissingSiblings } from "./package-checks.js";
 
-const THOUGHTS_DIRS = [
-	"thoughts/shared/discover",
-	"thoughts/shared/research",
-	"thoughts/shared/designs",
-	"thoughts/shared/plans",
-	"thoughts/shared/handoffs",
-	"thoughts/shared/reviews",
-] as const;
-
 const msgAgentsAdded = (n: number) => `Copied ${n} rpiv-pi agent(s) to ~/.pi/agent/agents/`;
 const msgAgentsHealed = (parts: string[]) => `Synced bundled agent(s): ${parts.join(", ")}.`;
 const msgAgentsDrift = (parts: string[]) => `${parts.join(", ")} agent(s). Run /rpiv-update-agents to sync.`;
@@ -83,7 +74,7 @@ async function onSessionStart(
 ): Promise<void> {
 	resetInjectionState();
 	injectRootGuidance(ctx.cwd, pi);
-	scaffoldThoughtsDirs(ctx.cwd);
+	migrateThoughtsToArtifacts(ctx.cwd);
 	await injectGitContext(pi, (msg) => sendGitContextMessage(pi, msg));
 	const cleanup = cleanupPerCwdAgents(ctx.cwd);
 	const agents = syncBundledAgents(false);
@@ -131,9 +122,42 @@ function resetInjectionState(): void {
 	clearInjectionState();
 }
 
-function scaffoldThoughtsDirs(cwd: string): void {
-	for (const dir of THOUGHTS_DIRS) {
-		mkdirSync(join(cwd, dir), { recursive: true });
+function migrateThoughtsToArtifacts(cwd: string): void {
+	const oldShared = join(cwd, "thoughts", "shared");
+	if (!existsSync(oldShared)) return;
+
+	try {
+		const entries = readdirSync(oldShared, { withFileTypes: true });
+		if (entries.length === 0) return; // empty source — nothing to copy, leave on disk
+
+		const newArtifacts = join(cwd, ".rpiv", ARTIFACTS_SUBDIR);
+		mkdirSync(newArtifacts, { recursive: true });
+
+		for (const entry of entries) {
+			const src = join(oldShared, entry.name);
+			const dest = join(newArtifacts, entry.name);
+			cpSync(src, dest, { recursive: true, errorOnExist: false, force: true });
+			if (!existsSync(dest)) {
+				console.warn(`[rpiv-pi] migration: failed to copy ${src} → ${dest}`);
+				return; // abort — don't delete source if copy failed
+			}
+		}
+
+		// All copies verified — safe to remove source
+		rmSync(oldShared, { recursive: true, force: true });
+
+		// Remove thoughts/ root only if empty (preserves thoughts/me/ etc.)
+		const thoughtsRoot = join(cwd, "thoughts");
+		try {
+			if (readdirSync(thoughtsRoot).length === 0) {
+				rmSync(thoughtsRoot, { recursive: true, force: true });
+			}
+		} catch {
+			// thoughts/ already gone or unreadable — not an error
+		}
+	} catch (e) {
+		console.warn(`[rpiv-pi] migration: ${e instanceof Error ? e.message : String(e)}`);
+		// Never crash session_start — migration is best-effort
 	}
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",