prizmkit 1.1.41 → 1.1.46

package/bundled/dev-pipeline/scripts/update-refactor-status.py

@@ -384,7 +384,15 @@ def action_update(args, refactor_list_path, state_dir):
 
 
 def _default_project_root():
-    return os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+    env = os.environ.get("PROJECT_ROOT")
+    if env:
+        return os.path.abspath(env)
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    pipeline_dir = os.path.dirname(script_dir)
+    pipeline_parent = os.path.dirname(pipeline_dir)
+    if os.path.basename(pipeline_parent) == ".prizmkit":
+        return os.path.dirname(pipeline_parent)
+    return pipeline_parent
 
 
 def cleanup_refactor_artifacts(state_dir, refactor_id, project_root=None):

package/bundled/dev-pipeline/templates/agent-prompts/critic-plan-challenge.md

@@ -1,7 +1,7 @@
 "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 **MODE: Plan Challenge**
 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-2. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
+2. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
 3. Read existing source files in the modules this plan touches.
 4. Challenge plan.md against the project's existing architecture, patterns, and style.
 Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."

package/bundled/dev-pipeline/templates/bootstrap-prompt.md

@@ -24,7 +24,7 @@ Infer what needs to be done from the feature context above and follow the standa
 
 ### Execution Steps
 
-1. **Read context**: Read `.prizm-docs/root.prizm` and relevant L1/L2 docs to understand the codebase.
+1. **Read context**: Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs to understand the codebase.
 
 2. **Plan**: Run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to produce `spec.md` and `plan.md`.
 
@@ -34,9 +34,9 @@ Infer what needs to be done from the feature context above and follow the standa
 
 5. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to review and auto-fix changes against the spec (internal review-fix loop, max 3 rounds).
 
-6. **Retrospective**: Run `/prizmkit-retrospective` to sync `.prizm-docs/` with code changes.
+6. **Retrospective**: Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/` with code changes.
 
-7. **Commit**: Run `/prizmkit-committer` to commit all changes. Do NOT push.
+7. **Commit**: Run `/prizmkit-committer --headless` to commit all changes. Do NOT push.
 
 ### Critical Rules
 

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -69,7 +69,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
 - Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
-- **CP-0**: Verify `.prizm-docs/root.prizm`, `.prizmkit/config.json` exist
+- **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 {{END_IF_INIT_NEEDED}}
 {{IF_INIT_DONE}}
 ### Phase 0: SKIP (already initialized)
@@ -82,7 +82,7 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXI
 ```
 
 If MISSING — build it now:
-1. Read `.prizm-docs/root.prizm` and relevant L1 prizm docs
+1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1 prizm docs
 2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
    ```bash
    find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
@@ -344,22 +344,22 @@ If verification fails, log the failure details but continue to commit. Failures
 
 ### Phase 4: Architecture Sync & Commit (SINGLE COMMIT)
 
-**4a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
-1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
-2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
+**4a.** Run `/prizmkit-retrospective` — maintains `.prizmkit/prizm-docs/` (architecture index):
+1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizmkit/prizm-docs/` files
+2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizmkit/prizm-docs/`
 3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
-4. Stage doc changes: `git add .prizm-docs/`
+4. Stage doc changes: `git add .prizmkit/prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **4b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
 git add <specific-files-created-or-modified>
-git add .prizm-docs/
+git add .prizmkit/prizm-docs/
 ```
 
 **4c.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
 `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
-This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT push.
+This single commit includes: feature code + tests + .prizmkit/prizm-docs/ updates. Do NOT push.
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 - Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
 

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -80,7 +80,7 @@ If any agent times out:
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
 - Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
-- **CP-0**: Verify `.prizm-docs/root.prizm`, `.prizmkit/config.json` exist
+- **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 {{END_IF_INIT_NEEDED}}
 {{IF_INIT_DONE}}
 ### Phase 0: SKIP (already initialized)
@@ -104,7 +104,7 @@ cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREV
 ```
 If failure-log.md exists:
 - Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
-- Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 6 retrospective
+- Read DISCOVERED_TRAPS — if any are genuine, inject into .prizmkit/prizm-docs/ during Phase 6 retrospective
 - Do NOT delete failure-log.md until this session completes all phases and commits successfully
 
 ```bash
@@ -112,7 +112,7 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXI
 ```
 
 If MISSING — build it now:
-1. Read `.prizm-docs/root.prizm` and relevant L1/L2 prizm docs
+1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
 2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
    ```bash
    find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
@@ -137,7 +137,7 @@ If MISSING — build it now:
      |------|-----------|----------------|
      | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
 
-     ### Known TRAPS (from .prizm-docs/)
+     ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
 
 ### Phase 2: Plan & Tasks (you, the orchestrator)
@@ -190,7 +190,7 @@ Prompt:
 > "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 > **MODE: Plan Challenge**
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-> 2. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
+> 2. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
 > 3. Read existing source files in the modules this plan touches.
 > 4. Challenge plan.md against the project's existing architecture, patterns, and style.
 > Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."
@@ -437,22 +437,22 @@ If verification fails, log the failure details but continue to commit. Failures
 
 ### Phase 6: Architecture Sync & Commit (SINGLE COMMIT)
 
-**6a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
-1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
-2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
+**6a.** Run `/prizmkit-retrospective` — maintains `.prizmkit/prizm-docs/` (architecture index):
+1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizmkit/prizm-docs/` files
+2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizmkit/prizm-docs/`
 3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
-4. Stage doc changes: `git add .prizm-docs/`
+4. Stage doc changes: `git add .prizmkit/prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **6b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
 git add <specific-files-created-or-modified>
-git add .prizm-docs/
+git add .prizmkit/prizm-docs/
 ```
 
 **6c.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
 `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
-This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT push.
+This single commit includes: feature code + tests + .prizmkit/prizm-docs/ updates. Do NOT push.
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 - Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
 

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -81,7 +81,7 @@ If any agent times out:
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
 - Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
-- **CP-0**: Verify `.prizm-docs/root.prizm`, `.prizmkit/config.json` exist
+- **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 {{END_IF_INIT_NEEDED}}
 {{IF_INIT_DONE}}
 ### Phase 0: Record Test Baseline & Detect Test Commands
@@ -134,7 +134,7 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
-1. Read `.prizm-docs/root.prizm` and relevant L1/L2 prizm docs
+1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
 2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
    ```bash
    find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
@@ -159,7 +159,7 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
      |------|-----------|----------------|
      | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
 
-     ### Known TRAPS (from .prizm-docs/)
+     ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
    - **Section 5 — Existing Tests**: full content of related test files as code blocks
 4. Confirm: `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
@@ -221,7 +221,7 @@ Prompt:
 > "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 > **MODE: Plan Challenge**
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-> 2. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
+> 2. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
 > 3. Read existing source files in the modules this plan touches.
 > 4. Challenge plan.md against the project's existing architecture, patterns, and style.
 > Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."
@@ -516,23 +516,23 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 - If a commit for `{{FEATURE_ID}}` already exists → **skip 6d** (do NOT run /prizmkit-committer, do NOT run git reset, do NOT stage or unstage anything). Proceed directly to 6e Final verification.
 - If no existing commit → proceed normally with 6b–6d.
 
-**6b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizm-docs/` architecture index):
+**6b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizmkit/prizm-docs/` architecture index):
 - **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
-- **Architecture knowledge** (feature sessions only): extract TRAPS, RULES, DECISIONS from completed work into `.prizm-docs/`
+- **Architecture knowledge** (feature sessions only): extract TRAPS, RULES, DECISIONS from completed work into `.prizmkit/prizm-docs/`
 - **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
-- Stage doc changes: `git add .prizm-docs/`
+- Stage doc changes: `git add .prizmkit/prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 - **For bug-fix sessions**: structural sync (Job 1) by default. Run knowledge injection (Job 2) when the fix causes interface signature changes, dependency additions/removals, observable behavior changes, or reveals new TRAPs
 
 **6c.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
 git add <specific-files-created-or-modified>
-git add .prizm-docs/
+git add .prizmkit/prizm-docs/
 ```
 
 **6d.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
 `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
-This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT push.
+This single commit includes: feature code + tests + .prizmkit/prizm-docs/ updates. Do NOT push.
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 - Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
 

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -116,10 +116,10 @@ If the bug is related to UI/frontend, you may use these tools to:
 
 **Step 1 — Diagnose the bug**:
 
-1. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules
+1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules
 2. Trace the bug:
    - Classify error type (Runtime / Network / Auth / Data / Logic / Config / External)
-   - Check `.prizm-docs/` TRAPS sections for matching known issues
+   - Check `.prizmkit/prizm-docs/` TRAPS sections for matching known issues
    - Trace call chain from error source to root cause
    - Identify all affected files and modules
 3. Read the affected source files and related test files
@@ -130,7 +130,7 @@ Write `.prizmkit/bugfix/{{BUG_ID}}/context-snapshot.md`:
 - **Section 1 — Bug Brief**: bug description + acceptance criteria + root cause analysis
 - **Section 2 — Affected Files**: full verbatim content of each affected source file
 - **Section 3 — Existing Tests**: full content of related test files
-- **Section 4 — Prizm Context**: relevant TRAPS, RULES from .prizm-docs/
+- **Section 4 — Prizm Context**: relevant TRAPS, RULES from .prizmkit/prizm-docs/
 
 **Step 3 — Plan the fix**:
 
@@ -228,19 +228,19 @@ Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
 - **Full retrospective** (Job 1 + Job 2): Only when the fix causes interface signature changes, dependency additions/removals, observable behavior changes, or reveals new TRAPs.
 
 **a.** If a new pitfall was discovered (not previously in TRAPS):
-   - Update the affected module's TRAPS section in `.prizm-docs/`
+   - Update the affected module's TRAPS section in `.prizmkit/prizm-docs/`
    - Format: `- TRAP: <description> | FIX: <solution> | DATE: YYYY-MM-DD`
 
 **b.** Run `/prizmkit-retrospective` following the policy above.
-   Stage doc changes: `git add .prizm-docs/`
+   Stage doc changes: `git add .prizmkit/prizm-docs/`
 
 **c.** Stage all changed files explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
 git add <specific-files-modified>
-git add .prizm-docs/
+git add .prizmkit/prizm-docs/
 ```
 
-**d.** Run `/prizmkit-committer`:
+**d.** Run `/prizmkit-committer --headless`:
    - Commit message prefix: `fix({{FIX_SCOPE}}): {{BUG_TITLE}}`
    - Include both fix code and reproduction test
    - Do NOT push

package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md

@@ -166,7 +166,7 @@ Include browser verification approach in plan.md:
 - Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false)
   Prompt: "Read {{DEV_SUBAGENT_PATH}}. For refactor {{REFACTOR_ID}} ('{{REFACTOR_TITLE}}'):
   1. Read `.prizmkit/refactor/{{REFACTOR_ID}}/spec.md` and `.prizmkit/refactor/{{REFACTOR_ID}}/plan.md`
-  2. Read `.prizm-docs/` for affected modules (TRAPS, RULES, PATTERNS)
+  2. Read `.prizmkit/prizm-docs/` for affected modules (TRAPS, RULES, PATTERNS)
   3. Before making any changes, run the existing test suite to establish a green baseline
   4. Run `/prizmkit-implement` with `artifact_dir=.prizmkit/refactor/{{REFACTOR_ID}}/` — this handles the full implementation cycle:
      - Reads plan.md Tasks section
@@ -233,9 +233,9 @@ Include browser verification approach in plan.md:
 
 **This phase is executed by YOU (the orchestrator), NOT a subagent.**
 
-1. Run `/prizmkit-retrospective` (full sync — Job 1 + Job 2) to update `.prizm-docs/` with structural changes
+1. Run `/prizmkit-retrospective` (full sync — Job 1 + Job 2) to update `.prizmkit/prizm-docs/` with structural changes
 
-2. Run `/prizmkit-committer` with:
+2. Run `/prizmkit-committer --headless` with:
    - Commit message: `refactor({{REFACTOR_ID}}): {{REFACTOR_TITLE}}`
    - Include all refactored files and any new/updated tests
    - Do NOT push (user will push manually)
@@ -271,7 +271,7 @@ Include browser verification approach in plan.md:
    ```
    Rules: focus on structural changes, new module boundaries, renamed/moved files, changed interfaces. 3-8 notes, each under 120 chars.
 
-- **CP-RF-4**: Commit recorded, refactor-report.md written, .prizm-docs/ updated
+- **CP-RF-4**: Commit recorded, refactor-report.md written, .prizmkit/prizm-docs/ updated
 - **Checkpoint update**: set steps `prizmkit-committer` and `refactor-report` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 ### Step 3: Report Session Status

package/bundled/dev-pipeline/templates/sections/phase-commit-full.md

@@ -7,22 +7,22 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 - If a commit for `{{FEATURE_ID}}` already exists → **skip d** (do NOT run /prizmkit-committer, do NOT run git reset, do NOT stage or unstage anything). Proceed directly to e Final verification.
 - If no existing commit → proceed normally with b–d.
 
-**b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizm-docs/` architecture index):
+**b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizmkit/prizm-docs/` architecture index):
 1. **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
-2. **Architecture knowledge**: extract TRAPS, RULES, DECISIONS from completed work into `.prizm-docs/`
+2. **Architecture knowledge**: extract TRAPS, RULES, DECISIONS from completed work into `.prizmkit/prizm-docs/`
 3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
-4. Stage doc changes: `git add .prizm-docs/`
+4. Stage doc changes: `git add .prizmkit/prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **c.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
 git add <specific-files-created-or-modified>
-git add .prizm-docs/
+git add .prizmkit/prizm-docs/
 ```
 
 **d.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
 `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
-This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT push.
+This single commit includes: feature code + tests + .prizmkit/prizm-docs/ updates. Do NOT push.
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 - Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
 

package/bundled/dev-pipeline/templates/sections/phase-commit.md

@@ -1,21 +1,21 @@
 ### Architecture Sync & Commit (SINGLE COMMIT)
 
-**a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
-1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
-2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
+**a.** Run `/prizmkit-retrospective` — maintains `.prizmkit/prizm-docs/` (architecture index):
+1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizmkit/prizm-docs/` files
+2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizmkit/prizm-docs/`
 3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
-4. Stage doc changes: `git add .prizm-docs/`
+4. Stage doc changes: `git add .prizmkit/prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
 git add <specific-files-created-or-modified>
-git add .prizm-docs/
+git add .prizmkit/prizm-docs/
 ```
 
 **c.** Run `/prizmkit-committer` → THE ONLY commit for this feature:
 `feat({{FEATURE_ID}}): {{FEATURE_TITLE}}`
-This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT push.
+This single commit includes: feature code + tests + .prizmkit/prizm-docs/ updates. Do NOT push.
 - MANDATORY: commit must be done via `/prizmkit-committer` skill. Do NOT run manual `git add`/`git commit` as a substitute.
 - Do NOT run `update-feature-status.py` here — the pipeline runner handles feature-list.json updates automatically after session exit.
 

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-agent-suffix.md

@@ -10,7 +10,7 @@
      |------|-----------|----------------|
      | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
 
-     ### Known TRAPS (from .prizm-docs/)
+     ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
 
 

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-base.md

@@ -5,7 +5,7 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXI
 ```
 
 If MISSING — build it now:
-1. Read `.prizm-docs/root.prizm` and relevant L1/L2 prizm docs
+1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
 2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
    ```bash
    find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30

package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md

@@ -11,7 +11,7 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
-1. Read `.prizm-docs/root.prizm` and relevant L1/L2 prizm docs
+1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
 2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
    ```bash
    find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
@@ -36,7 +36,7 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
      |------|-----------|----------------|
      | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
 
-     ### Known TRAPS (from .prizm-docs/)
+     ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
    - **Section 5 — Existing Tests**: full content of related test files as code blocks
 5. Confirm: `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`

package/bundled/dev-pipeline/templates/sections/phase0-init.md

@@ -1,7 +1,7 @@
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
 - Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
-- **CP-0**: Verify `.prizm-docs/root.prizm`, `.prizmkit/config.json` exist
+- **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 
 
 **Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-init` to `"completed"`.

package/bundled/dev-pipeline/tests/test-path-resolution.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Test path resolution in lib/common.sh across:
+#   1. Framework repo-source layout  (<repo>/dev-pipeline/lib/common.sh)
+#   2. User-install layout           (<proj>/.prizmkit/dev-pipeline/lib/common.sh)
+#   3. Caller pre-set override       (test mocks PRIZMKIT_DIR / PROJECT_ROOT)
+#
+# Run: bash dev-pipeline/tests/test-path-resolution.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+COMMON_SH="$REPO_ROOT/dev-pipeline/lib/common.sh"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+PASS=0
+FAIL=0
+
+pass() { echo -e "  ${GREEN}PASS${NC} $1"; PASS=$((PASS + 1)); }
+fail() { echo -e "  ${RED}FAIL${NC} $1 — $2"; FAIL=$((FAIL + 1)); }
+
+# Helper: source common.sh in a clean subshell with given env, echo the three
+# resolved paths as PIPELINE_DIR|PRIZMKIT_DIR|PROJECT_ROOT.
+resolve() {
+    env -i HOME="$HOME" PATH="$PATH" "$@" bash -c "
+        source '$COMMON_SH' >/dev/null 2>&1
+        printf '%s|%s|%s\n' \"\$PIPELINE_DIR\" \"\$PRIZMKIT_DIR\" \"\$PROJECT_ROOT\"
+    "
+}
+
+echo "================================="
+echo " Path Resolution Tests"
+echo "================================="
+
+# --- Test 1: Framework repo-source layout ---
+# common.sh located at <repo>/dev-pipeline/lib/common.sh.
+# PIPELINE_DIR -> <repo>/dev-pipeline
+# PRIZMKIT_DIR -> <repo>/.prizmkit
+# PROJECT_ROOT -> <repo>
+echo "[Test 1] Repo-source layout"
+result=$(resolve)
+IFS='|' read -r pipeline prizmkit project <<<"$result"
+[[ "$pipeline" == "$REPO_ROOT/dev-pipeline" ]] \
+    && pass "PIPELINE_DIR=$pipeline" \
+    || fail "PIPELINE_DIR" "got: $pipeline"
+[[ "$prizmkit" == "$REPO_ROOT/.prizmkit" ]] \
+    && pass "PRIZMKIT_DIR=$prizmkit" \
+    || fail "PRIZMKIT_DIR" "got: $prizmkit"
+[[ "$project" == "$REPO_ROOT" ]] \
+    && pass "PROJECT_ROOT=$project" \
+    || fail "PROJECT_ROOT" "got: $project"
+
+# --- Test 2: User-install layout (.prizmkit/dev-pipeline) ---
+# Build a tmp dir resembling: <tmp>/proj/.prizmkit/dev-pipeline/lib/common.sh
+TMP_INSTALL=$(mktemp -d)
+trap 'rm -rf "$TMP_INSTALL"' EXIT
+mkdir -p "$TMP_INSTALL/proj/.prizmkit/dev-pipeline/lib"
+cp "$COMMON_SH" "$TMP_INSTALL/proj/.prizmkit/dev-pipeline/lib/common.sh"
+
+echo "[Test 2] User-install layout"
+result=$(env -i HOME="$HOME" PATH="$PATH" bash -c "
+    source '$TMP_INSTALL/proj/.prizmkit/dev-pipeline/lib/common.sh' >/dev/null 2>&1
+    printf '%s|%s|%s\n' \"\$PIPELINE_DIR\" \"\$PRIZMKIT_DIR\" \"\$PROJECT_ROOT\"
+")
+IFS='|' read -r pipeline prizmkit project <<<"$result"
+[[ "$pipeline" == "$TMP_INSTALL/proj/.prizmkit/dev-pipeline" ]] \
+    && pass "PIPELINE_DIR=$pipeline" \
+    || fail "PIPELINE_DIR" "got: $pipeline"
+[[ "$prizmkit" == "$TMP_INSTALL/proj/.prizmkit" ]] \
+    && pass "PRIZMKIT_DIR=$prizmkit" \
+    || fail "PRIZMKIT_DIR" "got: $prizmkit"
+[[ "$project" == "$TMP_INSTALL/proj" ]] \
+    && pass "PROJECT_ROOT=$project" \
+    || fail "PROJECT_ROOT" "got: $project"
+
+# --- Test 3: Caller pre-set override (test mocking) ---
+echo "[Test 3] Caller-supplied env vars override detection"
+result=$(resolve \
+    PIPELINE_DIR=/mock/pipeline \
+    PRIZMKIT_DIR=/mock/.prizmkit \
+    PROJECT_ROOT=/mock/proj)
+IFS='|' read -r pipeline prizmkit project <<<"$result"
+[[ "$pipeline" == "/mock/pipeline" ]] \
+    && pass "PIPELINE_DIR honored override" \
+    || fail "PIPELINE_DIR override" "got: $pipeline"
+[[ "$prizmkit" == "/mock/.prizmkit" ]] \
+    && pass "PRIZMKIT_DIR honored override" \
+    || fail "PRIZMKIT_DIR override" "got: $prizmkit"
+[[ "$project" == "/mock/proj" ]] \
+    && pass "PROJECT_ROOT honored override" \
+    || fail "PROJECT_ROOT override" "got: $project"
+
+echo ""
+echo "================================="
+echo " Results: $PASS passed, $FAIL failed"
+echo "================================="
+
+[[ $FAIL -eq 0 ]] || exit 1

package/bundled/rules/USAGE.md

@@ -19,9 +19,9 @@ core/rules/
 
 | File | Description |
 |------|-------------|
-| `prizm-documentation.md` | Sync `.prizm-docs/` when modifying source files |
+| `prizm-documentation.md` | Sync `.prizmkit/prizm-docs/` when modifying source files |
 | `prizm-commit-workflow.md` | Update docs before commit, follow Conventional Commits |
-| `prizm-progressive-loading.md` | Load `.prizm-docs/` progressively on demand, never load all at once |
+| `prizm-progressive-loading.md` | Load `.prizmkit/prizm-docs/` progressively on demand, never load all at once |
 
 ### General Rules (`general/`)
 

package/bundled/rules/_rules-metadata.json

@@ -10,7 +10,7 @@
       "tags": ["prizm", "git"]
     },
     "prizm/prizm-progressive-loading": {
-      "description": "Progressive .prizm-docs context loading protocol",
+      "description": "Progressive .prizmkit/prizm-docs context loading protocol",
       "tags": ["prizm", "context"]
     },
     "general/prefer-linux-commands": {

package/bundled/rules/prizm/prizm-commit-workflow.md

@@ -3,7 +3,7 @@ description: "PrizmKit commit workflow rules"
 ---
 
 Before any git commit in this project:
-1. Run `/prizmkit-retrospective` to sync `.prizm-docs/` (architecture index with TRAPS/RULES/DECISIONS)
+1. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/` (architecture index with TRAPS/RULES/DECISIONS)
 2. Use Conventional Commits format: type(scope): description
 3. Bug fixes use `fix()` prefix, not `feat()`
 4. Bug fixes run retrospective with structural sync only (Job 1)

package/bundled/rules/prizm/prizm-documentation.md

@@ -1,5 +1,5 @@
 ---
-description: "PrizmKit .prizm-docs maintenance rules — when/how to update structured AI documentation"
+description: "PrizmKit .prizmkit/prizm-docs maintenance rules — when/how to update structured AI documentation"
 globs:
   - "**/*.ts"
   - "**/*.tsx"
@@ -11,11 +11,11 @@ globs:
   - "**/*.java"
 ---
 
-WHEN TO UPDATE .prizm-docs/:
-- Feature development (new interface, new module, new behavior) → UPDATE .prizm-docs/
+WHEN TO UPDATE .prizmkit/prizm-docs/:
+- Feature development (new interface, new module, new behavior) → UPDATE .prizmkit/prizm-docs/
 - Bug fix (fixing broken logic, no structural change) → SKIP, do NOT update
 - Rationale: bugs are incomplete features. Recording bug details causes doc bloat with no AI value.
-- Before modifying any source file, read `.prizm-docs/root.prizm` if it exists to understand project structure.
+- Before modifying any source file, read `.prizmkit/prizm-docs/root.prizm` if it exists to understand project structure.
 
 FORMAT RULES (enforced by pre-commit hook — violations block commit):
 - ALL CAPS section headers: MODULE:, FILES:, RESPONSIBILITY:, etc.

package/bundled/rules/prizm/prizm-progressive-loading.md

@@ -3,10 +3,10 @@ description: "PrizmKit progressive context loading protocol"
 ---
 
 This project uses PrizmKit's progressive loading protocol:
-- ON SESSION START: Read `.prizm-docs/root.prizm` (L0 — project map)
+- ON SESSION START: Read `.prizmkit/prizm-docs/root.prizm` (L0 — project map)
 - ON RESUME (feature/bugfix directory has session-summary.md): Read session-summary.md first for prior context, then load only L1/L2 for modules mentioned in it
-- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules. If MODULE_INDEX entries have keyword tags (e.g., `[login, jwt, oauth]`), match user's task description against tags to prioritize which modules' L1 to load first. If root.prizm uses MODULE_GROUPS, identify the relevant domain first, then load L1 only for modules in that domain.
-- ON FILE EDIT: Read L2 (`.prizm-docs/<module>/<submodule>.prizm`) before modifying
+- ON TASK: Read L1 (`.prizmkit/prizm-docs/<module>.prizm`) for relevant modules. If MODULE_INDEX entries have keyword tags (e.g., `[login, jwt, oauth]`), match user's task description against tags to prioritize which modules' L1 to load first. If root.prizm uses MODULE_GROUPS, identify the relevant domain first, then load L1 only for modules in that domain.
+- ON FILE EDIT: Read L2 (`.prizmkit/prizm-docs/<module>/<submodule>.prizm`) before modifying
 - NEVER load all .prizm docs at once
 - Arrow notation (->) in .prizm files indicates load pointers
 - DECISIONS and CHANGELOG in .prizm files are append-only