@starlein/paperclip-plugin-company-wizard 0.4.22 → 0.6.2

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

@@ -8,6 +8,8 @@
 
 Where `<prefix>` is the company issue prefix (lowercase) and `<N>` is the issue number.
 
+When Paperclip has already created a managed issue branch, preserve its supplied name. This naming convention applies only when you must create a branch yourself; it does not authorize switching or renaming the branch in a managed worktree.
+
 Examples: `yes-6/add-auth-endpoint`, `yes-12/fix-game-loop`
 
 ## PR Title
@@ -61,48 +63,42 @@ Apply one primary label: `feature`, `bug`, `docs`, `chore`, `infra`, `agent`.
 
 ## Review Workflow
 
-Review runs through the issue's native `executionPolicy` (stages), not separate child issues. The gate is **executed verification, not opinion**.
+Review runs through the originating issue's `executionPolicy`, not separate child issues. The gate is **exact-head verification, not opinion**. By default, use role-based stages: QA review, Security review only for security-relevant changes, Product Owner approval, then the Code Reviewer merge gate. Omit absent roles and the executor. If `docs/lean-delivery.md` exists, the optional lean-delivery contract replaces this chain with one Code Reviewer merge gate and risk-triggered specialist evidence.
 
 1. **Engineer** resolves the project/worktree base ref before branching from `heartbeat-context` / project workspace metadata. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. PRs must target the corresponding GitHub base and must not silently target the wrong branch.
 2. **Engineer** opens the PR on GitHub and adds the PR link as an issue comment.
-3. **Engineer** sets the originating issue's `executionPolicy` stages, in order:
-   - a `review` stage for **QA** when a QA agent is on the team (test adequacy / running the tests),
-   - a `review` stage for the **Security Engineer** *only when the change is security-relevant* (auth, secrets, input boundaries, crypto, dependencies, infra exposure),
-   - an `approval` stage for the **Product Owner** when one is on the team (intent, scope, acceptance),
-   - a final `approval` stage for the **Code Reviewer** as the merge gate (a non-author — Paperclip excludes the issue's executor from every stage). When no Code Reviewer is on the team, do not set executionPolicy stages at all — use the PR Self-Merge Flow (the engineer opens the PR and merges via `gh pr merge <N> --merge`); other review roles may leave advisory comments but do not block.
-   Resolve each role to its agentId. **Never list the issue's assignee/executor (whoever did the work — engineer, QA, or any role) as a participant in any stage** — the runtime excludes the original executor from every stage, so such a stage has no eligible participant and the issue stalls (`422 No eligible approval participant`). This applies to **every** stage, but is fatal in the **first** stage: a first stage listing only the assignee cannot be passed, so the issue stalls at stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`) even when later stages have non-author participants. If the policy ended up with the assignee as the first/only participant of a stage, recover with `PATCH /api/issues/{id}` `{"executionPolicy":null}` (returns the issue to `in_progress`), then re-set stages with a non-author first stage — or, with no Code Reviewer, self-merge via `gh pr merge <N> --merge`. Non-engineer roles (e.g. QA) must not author implementation work and then self-review it; implementation work belongs to the engineer.
+3. **Engineer** sets the selected workflow's stages before entering review, with a final `approval` stage for the **Code Reviewer** as non-author merge gate. In lean delivery, this is the only stage and all triggered specialist handoffs must return before review begins. When no eligible non-author Code Reviewer is on the team, set no executionPolicy stages and use PR Self-Merge Flow.
+   Resolve each role to its agentId. **Never list the issue's assignee/executor (whoever did the work — engineer, QA, or any role) as a participant in any stage** — Paperclip selects each stage's participant by excluding the recorded return assignee (the implementation owner), so such a stage has no eligible participant and the request is rejected with `422 No eligible <review|approval> participant is configured for this issue`. This applies to **every** stage, but is fatal in the **first** stage: the PATCH that would open the review is refused outright, so the issue never reaches `in_review` even when later stages have non-author participants. (`422 Only the active reviewer or approver can advance the current execution stage` is a different error — it fires when someone who is not the active participant tries to advance a stage that is already pending.) If the policy ended up with the assignee as the first/only participant of a stage, recover with `PATCH /api/issues/{id}` `{"executionPolicy":null}` (returns the issue to `in_progress`), then re-set stages with a non-author first stage — or, with no Code Reviewer, self-merge via `gh pr merge <N> --merge`. Non-engineer roles (e.g. QA) must not author implementation work and then self-review it; implementation work belongs to the engineer.
 4. **Engineer** sets the issue to `in_review`.
-5. **QA** (when present) reviews and records `approved`/`changes_requested` through the normal issue update route with executed evidence (see *Merge Rules*), preserving the issue-level review audit trail.
-6. **Security Engineer** (when present as a stage) probes the security-relevant change and records a verdict stating what was checked.
-7. Other domain reviewers may add **advisory, non-blocking** PR comments. They do not gate the merge.
-8. **Product Owner** reviews for intent match, scope discipline, and acceptance criteria, and records the `approval` verdict through the normal issue update route, preserving the issue-level approval audit trail.
-9. **Code Reviewer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the Code Reviewer satisfies the hard gate (CI green, or runs the tests/build and pastes the output), merges the PR into the correct configured base, confirms the merge landed, preserves the isolated execution workspace for reuse, and only then records `approved` — which closes the issue to `done`. The merge owner must be a non-author: Paperclip excludes the issue's executor (the engineer) from every stage, so the engineer cannot be the merge gate.
+5. In standard review, each active QA/Security/Product stage records its verdict through the executionPolicy, which wakes the next participant. In lean delivery, these roles contribute bounded same-issue evidence only for a concrete trigger before the merge gate, returning the issue to the implementation owner rather than advancing policy stages. UI/UX and DevOps remain advisory in both modes.
+6. **Code Reviewer** verifies the exact head/base, required CI, and triggered evidence, merges into the configured base, confirms the merge landed, and only then records `approved` — which closes the issue.
+7. A correction returns to the same implementation owner, issue, branch, and PR. Board users are not execution participants for technical defects; use a first-class board decision only for irreducible product, legal, licensing, or residual-risk acceptance.
+8. Review rounds are capped by the runtime: after 3 consecutive agent-initiated `changes_requested` rounds on one stage (default; `executionPolicy.maxReviewRounds` overrides it), Paperclip keeps the stage pending and assigns it to the issue's responsible/creating human rather than the implementation owner. That escalation is expected behavior — comment the context that person needs and let them decide; their decision resets the counter.
 
 ## Review Roles
 
-- **QA** (`review` stage, when present): the substantive gate. Test coverage, regression risk, and validation — backed by tests that actually ran.
-- **Security Engineer** (`review` stage, only when the change is security-relevant): probes the diff for injection, auth, secrets, crypto, dependency, and exposure issues.
-- **Product Owner** (`approval` stage, when present): intent alignment, scope discipline, acceptance criteria.
-- **Code Reviewer** (`approval` stage, last, when present): the merge gate and hard-gate backstop — a non-author who verifies and lands the PR. See *Merge Rules*. When no Code Reviewer is present, the engineer self-merges via `gh pr merge <N> --merge` and no executionPolicy stages are set.
-- **Domain reviewers** (advisory): optional, non-blocking comments on correctness, clarity, design, accessibility, UX. They never gate the merge.
+- **Product Owner**: defines acceptance before implementation; approves intent/scope in standard review. In lean delivery, returns only for a concrete unresolved decision.
+- **QA / Security**: QA reviews by default and Security reviews security-relevant changes in standard mode. In lean delivery, both provide only risk-triggered bounded evidence.
+- **UI/UX / DevOps**: risk-triggered advisory evidence on the originating issue in either mode.
+- **Code Reviewer**: final non-author approval stage, exact-head verifier, and merge owner (sole stage in lean delivery). When absent or the author, the engineer self-merges with no executionPolicy stages.
 
 ## 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 **exact-head verification**, enforced by the Code Reviewer merge stage.
+
+**When required company CI is available, it is authoritative on the exact reviewed head.** Cite the head SHA and required green checks, then run only the smallest independent check needed for a risky or unclear part of the diff. Do not duplicate the complete lint/test/typecheck/build suite. When company CI is unavailable, run the complete local gate once and record the real output.
 
-**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.
+Selecting `ci-cd` does not prove required checks exist yet. Use the local fallback until they exist on the reviewed head. Pending or failed required checks are not unavailable CI: wait for or repair them, rather than substituting local output. Branch-protection requirements remain binding even for checks the company did not configure.
 
-**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".
+**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.
-- No force pushes.
+**When the company did NOT set up CI/CD** (no `ci-cd` module): existing required checks and repository rules remain binding, regardless of who configured them. Only optional, non-required checks are advisory. Investigate failures that indicate a defect in the diff; use the complete local gate when no required CI exists. Do not disable protections or bypass a required failing check to make the workflow fit shared credentials.
+- Triggered specialist evidence must be resolved on the originating issue before merge; completed evidence is not replayed after every correction.
+- No force pushes to the base or someone else's branch. After rebasing your own issue branch, use only `--force-with-lease`.
 - Merge using `gh pr merge <number> --merge`.
 - Before merge, verify the PR base matches the configured project/worktree base from `heartbeat-context`. Retarget before review/merge if needed.
 - The Code Reviewer is the merge owner (a non-author); the engineer who wrote the PR cannot merge it.
-- The merge gate must be the **last** `approval` stage and must be a **non-author**. If the Product Owner's approval were last, it would auto-close the issue to `done` and the merge would be skipped, leaving the PR open on GitHub. The merge gate can never be the issue's executor — Paperclip excludes the original executor from every stage (`422 No eligible approval participant is configured for this issue`).
+- The merge gate is the **last stage** (the only stage in lean delivery) and must be a non-author. The issue's executor is never a participant.
 - If Paperclip created an isolated execution workspace for the issue, leave it reusable after the PR is merged and the tree is clean. Do not archive/delete it as part of recording approval or marking the issue `done`; review, follow-up, or dependent work may still reference it. Workspace retirement is a separate board/operator action.
 - Do not configure GitHub branch protection to require approving reviews unless the project has distinct non-author GitHub reviewer credentials; all agents using one GitHub account cannot formally approve their own PRs.
 

package/templates/modules/pr-review/module.meta.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-review",
-  "description": "Coordinates substantive PR review through the issue's native executionPolicy. The merge gate is executed verification — green CI, or running the tests/build and pasting the output — not opinion. QA is the substantive reviewer when present; the Security Engineer reviews only security-relevant changes; the Code Reviewer is the non-author merge gate that verifies and lands the PR (Paperclip excludes the issue's author from every stage, so the engineer cannot merge their own work).",
+  "description": "Coordinates PR review through native executionPolicy stages: QA review, Product approval, then a non-author Code Reviewer merge gate, using roles present. Select the optional lean-delivery module to replace this chain with one merge gate and risk-triggered specialist evidence. Without a Code Reviewer, use the self-merge path.",
   "requires": [
     "github-repo"
   ],
@@ -25,7 +25,7 @@
         "approver": "product-owner",
         "mergeGate": "code-reviewer"
       },
-      "description": "Document and verify the PR workflow via the issue's executionPolicy. The merge gate is executed verification: with CI, builds must be green before merge; without CI, the merge-gate agent runs the test suite/build and pastes the output before merging. Stages: a review stage for QA when present, a review stage for the Security Engineer only on security-relevant changes, an approval stage for the Product Owner when present, and a final approval stage for the Code Reviewer as the merge gate (a non-author woken last to merge the PR before recording approval, which closes the issue). Never list the issue's executor/author as a participant in any stage — Paperclip excludes the original executor, so a stage whose only participant is the author has no eligible participant and the issue stalls (`422 No eligible approval participant is configured for this issue`); this is why the merge gate is the Code Reviewer (a non-author), not the engineer. The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. Other domain reviewers add advisory, non-blocking comments. Optional branch protection may disable direct pushes, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials. When no code-reviewer role is present in the company, use PR-Self-Merge mode instead: the engineer opens the PR normally but skips executionPolicy stages entirely and merges via `gh pr merge <N> --merge` themselves. Other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR but do not block the merge. Never set up executionPolicy stages when there is no eligible non-author merge gate — the issue will stall with `422 No eligible approval participant`."
+      "description": "Document and verify the selected PR workflow via the issue's executionPolicy and docs/pr-conventions.md. Standard stages are QA review when present, Security review only for a security-relevant change, Product Owner approval when present, and a final non-author Code Reviewer approval/merge gate. If docs/lean-delivery.md exists, it replaces the standard chain with exactly one Code Reviewer stage; triggered specialists provide bounded same-issue evidence before that gate, not serial stages. The implementation owner keeps the same issue, branch, and PR through corrections. Verify required company CI on the exact reviewed head; until required checks exist, run the complete local gate once. Pending or failed required checks must be awaited or repaired, not bypassed with local output. The Code Reviewer merges before recording approved, so the issue cannot become done with an open PR. Never list the executor/author as a stage participant: Paperclip excludes the original executor and an author-only stage stalls with 422. Technical corrections return to the implementation owner, not the board user. Use first-class interactions/approvals for genuine human decisions. When no eligible non-author Code Reviewer is present, set no executionPolicy stages and use PR-Self-Merge mode (`gh pr merge <N> --merge`)."
     }
   ]
 }

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,16 +19,16 @@
     {
       "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": [
     {
-      "name": "Release readiness check",
+      "title": "Release readiness check",
       "description": "Check for unreleased changes and cut a release if warranted.",
       "assignTo": "capability:release-process",
       "schedule": "0 9 * * 1",
-      "concurrencyPolicy": "forbid"
+      "concurrencyPolicy": "skip_if_active"
     }
   ]
 }

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,15 +4,15 @@ 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
    - **Risk ratings**: Likelihood x Impact = Risk (Critical/High/Medium/Low)
    - **Mitigations**: Recommended controls for each threat
 3. Create follow-up issues for Critical and High risks:
-   - `POST /api/companies/{companyId}/issues` with specific remediation tasks. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
+   - `POST /api/companies/{companyId}/issues` with specific remediation tasks. Include `projectId` plus `goalId` / `parentId` when applicable, and set `executionWorkspaceSettings: { "mode": "isolated_workspace" }` for top-level repository implementation issues and subissues when the instance feature, project policy, and initialized repository support isolation. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse only when explicitly required via `inheritExecutionWorkspaceFromIssueId`; keep API-only work project-detached.
 4. Record summary in your daily notes
 
 ## Rules

package/templates/modules/stall-detection/agents/ceo/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Stall Detection Routine
 
-Do not scan for stalled work during a normal heartbeat. When you are assigned a routine-run issue titled like "Stall detection", use `$AGENT_HOME/skills/stall-detection.md`, then summarize findings on the routine issue and exit.
+Do not scan for stalled work during a normal heartbeat. When you are assigned a routine-run issue titled like "Stall detection", use your installed `stall-detection` skill, then summarize findings on the routine issue and exit.

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

@@ -2,7 +2,7 @@
 
 You own stall detection when you are explicitly assigned a stall-detection routine run. This is not an every-heartbeat background scan.
 
-This routine is the **periodic backstop**. Individual top-level issues should also carry a per-issue **task watchdog** (`watchdog: { agentId, instructions }` set at issue creation — see the backlog-health skill), which Paperclip fires event-driven the moment an issue's subtree stalls. When you find a stalled top-level issue here that has no watchdog, add one as part of the fix so it recovers natively next time instead of waiting for this scan.
+This routine is the **periodic backstop**. Do not create universal task-watchdog, queue-drain, status-repair, or workspace-cleanup wrapper issues. Prefer the originating issue's real owner, blockers, executionPolicy, interactions, and normal wake paths. Add a watchdog only when the issue explicitly documents a bounded recovery requirement those paths cannot cover.
 
 ## When To Use This Skill
 
@@ -28,17 +28,19 @@ Use this only when the current assigned issue/routine is titled like "Stall dete
 
 Paperclip classifies `in_review_without_action_path` only when an agent-owned `in_review` issue has no participant, interaction, approval, user owner, monitor, active run/queued wake, or recovery issue owning the next action. A null `executionPolicy` is only one input to that classification.
 
-1. Check the interaction, approval, wake, monitor, active-run, and recovery routes in *Stall Check*. If any path is pending, record it as `WAITING-INTERACTION`, `WAITING-APPROVAL`, or the matching owner in the routine summary and do not nudge, reassign, or change status.
+**Paperclip repairs a lost review path itself.** The review path is a maintained invariant: when an `in_review` issue loses its path (a user comment supersedes the pending interaction, a monitor is exhausted, a run ends without restoring one), Paperclip queues a wake with reason `issue_review_path_lost` and drives its own recovery. If `GET /api/issues/{id}/diagnostics/wakes` shows that wake queued or recently claimed, Paperclip owns the next action — record it as `WAITING-REVIEW-PATH-RECOVERY` and do **not** intervene. Only treat the issue as stalled when that recovery is absent, or has itself gone stale/`failed`.
+
+1. Check the interaction, approval, wake, monitor, active-run, and recovery routes in *Stall Check*. If any path is pending, record it as `WAITING-INTERACTION`, `WAITING-APPROVAL`, `WAITING-REVIEW-PATH-RECOVERY`, or the matching owner in the routine summary and do not nudge, reassign, or change status.
 2. If every path is absent, flag the issue as `IN-REVIEW-WITHOUT-ACTION-PATH` and leave a structured comment naming the missing owner.
-3. Make the next action explicit according to the work: add the intended reviewer/interaction, return it to `in_progress` with a concrete change request and active assignee, mark it `done` if already accepted, or open a bounded recovery issue. For PR work, set non-author `executionPolicy` stages when a Code Reviewer exists; otherwise return it to the engineer for the self-merge flow.
+3. Make the next action explicit according to the work: add the intended reviewer/interaction, return it to `in_progress` with a concrete change request and active assignee, or mark it `done` if already accepted. Keep recovery on the originating issue unless independent work is genuinely required. For PR work, restore the selected policy from `docs/pr-conventions.md` if it exists: standard role-based stages, or exactly one non-author Code Reviewer stage when `docs/lean-delivery.md` exists. With no eligible non-author Code Reviewer, return it to the engineer for self-merge.
 
 ## Author-only first stage
 
-An `in_review` issue whose **first (current) executionPolicy stage lists only the issue's assignee as a participant** has an invalid review participant: Paperclip excludes the executor from every stage, so that stage cannot advance (`422 Only the active reviewer or approver can advance the current execution stage`). Common cause: a non-engineer (e.g. QA) was assigned implementation work, did it, moved the issue to `in_review`, and set itself as the first reviewer. Detect it with `GET /api/issues/{id}` (the list endpoint omits the full `executionPolicy`) and compare the current stage participants with `assigneeAgentId`. If another explicit waiting path is pending, leave it intact and defer policy repair until that path resolves.
+Read `GET /api/issues/{id}` and locate the stage named by `executionState.currentStageId`; it need not be the first stage. Paperclip excludes `executionState.returnAssignee` (the implementation owner) when selecting a participant. Compare principals by both type and id. **Do not compare stage participants with `assigneeAgentId` to infer self-review:** Paperclip normally reassigns the issue to the active reviewer, so that match describes a healthy review. A stage is author-only only when every configured participant is the recorded return assignee and there is no eligible participant. If execution state is missing, diagnose with the issue's history/recovery actions rather than guessing who authored the work. If another explicit waiting path is pending, leave it intact.
 
 1. Flag it in the routine-run summary as `AUTHOR-ONLY-STAGE`.
-2. When no other waiting path is pending, leave a structured comment on the issue: `in_review` whose first executionPolicy stage lists only the assignee `<agent>` as participant — author-only stage with no eligible participant (`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.
+2. When no other waiting path is pending, leave a structured comment identifying `currentStageId`, `returnAssignee`, configured participants, and the evidence that no eligible participant exists.
+3. Only with authority to repair this policy, clear it using `PATCH /api/issues/{id}` with `{"executionPolicy":null}`. When a pending execution state has a return assignee, Paperclip restores `in_progress` and that owner; re-read the response rather than assuming the transition. Restore the selected policy with a non-author gate before resubmitting, or return the same issue to its implementation owner for self-merge when no eligible Code Reviewer exists. Never clear a healthy reviewer stage or a human escalation hold. If authorization is denied, report the exact denial to the responsible board operator and stop retrying.
 
 ## Dependency-ready but still blocked
 
@@ -46,6 +48,8 @@ Treat `GET /api/issues/{id}/diagnostics/blockers` as authoritative. When `readin
 
 If `readiness.pendingFinalizeBlockerCount` is non-zero, a blocker may be `done` but still carry `workspace_finalize_pending`, so the dependency is not ready yet. A recent finalization is a valid wait. If finalization remains stale or the corresponding `issue_blockers_resolved` wake is `skipped`/`failed`, flag `WORKSPACE-FINALIZE-PENDING`, attach the blocker and wake diagnostics, and escalate the blocker/finalization failure to the CEO or board operator. Do not force the downstream issue active and do not archive/delete the blocker workspace as a workaround.
 
+A `cancelled` blocker does **not** resolve a dependency. Remove that blocker relation from every dependent when the dependency is no longer required, or replace it with the issue that now owns the work. Do not force a dependent active while diagnostics still list the cancelled blocker as unresolved.
+
 1. If dependency-ready with no active/queued wake or recovery action, flag it in the routine-run summary as `DEPENDENCY-READY-BUT-BLOCKED`.
 2. Leave a structured comment with blocker readiness and wake-diagnostic evidence.
 3. Reactivate it with `PATCH /api/issues/{id}` `{"status":"in_progress"}`, then assign the correct owner with an explicit next action. For a merge-gate issue, the next action is to verify the PR base and verification gate, merge, leave the execution workspace reusable, and mark `done`.
@@ -53,17 +57,14 @@ If `readiness.pendingFinalizeBlockerCount` is non-zero, a blocker may be `done`
 
 ## 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.
+When `github-repo` is active, reconcile each configured project repository's open PRs against their originating Paperclip issues. Resolve repositories only from project metadata/workspace origin and identify every PR as `owner/repo#number`.
 
-1. List open PRs: `gh pr list --repo <owner/repo> --state open --json number,title,mergeStateStatus,headRefName,baseRefName`.
-2. Count PRs in each state: UNSTABLE (mergeable but CI failing), DIRTY/CONFLICTING, CLEAN.
-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.
-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 still `blocked` despite dependency readiness, means the merge step never ran. For each such PR: confirm the base and verification gate, then merge it (`gh pr merge <N> --merge`) or route a one-line next action to the merge owner, and recover the merge issue per *Dependency-ready but still blocked* above. Never leave a green, approved PR unmerged because its tracking issue already closed.
+1. List open PRs and compare each with its originating issue, exact head/base, required CI, merge state, owner, and next gate.
+2. Open PR count is a queue-health signal, not a hard WIP cap. Keep independent acceptance-ready work moving while routing stale, conflicting, red, or ownerless PRs to their existing owners; never create dependencies merely because other PRs are open.
+3. Route CI/runner failures, stale bases, conflicts, branch protection, packaging, deployment, and release mechanics on the **existing originating issue and PR** to the operational owner. Never open a replacement PR to escape a blocker.
+4. A `done` issue with an open PR is an invariant violation. Reopen/route the originating issue when work remains, or close the obsolete PR with evidence. Do not create a separate merge, status, evidence, or cleanup issue.
+5. Detect base-branch-red before blaming feature diffs. Restore the base through one explicitly owned baseline fix, then rebase and drain existing PRs.
+6. Summarize repository counts and exact existing issue/PR next actions on the routine-run issue.
 
 ## Rules
 
@@ -71,4 +72,6 @@ As part of every stall-detection run, scan the repository's open PR queue for pi
 - Do not interrupt running agents.
 - Do not close or cancel another agent's work unless the issue explicitly grants that authority.
 - Be specific: which issue, which agent, last activity, why stalled, and who owns the next action.
+- Do not poll ordinary review stages, PR-capacity waits, or workspace cleanup with a fixed-cadence monitor when a live owner, blocker, participant, or wake path exists. For a named external transition such as a running CI job, use a bounded monitor no more often than every 15 minutes unless the issue defines a tighter SLA; set attempt/timeout bounds and comment only on a state change or terminal checkpoint.
+- **A `403 ... outside this actor's authorization boundary` is a final answer, not a retry.** Paperclip contains cross-issue agent writes: a repair you are not authorized to make on someone else's issue will be denied no matter how often you retry. Record the denial (issue id, attempted change, denial reason) in the routine summary and escalate to the responsible human/board operator in the same pass. Never loop on the same denied call.
 - **Never archive or retire your own routine-run workspace.** This routine is pure control-plane work (reading and patching the board via the API) — it needs no repository state. When you finish, mark the routine issue `done` and exit. Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not check `close-readiness` to trigger a teardown, and do not otherwise remove the worktree your run is using. Archiving it mid-run makes Paperclip fail the run's workspace validation and breaks the next reuse of that workspace. Workspace retirement is a board/operator action only.

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,13 +9,13 @@ 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
    - **Dependencies**: Key libraries and their purposes
 4. Create setup issues if needed:
-   - `POST /api/companies/{companyId}/issues` for initial project scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
+   - `POST /api/companies/{companyId}/issues` for initial project scaffolding. Include `projectId` plus `goalId` / `parentId` when applicable, and set `executionWorkspaceSettings: { "mode": "isolated_workspace" }` for top-level repository implementation issues and subissues when the instance feature, project policy, and initialized repository support isolation. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse only when explicitly required via `inheritExecutionWorkspaceFromIssueId`; keep API-only work project-detached.
 
 ## Rules
 

package/templates/modules/triage/agents/ceo/skills/issue-triage.fallback.md

@@ -8,7 +8,7 @@ The Product Owner or Engineer primarily owns issue triage. You are the fallback
 2. If issues are piling up without responses:
    - Classify each as bug, feature, question, or invalid
    - Respond with a brief acknowledgment
-   - Create Paperclip tasks for actionable items with priority set. When creating Paperclip issues from triaged GitHub items, include `executionWorkspaceSettings: { mode: 'isolated_workspace' }` in the issue creation payload.
+   - Create Paperclip tasks for actionable items with priority set. When creating Paperclip issues from triaged GitHub items, include `executionWorkspaceSettings: { mode: 'isolated_workspace' }` for repository implementation only when the instance feature, project policy, and initialized repository support isolation; otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Keep API-only work project-detached.
    - Close duplicates and invalid issues with explanation
 3. If the Product Owner or Engineer is active and triaging, skip this entirely.
 

package/templates/modules/triage/agents/engineer/skills/issue-triage.fallback.md

@@ -9,7 +9,7 @@ The Product Owner primarily owns issue triage. You are the engineering fallback:
 3. For each technical issue:
    - Reproduce or inspect enough to classify it as bug, feature, question, duplicate, invalid, or needs-info.
    - Apply labels and priority based on user impact and technical severity.
-   - Create Paperclip issues for actionable bugs or engineering work. Top-level Paperclip issues should include `executionWorkspaceSettings: { "mode": "isolated_workspace" }`; subissues set `parentId` and omit workspace settings.
+   - Create Paperclip issues for actionable bugs or engineering work. Top-level issues and subissues include `executionWorkspaceSettings: { "mode": "isolated_workspace" }` when the instance feature, project policy, and initialized repository support isolation; otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Explicit same-change reuse uses `inheritExecutionWorkspaceFromIssueId`.
    - Ask concise follow-up questions when reproduction details are missing.
 4. Leave product-priority and roadmap tradeoffs for the Product Owner or CEO.
 

package/templates/modules/triage/skills/issue-triage.md

@@ -16,7 +16,7 @@ Use this only when the current assigned issue/routine asks for GitHub issue tria
    - Set priority P0-P3; P0 maps to urgent Paperclip priority.
    - Apply labels with `gh issue edit <number> --add-label "<type>,<priority>"`.
    - Respond to the reporter with acknowledgement, follow-up questions, or a polite close reason.
-   - For actionable issues, create a corresponding Paperclip issue via `POST /api/companies/{companyId}/issues`. Include GitHub issue URL/number, active `projectId`, and `goalId` / `parentId` when applicable. For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
+   - For actionable issues, create a corresponding Paperclip issue via `POST /api/companies/{companyId}/issues`. Include the GitHub URL/number, `projectId`, and `goalId` / `parentId` when applicable; set `executionWorkspaceSettings: { "mode": "isolated_workspace" }` for top-level repository implementation issues and subissues when the instance feature, project policy, and initialized repository support isolation. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse only when explicitly required via `inheritExecutionWorkspaceFromIssueId`; keep API-only work project-detached.
 4. Link bidirectionally: GitHub comment references the Paperclip issue, Paperclip issue references GitHub.
 5. Summarize triage results on the assigned triage issue/routine and mark it done.
 

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
@@ -18,7 +18,7 @@ You are the QA engineer and user-facing quality is your core domain. You own tes
    - **Major**: Significant friction or confusion
    - **Minor**: Cosmetic or low-impact usability issues
 7. Create follow-up issues for critical and major findings:
-   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
+   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. Include `projectId` plus `goalId` / `parentId` when applicable, and set `executionWorkspaceSettings: { "mode": "isolated_workspace" }` for top-level repository implementation issues and subissues when the instance feature, project policy, and initialized repository support isolation. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse only when explicitly required via `inheritExecutionWorkspaceFromIssueId`; keep API-only work project-detached.
 8. Record summary in your daily notes
 
 ## Rules