@starlein/paperclip-plugin-company-wizard 0.4.12 → 0.4.16

package/templates/modules/pr-review/agents/code-reviewer/skills/code-review.md

@@ -9,10 +9,10 @@ Paperclip's runtime **excludes the issue's original executor (the author) from e
 ## What to verify before merging
 
 1. **Hard gate — executed verification (never skip):**
-   - With CI: the PR's CI (lint/test/build) must be **green**. Confirm it on the PR.
-   - Without CI: run the full test suite and build yourself and paste the real output into your verdict before merging.
-   - A merge without cited executed verification is invalid.
-   - **Base-branch-red:** when the base branch's own CI is red, a feature PR's CI is red from the inherited baseline — not from the PR's diff. Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock* (compare the PR's failing checks to the base commit's own checks). Do not merge a feature PR on a red base — record `changes_requested` citing `BASE-BRANCH-RED` and route the issue back with "waiting-on-baseline". The single baseline-restore PR (`fix(ci): restore base CI`) may merge under the narrow exception in `docs/git-workflow.md` → *Narrow exception: merging the baseline-restore PR on a red base*: scoped diff + local executed verification that the fix reduces the failure set + cited base-sha check set. The exception replaces CI-green with local-executed-verification plus diff-scope proof; it does not waive the verification gate and never applies to feature PRs.
+   - **Always run the full lint/test/build yourself and paste the real output** into your verdict before merging. This is the authoritative gate, with or without CI. A merge without cited executed verification is invalid.
+   - **CI is an additional gate only when this company runs its own CI/CD** (the `ci-cd` module is active — you have the `ci-cd` skill / a company-authored `docs/CI-CD*.md`). In that case the company-owned CI (lint/test/build) must also be **green** before you merge.
+   - **No company-owned CI/CD:** treat any pre-existing checks on the repository as **advisory signals, not a gate**. Do not refuse to merge solely because a repo-native check the company never configured is red or flaky — your pasted local test/build output is sufficient. (Look into a red repo check if it reveals a real defect in the diff; never let an external/inherited CI you don't own block the merge.)
+   - **Base-branch-red (company-owned CI only):** when the company's own base-branch CI is red, a feature PR's CI is red from the inherited baseline — not from the PR's diff. Detect base-red per `../../docs/git-workflow.md` → *Base-branch-red deadlock* (compare the PR's failing checks to the base commit's own checks). Do not merge a feature PR on a red company-owned base — record `changes_requested` citing `BASE-BRANCH-RED` and route back with "waiting-on-baseline". The single baseline-restore PR (`fix(ci): restore base CI`) may merge under the narrow exception in `../../docs/git-workflow.md` → *Narrow exception*: scoped diff + local executed verification that the fix reduces the failure set + cited base-sha check set. The exception replaces CI-green with local-executed-verification plus diff-scope proof; it never applies to feature PRs.
 2. **All prior stages approved:** QA's `review` (when present), the Security Engineer's `review` (when added), and the Product Owner's `approval` are all recorded `approved`.
 3. **Correctness pass:** read the diff. Does it do what the PR claims? Are edge cases handled? Is it the simplest, clearest solution? Watch for dead code, exposed secrets, and missing validation at boundaries (defer deep security review to the Security Engineer when the change is security-relevant).
 4. **Base ref:** the PR targets the configured project/worktree base from `heartbeat-context` (`repoRef` / `defaultRef` / `workspaceStrategy.baseRef`). Retarget before merging if it points at the wrong branch.
@@ -45,12 +45,12 @@ If correctness, security, or verification is not satisfied, record `changes_requ
 
 ## How to comment
 
-Post verdicts as GitHub PR comments via a Markdown file (`gh pr comment <number> --body-file <file>`) — never inline `--body "..."` (`\n` stays literal in a double-quoted shell string). Open with a heading stating the verdict (`## ✅ Approved & merged`, `## 🔄 Changes requested`), then the verification you ran or confirmed and the specific points you examined. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+Post verdicts as GitHub PR comments via a Markdown file (`gh pr comment <number> --body-file <file>`) — never inline `--body "..."` (`\n` stays literal in a double-quoted shell string). Open with a heading stating the verdict (`## ✅ Approved & merged`, `## 🔄 Changes requested`), then the verification you ran or confirmed and the specific points you examined. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 
 - You are the merge owner. Reviewers before you do not merge; the engineer (author) cannot.
 - "Looks good" is not a verdict. Cite what you examined and the verification you ran or confirmed.
-- Never merge without green CI or pasted test/build output — except the baseline-restore PR under the Base-Branch-Red Protocol, which may merge with cited local-executed verification that the fix reduces the base failure set (remaining failing checks exactly the inherited baseline set) and a scoped diff. A feature PR on a red base is never merged; record `changes_requested` citing `BASE-BRANCH-RED` and route back with "waiting-on-baseline".
+- Never merge without your pasted test/build output. When the company runs its own CI/CD (`ci-cd` module active), company-owned CI must also be green — except the baseline-restore PR under the Base-Branch-Red Protocol, which may merge with cited local-executed verification that the fix reduces the base failure set and a scoped diff. A feature PR on a red company-owned base is never merged; record `changes_requested` citing `BASE-BRANCH-RED`. When the company has no CI/CD module, a pre-existing repo check the company didn't configure is advisory — never block a merge solely on it.
 - Block on real concerns via `changes_requested` rather than merging around them.
 - Never add the issue's author/executor as a participant in any stage — you are the non-author gate that lands the work.

package/templates/modules/pr-review/agents/devops/skills/infra-review.md

@@ -16,7 +16,7 @@ You review PRs for infrastructure impact, performance, security, and operational
 
 1. When a PR changes deployments, configs, dependencies, or system behavior, review it for the infra concerns below.
 2. Focus on infrastructure, deployment, runtime security, observability, and rollback risk.
-3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 4. If you find a concern that should block the merge, flag it as **blocking-severity** in the comment and name who should act on it — for security issues (exposed secrets, critical vulnerabilities), that is the Security Engineer review stage when one exists, otherwise QA or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
 
 ## Rules

package/templates/modules/pr-review/agents/engineer/skills/pr-workflow.md

@@ -1,10 +1,10 @@
 # Skill: PR Workflow
 
-When this skill is active, you work in feature branches and open PRs instead of committing directly to the base ref. Follow the conventions in `docs/pr-conventions.md` in the project root.
+When this skill is active, you work in feature branches and open PRs instead of committing directly to the base ref. Follow the conventions in `../../docs/pr-conventions.md` in the project root.
 
 ## Feature Branch Flow
 
-1. Resolve the project/worktree base ref from the issue's `heartbeat-context` / project workspace metadata before branching. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from your shell's current branch and never rewrite the configured ref to `main`, `master`, or `origin/*`. If no base ref is configured anywhere, use the repository's actual default branch — whatever `origin/HEAD` points at, regardless of name (`main`/`master`/`trunk`/…); fall back to `main` then `master` only if the remote advertises no default HEAD. See `docs/git-workflow.md` → *Resolving the default branch*. Never hard-code `main`.
+1. Resolve the project/worktree base ref from the issue's `heartbeat-context` / project workspace metadata before branching. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from your shell's current branch and never rewrite the configured ref to `main`, `master`, or `origin/*`. If no base ref is configured anywhere, use the repository's actual default branch — whatever `origin/HEAD` points at, regardless of name (`main`/`master`/`trunk`/…); fall back to `main` then `master` only if the remote advertises no default HEAD. See `../../docs/git-workflow.md` → *Resolving the default branch*. Never hard-code `main`.
 2. Fetch and update the base:
    - external: `git fetch origin`, then branch from the configured base ref
    - local: update from the configured local branch
@@ -12,7 +12,7 @@ When this skill is active, you work in feature branches and open PRs instead of
 4. **Verify you are on the feature branch** before making changes: `git branch --show-current` must print your branch name, not the base ref. If it prints the base ref name, you forgot step 3 — create the branch now.
 5. Make your changes, commit with Conventional Commits format
 6. **Verify the current branch one more time**, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-7. Open PR against the same resolved base: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`; configured `main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body (PR Body Template in `docs/pr-conventions.md`) to a file first — never inline `--body "..."` (double-quoted shell string keeps `\n` literal; see *Posting PR Bodies & Comments*).
+7. Open PR against the same resolved base: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`; configured `main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body (PR Body Template in `../../docs/pr-conventions.md`) to a file first — never inline `--body "..."` (double-quoted shell string keeps `\n` literal; see *Posting PR Bodies & Comments*).
 8. **Register the PR as a Paperclip work product** so it is visible on the issue and board (creating it on GitHub alone does not surface it in Paperclip):
    ```
    POST /api/issues/{issueId}/work-products
@@ -60,15 +60,15 @@ If the conflict is too complex to resolve safely (large structural conflict with
 
 ## Base-branch-red deadlock
 
-When a PR's CI fails, do not assume the PR is at fault. Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock*: compare the PR's failing checks against the base commit's own checks. If the base is red, the failure is inherited, not introduced by your diff.
+When a PR's CI fails, do not assume the PR is at fault. Detect base-red per `../../docs/git-workflow.md` → *Base-branch-red deadlock*: compare the PR's failing checks against the base commit's own checks. If the base is red, the failure is inherited, not introduced by your diff.
 
 - **Do not open new feature PRs on a red base** — they pile up and inherit the failure.
-- Run the baseline-emergency protocol in `docs/git-workflow.md` → *Baseline-emergency protocol*: fix main first with a single `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base is green, then rebase and drain the feature-PR queue.
+- Run the baseline-emergency protocol in `../../docs/git-workflow.md` → *Baseline-emergency protocol*: fix main first with a single `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base is green, then rebase and drain the feature-PR queue.
 - A feature PR on a red base waits for the base to be restored. It never merges under the baseline-restore exception.
 
-In **PR-Gate mode** (Code Reviewer present): you are the issue author and Paperclip excludes you from every executionPolicy stage, so you **cannot record `changes_requested`** — only a stage participant (the Code Reviewer) can. If you detect BASE-BRANCH-RED before moving the issue to `in_review` (step 10), do not move it — leave it `in_progress`, comment `BASE-BRANCH-RED` with the baseline-restore PR link, and start the baseline-emergency protocol now. If the issue is already `in_review`, comment `BASE-BRANCH-RED` with "waiting-on-baseline; starting baseline-restore PR now", then immediately claim and create the `fix(ci): restore base CI` PR per the baseline-emergency protocol in `docs/git-workflow.md` — do not wait for the Code Reviewer's `changes_requested` route-back before beginning the fix. The Code Reviewer reads its `code-review.md` and records `changes_requested` to formally route the issue back; the base fix proceeds in parallel. Do not leave the issue silently in `in_review` against a red base.
+In **PR-Gate mode** (Code Reviewer present): you are the issue author and Paperclip excludes you from every executionPolicy stage, so you **cannot record `changes_requested`** — only a stage participant (the Code Reviewer) can. If you detect BASE-BRANCH-RED before moving the issue to `in_review` (step 10), do not move it — leave it `in_progress`, comment `BASE-BRANCH-RED` with the baseline-restore PR link, and start the baseline-emergency protocol now. If the issue is already `in_review`, comment `BASE-BRANCH-RED` with "waiting-on-baseline; starting baseline-restore PR now", then immediately claim and create the `fix(ci): restore base CI` PR per the baseline-emergency protocol in `../../docs/git-workflow.md` — do not wait for the Code Reviewer's `changes_requested` route-back before beginning the fix. The Code Reviewer reads its `code-review.md` and records `changes_requested` to formally route the issue back; the base fix proceeds in parallel. Do not leave the issue silently in `in_review` against a red base.
 
-In the **Self-Merge path** (no Code Reviewer): do not merge your feature PR on a red base; run the baseline-emergency protocol, then rebase and merge once the base is green. If you opened the `fix(ci): restore base CI` PR under a declared baseline emergency, you may merge it despite red CI under the narrow exception in `docs/git-workflow.md` → *Narrow exception* (run the failing checks locally, paste passing output, remaining failures exactly the inherited baseline set).
+In the **Self-Merge path** (no Code Reviewer): do not merge your feature PR on a red base; run the baseline-emergency protocol, then rebase and merge once the base is green. If you opened the `fix(ci): restore base CI` PR under a declared baseline emergency, you may merge it despite red CI under the narrow exception in `../../docs/git-workflow.md` → *Narrow exception* (run the failing checks locally, paste passing output, remaining failures exactly the inherited baseline set).
 
 ## Misrouted in_review (null executionPolicy)
 

package/templates/modules/pr-review/agents/product-owner/skills/product-review.md

@@ -17,7 +17,7 @@ You review PRs for intent alignment, scope discipline, and acceptance criteria.
 2. Record your verdict through the normal issue update route for your approval stage:
    - **approved** if the change meets product requirements
    - **changes_requested** with specific feedback tied to acceptance criteria
-3. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+3. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

package/templates/modules/pr-review/agents/qa/skills/qa-review.md

@@ -2,18 +2,15 @@
 
 You are the **substantive review gate** for pull requests. Review is by *doing*, not by reading: your verdict must rest on tests that actually ran. "Looks good" is not a review.
 
-## Two modes
+## How you verify
 
-**CI is configured (hard gate = CI):**
-Your job is to ensure the tests *mean something*. Green CI on a change with no real coverage is worthless. Verify:
-- New code paths and edge cases are covered by tests that CI runs.
+**You run the tests yourself — always.** There is no machine arbiter you can defer to: check out the branch, run the full test suite and the build locally, and paste the **real command output** into your stage-record verdict. A verdict without execution output is invalid. Beyond green/red, ensure the tests *mean something*:
+- New code paths and edge cases are covered by tests you ran.
 - Tests assert behavior, not implementation.
 - Regression risk is covered.
-- The CI build job is green, not only the test job.
-Record `approved` only when CI is green AND coverage is adequate. If coverage is inadequate, record `changes_requested` with the specific missing test cases — even if CI is green.
+Record `approved` only when your executed tests pass AND coverage is adequate. If coverage is inadequate, record `changes_requested` with the specific missing test cases — even if everything is green.
 
-**No CI configured (you are the gate):**
-There is no machine arbiter, so you run it. Check out the branch, run the full test suite and the build locally, and paste the **real command output** into your stage-record verdict. A verdict without execution output is invalid.
+**Company-owned CI/CD (`ci-cd` module active):** in addition to your own executed verification, confirm the company's CI (lint/test/build) is green — both the build and test jobs. **Without a company CI/CD module:** treat any pre-existing repo checks as advisory signals only; your pasted local output is the gate — do not block solely on an external check the company never configured.
 
 Replace `<branch>` with the PR branch name and substitute your project's actual test and build commands:
 
@@ -39,7 +36,7 @@ Record `approved` only if the suite and build pass and coverage is adequate; oth
 
 1. You are the active participant of a `review` stage on the issue carrying the PR link.
 2. Record on your stage through the normal issue update route: `approved` (with the evidence — commands + results) by PATCHing toward `done`, or `changes_requested` (with specific gaps and suggested test cases) by PATCHing back to `in_progress`.
-3. Optionally mirror the verdict as a GitHub PR comment via a Markdown file: open with a heading (`## ✅ Approved` / `## 🔄 Changes requested`), then details, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+3. Optionally mirror the verdict as a GitHub PR comment via a Markdown file: open with a heading (`## ✅ Approved` / `## 🔄 Changes requested`), then details, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

package/templates/modules/pr-review/agents/security-engineer/skills/pr-security-review.md

@@ -18,7 +18,7 @@ Review is by *probing*, not by reading. Your verdict must state what you actuall
 1. You are the active participant of a `review` stage on the issue carrying the PR link.
 2. State **what you probed and how** (e.g. "checked the new `/upload` endpoint for path traversal with `../` inputs; validated the content-type allowlist"). A verdict without concrete checks is invalid.
 3. Record the stage decision through the normal issue update route: `approved` by PATCHing the issue toward `done` with the checks performed, or `changes_requested` by PATCHing back to `in_progress` with the specific finding, impact, and remediation.
-4. Optionally mirror as a GitHub PR comment via a Markdown file (`## ✅ Approved` / `## 🔄 Changes requested`), run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+4. Optionally mirror as a GitHub PR comment via a Markdown file (`## ✅ Approved` / `## 🔄 Changes requested`), run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

package/templates/modules/pr-review/agents/ui-designer/skills/design-review.md

@@ -4,7 +4,7 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 
 ## Review Checklist
 
-1. **Brand consistency** — If `docs/BRAND-IDENTITY.md` exists, check that colors, typography, spacing, and iconography match the brand guidelines. Otherwise, evaluate visual consistency based on the existing codebase patterns.
+1. **Brand consistency** — If `../../docs/BRAND-IDENTITY.md` exists, check that colors, typography, spacing, and iconography match the brand guidelines. Otherwise, evaluate visual consistency based on the existing codebase patterns.
 2. **Visual hierarchy** — Is the information hierarchy clear? Do primary actions stand out? Is there visual clutter?
 3. **Layout and spacing** — Are margins, padding, and alignment consistent with the design system?
 4. **Responsive behavior** — Does the layout adapt correctly across breakpoints?
@@ -16,12 +16,12 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 
 1. When a PR touches UI components, styles, or user-facing screens, review it for the design concerns below.
 2. Focus only on visual/design concerns — leave code logic to Code Reviewer and product scope to Product Owner.
-3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 4. If you find a concern that should block the merge (e.g. a critical accessibility regression or a brand-violating change), flag it explicitly in the comment and name who should act on it — QA, the Security Engineer, or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
 
 ## Rules
 
 - Be specific — "the button should use `--color-primary`" beats "wrong color".
 - Comment only on changes that touch UI — not every PR needs design review.
-- If `docs/BRAND-IDENTITY.md` doesn't exist yet, note it but don't block the PR.
+- If `../../docs/BRAND-IDENTITY.md` doesn't exist yet, note it but don't block the PR.
 - Screenshots or before/after comparisons strengthen feedback when possible.

package/templates/modules/pr-review/agents/ux-researcher/skills/ux-review.md

@@ -16,12 +16,12 @@ You review PRs for usability, user flow integrity, and alignment with user needs
 
 1. When a PR changes user-facing behavior, interactions, or flows, review it for the UX concerns below.
 2. Focus only on UX and usability concerns — leave code logic to Code Reviewer and visuals to UI Designer.
-3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 4. If you find a concern that should block the merge (e.g. a flow that traps users in a dead end), flag it explicitly in the comment and name who should act on it — QA, the Security Engineer, or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
 
 ## Rules
 
 - Ground feedback in user impact — "users might miss this because..." beats "I don't like this".
-- If `docs/USER-TESTING.md` exists, reference its findings where relevant. If it doesn't exist yet, ground feedback in the PR and existing app patterns instead.
+- If `../../docs/USER-TESTING.md` exists, reference its findings where relevant. If it doesn't exist yet, ground feedback in the PR and existing app patterns instead.
 - Comment only on changes that affect user-facing behavior.
 - If the change introduces a new interaction pattern, flag it for consistency tracking.

package/templates/modules/pr-review/docs/pr-conventions.md

@@ -88,11 +88,13 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
 
 ## Merge Rules
 
-The hard gate is **executed verification**, enforced on the merge-gate stage (the Code Reviewer's) and independent of which reviewers are present:
+The hard gate is **executed verification**, enforced on the merge-gate stage (the Code Reviewer's) and independent of which reviewers are present.
 
-- **With CI:** CI (lint/test/build) must be **green** before the merge gate merges. This is machine-verified and cannot be skipped — with one narrow exception: the baseline-restore PR (`fix(ci): restore base CI`) may merge when the base branch's own CI is red and the PR carries cited local-executed verification that its scoped diff reduces the base failure set (remaining failing checks exactly the inherited baseline set). See `docs/git-workflow.md` → *Base-branch-red deadlock* and *Narrow exception*. A feature PR on a red base is never merged; the merge gate records `changes_requested` citing `BASE-BRANCH-RED` and routes back with "waiting-on-baseline".
-- **Without CI:** the merge-gate agent must run the full test suite and build locally and paste the real output into the merge-gate verdict before merging. (When QA is present, QA already produced this evidence; the merge gate confirms it.)
-- A verdict that does not cite executed verification — green CI, or pasted test/build output — is not valid.
+**The authoritative gate is the merge-gate agent's own executed verification: run the full lint/test/build locally and paste the real output into the merge-gate verdict before merging.** (When QA is present, QA already produced this evidence; the merge gate confirms it.) A verdict that does not cite executed verification — your pasted test/build output, or green company-owned CI — is not valid.
+
+**CI is a gate only when this company runs its own CI/CD** — i.e. the `ci-cd` module is active (you have the `ci-cd` skill and a `docs/CI-CD*.md` the company authored). In that case the company-owned CI (lint/test/build) must be **green** before the merge gate merges, with one narrow exception: the baseline-restore PR (`fix(ci): restore base CI`) may merge when the base branch's own CI is red and the PR carries cited local-executed verification that its scoped diff reduces the base failure set (remaining failing checks exactly the inherited baseline set). See `../../docs/git-workflow.md` → *Base-branch-red deadlock* and *Narrow exception*. A feature PR on a red company-owned base is never merged; the merge gate records `changes_requested` citing `BASE-BRANCH-RED` and routes back with "waiting-on-baseline".
+
+**When the company did NOT set up CI/CD** (no `ci-cd` module): treat any pre-existing checks on the repository as **advisory signals, not a merge gate**. Do not block or refuse a merge solely because a repo-native check the company never configured is red or flaky — your pasted local lint/test/build output is the sufficient and authoritative gate. (Investigate a red repo check if it points at a real defect in the diff, but never let an external/inherited CI you don't own deadlock the queue.)
 - The Product Owner's `approval` stage must be approved.
 - QA's `review` stage (when present) and the Security Engineer's `review` stage (when added) must be approved.
 - Domain reviewers are advisory — blocking only when they escalate a concern that QA, the Security Engineer, or the merge gate then acts on.

package/templates/modules/release-management/agents/ceo/skills/release-process.fallback.md

@@ -4,13 +4,13 @@ You are acting as a fallback for this capability because neither a devops agent
 
 ## What you should do
 
-1. Check if `docs/RELEASE-PROCESS.md` exists. If not, create it with:
+1. Check if `../../docs/RELEASE-PROCESS.md` exists. If not, create it with:
    - Versioning convention (SemVer: `MAJOR.MINOR.PATCH`)
    - Branch and tagging strategy (e.g., tag `vX.Y.Z` on the default branch after each release)
    - Changelog format: Conventional Commits → CHANGELOG.md grouping
    - Note: "This document was created by the CEO as a placeholder. A devops or engineer agent should implement and automate the release pipeline."
 2. Check if the project has a CHANGELOG.md. If not, create one with a `## Unreleased` section listing the current commits since the last tag (use `git log --oneline`).
-3. Create a follow-up issue: "Implement automated release pipeline" assigned to `capability:ci-cd` or directly to an engineer, linking to `docs/RELEASE-PROCESS.md`.
+3. Create a follow-up issue: "Implement automated release pipeline" assigned to `capability:ci-cd` or directly to an engineer, linking to `../../docs/RELEASE-PROCESS.md`.
 4. Mark this issue done. **Do not push tags, create GitHub releases, or modify version files** — those actions require a devops or engineer agent.
 
 ## Rules

package/templates/modules/release-management/agents/engineer/skills/release-process.fallback.md

@@ -4,9 +4,9 @@ DevOps primarily owns the release process. You are the fallback — step in only
 
 ## Release Process (Fallback)
 
-1. If no `docs/RELEASE-PROCESS.md` exists and DevOps hasn't started:
+1. If no `../../docs/RELEASE-PROCESS.md` exists and DevOps hasn't started:
    - Check the project for existing versioning (git tags, package.json version)
-   - Document the current state in `docs/RELEASE-PROCESS.md`
+   - Document the current state in `../../docs/RELEASE-PROCESS.md`
    - If no process exists, set up basic semver + CHANGELOG.md
    - Mark the document as **provisional** — it needs DevOps review for CI integration and rollback procedures
 2. If DevOps is active, skip this entirely.

package/templates/modules/release-management/module.meta.json

@@ -19,7 +19,7 @@
     {
       "title": "Document or establish release process",
       "assignTo": "capability:release-process",
-      "description": "Review the current release workflow. If one exists, document it in docs/RELEASE-PROCESS.md. If not, establish a semver + changelog workflow with tagging conventions."
+      "description": "Review the current release workflow. If one exists, document it in ../../docs/RELEASE-PROCESS.md. If not, establish a semver + changelog workflow with tagging conventions."
     }
   ],
   "routines": [

package/templates/modules/release-management/skills/release-process.md

@@ -10,7 +10,7 @@ You are responsible for managing the release lifecycle — versioning, changelog
    - A release branch strategy or tag-based releases
    - CI/CD release automation (GitHub Actions release workflow, etc.)
 
-2. **Establish or document the release process** in `docs/RELEASE-PROCESS.md`:
+2. **Establish or document the release process** in `../../docs/RELEASE-PROCESS.md`:
    - **Versioning** — Semantic Versioning (MAJOR.MINOR.PATCH). Document what constitutes each level.
    - **Changelog** — Keep a CHANGELOG.md following Keep a Changelog format. Update it with every release.
    - **Tagging** — Tag releases as `vX.Y.Z`. Tags trigger release workflows if CI is configured.
@@ -34,7 +34,7 @@ You are responsible for managing the release lifecycle — versioning, changelog
 When assigned a "Release readiness check" routine-run issue:
 
 1. Check if unreleased changes have accumulated since the last release: `git log <last-tag>..HEAD --oneline`. If no unreleased commits, mark done.
-2. Review `docs/CHANGELOG.md` or commit log for breaking changes, new features, or bug fixes that warrant a version bump.
+2. Review `../../docs/CHANGELOG.md` or commit log for breaking changes, new features, or bug fixes that warrant a version bump.
 3. Run the full test suite and build. If failing, create a blocking issue and escalate before continuing.
 4. If a release is warranted, follow the release steps in the *Setup* section of this skill to cut the release. Otherwise leave a comment noting the check result and mark the routine issue done.
 

package/templates/modules/security-audit/agents/devops/skills/security-review.fallback.md

@@ -4,10 +4,10 @@ The Security Engineer owns security review above you. You are the fallback — s
 
 ## Security Review (Fallback)
 
-1. If no `docs/SECURITY-REVIEW.md` exists and the Security Engineer hasn't started:
+1. If no `../../docs/SECURITY-REVIEW.md` exists and the Security Engineer hasn't started:
    - Audit infrastructure config: Dockerfiles, CI/CD pipelines, cloud IAM, secrets management
    - Check deployment security: TLS, security headers, network policies
-   - Document in `docs/SECURITY-REVIEW.md`
+   - Document in `../../docs/SECURITY-REVIEW.md`
    - Tag the Security Engineer to expand with application-layer review
 2. If the Security Engineer is active, skip this entirely.
 

package/templates/modules/security-audit/agents/devops/skills/threat-model.fallback.md

@@ -4,10 +4,10 @@ The Security Engineer owns threat modeling above you. You are the fallback — s
 
 ## Threat Model (Fallback)
 
-1. If no `docs/THREAT-MODEL.md` exists and the Security Engineer hasn't started:
+1. If no `../../docs/THREAT-MODEL.md` exists and the Security Engineer hasn't started:
    - Map the infrastructure attack surface: exposed ports, network boundaries, cloud IAM
    - Identify deployment-specific risks: container escapes, supply chain, CI/CD pipeline security
-   - Document in `docs/THREAT-MODEL.md`
+   - Document in `../../docs/THREAT-MODEL.md`
    - Tag the Security Engineer to expand with application-layer analysis
 2. If the Security Engineer is active, skip this entirely.
 

package/templates/modules/security-audit/agents/engineer/skills/security-review.fallback.md

@@ -4,10 +4,10 @@ The Security Engineer and DevOps own security review above you. You are the last
 
 ## Security Review (Fallback)
 
-1. If no `docs/SECURITY-REVIEW.md` exists and the Security Engineer hasn't started:
+1. If no `../../docs/SECURITY-REVIEW.md` exists and the Security Engineer hasn't started:
    - Run `npm audit` (or equivalent) and document critical CVEs
    - Check for obvious issues: hardcoded secrets, missing input validation, permissive CORS
-   - Document in `docs/SECURITY-REVIEW.md`
+   - Document in `../../docs/SECURITY-REVIEW.md`
    - Tag the Security Engineer or DevOps to expand the review
 2. If the Security Engineer or DevOps is active, skip this entirely.
 

package/templates/modules/security-audit/agents/engineer/skills/threat-model.fallback.md

@@ -4,10 +4,10 @@ The Security Engineer and DevOps own threat modeling above you. You are the last
 
 ## Threat Model (Fallback)
 
-1. If no `docs/THREAT-MODEL.md` exists and the Security Engineer hasn't started:
+1. If no `../../docs/THREAT-MODEL.md` exists and the Security Engineer hasn't started:
    - Write a brief security overview: main attack surfaces, obvious risks
    - Focus on the OWASP Top 10 most relevant to the project
-   - Document in `docs/THREAT-MODEL.md`
+   - Document in `../../docs/THREAT-MODEL.md`
    - Tag the Security Engineer or DevOps to expand and maintain the model
 2. If the Security Engineer or DevOps is active, skip this entirely.
 

package/templates/modules/security-audit/module.meta.json

@@ -25,12 +25,12 @@
     {
       "title": "Conduct initial threat model",
       "assignTo": "capability:threat-model",
-      "description": "Identify attack surfaces, trust boundaries, and data flows using STRIDE methodology. Document the threat model in docs/THREAT-MODEL.md with risk ratings and mitigation recommendations."
+      "description": "Identify attack surfaces, trust boundaries, and data flows using STRIDE methodology. Document the threat model in ../../docs/THREAT-MODEL.md with risk ratings and mitigation recommendations."
     },
     {
       "title": "Perform initial security review",
       "assignTo": "capability:security-review",
-      "description": "Audit the codebase for OWASP Top 10 vulnerabilities, dependency CVEs, secrets exposure, and configuration issues. Document findings in docs/SECURITY-REVIEW.md with severity ratings."
+      "description": "Audit the codebase for OWASP Top 10 vulnerabilities, dependency CVEs, secrets exposure, and configuration issues. Document findings in ../../docs/SECURITY-REVIEW.md with severity ratings."
     }
   ]
 }

package/templates/modules/security-audit/skills/security-review.bar.md

@@ -2,7 +2,7 @@
 
 A good security review:
 
-- A `docs/SECURITY-REVIEW.md` with findings that include: severity (Critical / High / Medium / Low), exact file path and line number, the evidence (code snippet or reproduction step), and a specific recommended fix.
+- A `../../docs/SECURITY-REVIEW.md` with findings that include: severity (Critical / High / Medium / Low), exact file path and line number, the evidence (code snippet or reproduction step), and a specific recommended fix.
 - A dependency report with CVE details from `npm audit` or equivalent. Critical and High findings have follow-up issues created.
 
 Not done:

package/templates/modules/security-audit/skills/security-review.md

@@ -11,7 +11,7 @@ You own security code review for the project. This catches vulnerabilities in th
    - **Data exposure**: Leaked secrets, verbose errors, unnecessary data in responses
    - **Dependencies**: Known CVEs in dependencies (`npm audit` or equivalent)
    - **Configuration**: Missing security headers, permissive CORS, debug mode in production
-2. Document in `docs/SECURITY-REVIEW.md`:
+2. Document in `../../docs/SECURITY-REVIEW.md`:
    - **Findings** with severity (Critical/High/Medium/Low), location, and evidence
    - **Recommendations** for each finding with specific fix guidance
    - **Dependency report** with CVE details

package/templates/modules/security-audit/skills/threat-model.bar.md

@@ -2,7 +2,7 @@
 
 A good threat model:
 
-- A `docs/THREAT-MODEL.md` with a system overview that includes components, data flows, and explicit trust boundaries; STRIDE threats against the identified attack surfaces; a risk rating (Likelihood × Impact) for each threat; and mitigations for every Critical and High risk.
+- A `../../docs/THREAT-MODEL.md` with a system overview that includes components, data flows, and explicit trust boundaries; STRIDE threats against the identified attack surfaces; a risk rating (Likelihood × Impact) for each threat; and mitigations for every Critical and High risk.
 - Critical and High risks have corresponding follow-up issues with specific remediation tasks.
 
 Not done:

package/templates/modules/security-audit/skills/threat-model.md

@@ -4,8 +4,8 @@ You own threat modeling for the project. This identifies security risks before t
 
 ## Threat Modeling Process
 
-1. Review the system architecture — if `docs/ARCHITECTURE.md` exists, use it as the starting point. Otherwise, analyze the codebase structure directly.
-2. Document in `docs/THREAT-MODEL.md`:
+1. Review the system architecture — if `../../docs/ARCHITECTURE.md` exists, use it as the starting point. Otherwise, analyze the codebase structure directly.
+2. Document in `../../docs/THREAT-MODEL.md`:
    - **System overview**: Components, data flows, trust boundaries
    - **Attack surfaces**: Entry points, APIs, user inputs, external integrations
    - **Threats (STRIDE)**: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege

package/templates/modules/stall-detection/agents/ceo/skills/stall-detection.md

@@ -11,7 +11,7 @@ Use this only when the current assigned issue/routine is titled like "Stall dete
 1. Checkout the assigned routine-run issue.
 2. Query active issues for the relevant company/project: `todo`, `in_progress`, `in_review`, and blocked work where applicable.
 3. For each candidate, inspect latest comments/activity, execution state, blockers, approval/review state, and assigned agent status.
-4. Skip issues with an active run, recent activity, valid `blockedByIssueIds`, or a genuinely pending executionPolicy approval/review — meaning `in_review` **whose current (first unapproved) stage has at least one non-author participant**. An issue `in_review` with `executionPolicy: null`, with no non-author stage at all, OR whose first/current stage lists only the assignee (author) as a participant is NOT pending review — it is a stall (see *Misrouted in_review* and *Author-only first stage* below).
+4. Skip issues with an active run, recent activity, or a genuinely pending executionPolicy approval/review — meaning `in_review` **whose current (first unapproved) stage has at least one non-author participant**. An issue `in_review` with `executionPolicy: null`, with no non-author stage at all, OR whose first/current stage lists only the assignee (author) as a participant is NOT pending review — it is a stall (see *Misrouted in_review* and *Author-only first stage* below). A `blocked` issue counts as validly blocked **only if at least one of its blockers is still open** (`todo`/`in_progress`/`in_review`/`blocked`). A `blocked` issue whose blockers are **all** `done`/`cancelled` (or that has no blockers at all) is NOT validly blocked — it is a stall (see *Stranded blocked* below).
 5. For a likely stall, leave a structured comment on the issue with:
    - issue id/title
    - assigned agent
@@ -38,6 +38,17 @@ An issue `in_review` whose **first (current) executionPolicy stage lists only th
 2. Leave a structured comment on the issue: `in_review` whose first executionPolicy stage lists only the assignee `<agent>` as participant — author-only stage, no eligible participant, permanent stall (`422`).
 3. Recover by nulling the policy: `PATCH /api/issues/{id}` with `{"executionPolicy":null}` returns the issue to `in_progress` (do not try `{"status":"in_progress"}` alone — a active policy rejects that with `422 Only the active reviewer or approver can advance`). Then reassign to the correct owner (the engineer for implementation work) with the next action: either re-set `executionPolicy` stages with a **non-author first stage** (Code Reviewer present) or self-merge the PR via `gh pr merge <N> --merge` (no Code Reviewer). Never re-add the assignee as a stage participant.
 
+## Stranded blocked (blockers done, never reactivated)
+
+An issue in `blocked` whose blockers have **all** reached `done`/`cancelled` is permanently stranded: Paperclip only re-wakes a blocked issue's assignee when a blocker transitions to `done` **and** that blocker's execution workspace has recorded a successful finalize. If the wake was missed, or all blockers were already `done` when the block was set, the issue is never reactivated — and because worker agents have heartbeats disabled, the assignee never wakes on its own. The platform's liveness watchdog also skips a blocked issue once its blockers are `done`, so nothing recovers it. **This is the dominant cause of "PRs open but never merged":** the merge step is frequently modeled as a separate `blocked` "Code review and merge PR #N" issue (assigned to the Code Reviewer) that is `blockedBy` the per-role review issues; once those reviews finish (`done`), the merge issue is stranded `blocked` and the PR is never merged — even when it is green and mergeable.
+
+Detect it during the blocked scan (step 2-5): `GET /api/issues/{id}` and inspect `blockedBy` (every entry `done`/`cancelled`, or empty) — or `blockerAttention` showing `state: "needs_attention"` with `unresolvedBlockerCount: 0`.
+
+1. Flag it in the routine-run summary as `STRANDED-BLOCKED`.
+2. Leave a structured comment on the issue: `blocked` with no open blockers (all blockers `done`/`cancelled`) — never reactivated; recovering.
+3. Reactivate it: `PATCH /api/issues/{id}` with `{"status":"in_progress"}` (a `blocked` issue with `executionPolicy: null` accepts this directly), then **re-assign it to the owner** (for a merge-gate issue, the Code Reviewer; otherwise the role that owns the next action) to trigger a wake, with an explicit next-action comment. For a merge-gate issue the next action is: verify the PR base, satisfy the verification gate (green CI, or paste test/build output where CI is disabled), `gh pr merge <N> --merge`, close/archive any worktree, then mark `done`.
+4. **Prefer prevention over re-stranding:** if you find a *separate* "merge PR #N" issue blocked behind review issues, do not just reactivate it in isolation — the right shape is one implementation issue carrying the PR through its `executionPolicy` stages (which auto-advance) rather than a fan-out of NULL-policy review issues plus a standalone blocked merge issue. Fold the merge back onto the implementation issue's policy where practical, and flag the fan-out pattern to the Product Owner so it stops being created.
+
 ## PR-queue hygiene
 
 As part of every stall-detection run, scan the repository's open PR queue for pile-ups and red/DIRTY state — the issue queue alone does not surface a growing PR backlog. This scan only applies when the `github-repo` module is active (so `gh` is configured and a repository exists). Discover the repo from the project workspace metadata (`repoUrl` / `repoRef`) or your `heartbeat-context`; for multi-repo companies, scan each project's repo.
@@ -47,9 +58,10 @@ As part of every stall-detection run, scan the repository's open PR queue for pi
 3. Escalate a triage issue when any threshold is met:
    - **3 or more** UNSTABLE or DIRTY/CONFLICTING PRs, or
    - **8 or more** open PRs total.
-4. Before opening the triage issue, run the base-branch-red detection in `docs/git-workflow.md` → *Base-branch-red deadlock* against the base commit (if `docs/git-workflow.md` is present — it ships with `github-repo`, which is active here). If the base is red, the triage issue names `BASE-BRANCH-RED` and instructs the baseline-emergency protocol (fix main first, fast-track the baseline-restore PR, drain the queue) — the pile-up is a symptom of the red base, not individual PR faults.
+4. Before opening the triage issue, run the base-branch-red detection in `../../docs/git-workflow.md` → *Base-branch-red deadlock* against the base commit (if `../../docs/git-workflow.md` is present — it ships with `github-repo`, which is active here). If the base is red, the triage issue names `BASE-BRANCH-RED` and instructs the baseline-emergency protocol (fix main first, fast-track the baseline-restore PR, drain the queue) — the pile-up is a symptom of the red base, not individual PR faults.
 5. If the base is green, the triage issue lists each UNSTABLE/DIRTY PR with its owner and the specific next action (rebase for DIRTY, fix the introduced failure for UNSTABLE).
 6. Assign the triage issue to the CEO (or the engineer owning the red base) and summarize on the routine-run issue.
+7. **Reconcile each open PR against its owning issue.** A `CLEAN`/mergeable open PR (CI green or no required CI) whose owning issue is already `done`, or whose dedicated merge issue is `blocked`/stranded, means the merge step never ran — the *exact* "open but never merged" failure. For each such PR: confirm the base is correct and the verification gate is satisfied, then merge it (`gh pr merge <N> --merge`) or route a one-line next-action to the merge owner, and reactivate the stranded merge issue per *Stranded blocked* above. Never leave a green, approved PR unmerged because its tracking issue already closed.
 
 ## Rules
 

package/templates/modules/tech-stack/agents/ceo/skills/tech-stack.fallback.md

@@ -4,9 +4,9 @@ The Engineer primarily owns technology decisions. You are the fallback — step
 
 ## Tech Stack Evaluation (Fallback)
 
-1. If no `docs/TECH-STACK.md` exists and no engineer has started:
+1. If no `../../docs/TECH-STACK.md` exists and no engineer has started:
    - Make pragmatic default choices based on the project type
-   - Document in `docs/TECH-STACK.md` with clear rationale
+   - Document in `../../docs/TECH-STACK.md` with clear rationale
    - Create an issue for the engineer to review and refine the choices
 2. If an engineer is active, skip this entirely.
 

package/templates/modules/tech-stack/module.meta.json

@@ -15,7 +15,7 @@
     {
       "title": "Evaluate and document technology choices",
       "assignTo": "capability:tech-stack",
-      "description": "Assess technology options for the project based on goals, constraints, and team capabilities. Document decisions, trade-offs, and rationale in docs/TECH-STACK.md."
+      "description": "Assess technology options for the project based on goals, constraints, and team capabilities. Document decisions, trade-offs, and rationale in ../../docs/TECH-STACK.md."
     }
   ]
 }

package/templates/modules/tech-stack/skills/tech-stack.bar.md

@@ -2,7 +2,7 @@
 
 A good tech stack evaluation:
 
-- A `docs/TECH-STACK.md` that lists the chosen technology per layer (language, framework, database, infra) with version, the rationale for each choice, and the alternatives that were considered and rejected.
+- A `../../docs/TECH-STACK.md` that lists the chosen technology per layer (language, framework, database, infra) with version, the rationale for each choice, and the alternatives that were considered and rejected.
 - Covers at least: team familiarity, ecosystem maturity, performance trade-offs, and cost for each layer.
 
 Not done:

package/templates/modules/tech-stack/skills/tech-stack.md

@@ -9,7 +9,7 @@ You own technology decisions. Evaluate options and document choices that align w
    - List viable options
    - Evaluate against criteria: team familiarity, ecosystem maturity, performance, cost
    - Document the decision and rationale
-3. Write the complete tech stack to `docs/TECH-STACK.md`:
+3. Write the complete tech stack to `../../docs/TECH-STACK.md`:
    - **Chosen stack**: Technology per layer with version
    - **Rationale**: Why each choice was made
    - **Trade-offs**: What was considered and rejected, and why

package/templates/modules/user-testing/agents/ceo/skills/user-testing.fallback.md

@@ -4,10 +4,10 @@ QA, the UX Researcher, and PO all own usability evaluations above you. You are t
 
 ## User Testing (Fallback)
 
-1. If no `docs/USER-TESTING.md` exists and no one has started:
+1. If no `../../docs/USER-TESTING.md` exists and no one has started:
    - Create a basic heuristic checklist covering the core user flow
    - Identify the top 3-5 usability concerns based on product goals
-   - Document in `docs/USER-TESTING.md`
+   - Document in `../../docs/USER-TESTING.md`
    - Mark all findings as **provisional** — they need validation by QA, a researcher, or PO
 2. If QA, the researcher, or PO is active, skip this entirely.
 

package/templates/modules/user-testing/agents/product-owner/skills/user-testing.fallback.md

@@ -4,10 +4,10 @@ QA and the UX Researcher primarily own usability evaluation. You are the fallbac
 
 ## User Testing (Fallback)
 
-1. If no `docs/USER-TESTING.md` exists and no one above you has started:
+1. If no `../../docs/USER-TESTING.md` exists and no one above you has started:
    - Create a basic test plan covering the most critical user flows
    - Evaluate against acceptance criteria from the product roadmap
-   - Document findings in `docs/USER-TESTING.md`
+   - Document findings in `../../docs/USER-TESTING.md`
    - Mark all findings as **provisional** — they need validation by QA or a researcher
 2. If QA or the researcher is active, skip this entirely.
 

package/templates/modules/user-testing/agents/qa/skills/user-testing.md

@@ -8,7 +8,7 @@ You are the QA engineer and user-facing quality is your core domain. You own tes
 2. Design test scenarios covering critical user flows
 3. Define success metrics for each scenario (task completion, error rate, time-on-task)
 4. Build test automation for repeatable user flow validation
-5. Execute evaluations and document in `docs/USER-TESTING.md`:
+5. Execute evaluations and document in `../../docs/USER-TESTING.md`:
    - **Functional testing**: Verify all user flows work end-to-end
    - **Heuristic analysis**: Apply usability heuristics to key screens and flows
    - **Edge case coverage**: Test boundary conditions, error states, and recovery flows

package/templates/modules/user-testing/agents/ux-researcher/skills/user-testing.fallback.md

@@ -4,10 +4,10 @@ The QA engineer primarily owns test strategy and usability validation. You are t
 
 ## User Testing (Fallback)
 
-1. If no `docs/USER-TESTING.md` exists and QA hasn't started:
+1. If no `../../docs/USER-TESTING.md` exists and QA hasn't started:
    - Design test scenarios covering critical user flows from a user-centered perspective
    - Conduct heuristic evaluation against usability principles
-   - Document findings in `docs/USER-TESTING.md`
+   - Document findings in `../../docs/USER-TESTING.md`
    - Focus on user experience quality — task flows, cognitive load, error recovery
 2. If QA is active, skip this entirely.
 

package/templates/modules/user-testing/module.meta.json

@@ -17,7 +17,7 @@
     {
       "title": "Design and execute initial usability evaluation",
       "assignTo": "capability:user-testing",
-      "description": "Define test scenarios based on the company goal, identify target user personas, create a test plan, execute evaluations, and document findings in docs/USER-TESTING.md."
+      "description": "Define test scenarios based on the company goal, identify target user personas, create a test plan, execute evaluations, and document findings in ../../docs/USER-TESTING.md."
     }
   ]
 }

package/templates/modules/user-testing/skills/user-testing.md

@@ -7,7 +7,7 @@ You own usability evaluations and user testing. This ensures the product meets r
 1. Review the company goal, product description, and user personas
 2. Design test scenarios covering critical user flows
 3. Define success metrics for each scenario (task completion, error rate, time-on-task)
-4. Execute evaluations and document in `docs/USER-TESTING.md`:
+4. Execute evaluations and document in `../../docs/USER-TESTING.md`:
    - **Heuristic analysis**: Apply usability heuristics to key screens and flows
    - **Task flow evaluation**: Walk through core tasks as target personas would
    - **Accessibility review**: Check against basic accessibility standards (contrast, keyboard nav, screen reader)