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

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

@@ -4,10 +4,10 @@ DevOps primarily owns dependency management. You are the security fallback: step
 
 ## Dependency Audit (Fallback)
 
-1. If no `../../docs/DEPENDENCY-AUDIT.md` exists or the last audit is stale:
+1. If no `docs/DEPENDENCY-AUDIT.md` exists or the last audit is stale:
    - Run the package manager's vulnerability audit (`npm audit`, `pip-audit`, `go vuln check`, or equivalent).
    - Identify Critical/High CVEs, abandoned packages, suspicious transitive dependencies, and risky license or provenance issues.
-   - Document findings and risk level in `../../docs/DEPENDENCY-AUDIT.md`.
+   - Document findings and risk level in `docs/DEPENDENCY-AUDIT.md`.
    - Apply safe security patch updates only when tests pass.
 2. If DevOps is active and already running the audit, review their findings for security completeness instead of duplicating the work.
 

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

@@ -24,11 +24,11 @@
   ],
   "routines": [
     {
-      "name": "Dependency audit",
+      "title": "Dependency audit",
       "description": "Scan for new vulnerabilities and outdated packages, apply safe patch updates.",
       "assignTo": "capability:dependency-audit",
       "schedule": "0 2 * * 1",
-      "concurrencyPolicy": "forbid"
+      "concurrencyPolicy": "skip_if_active"
     }
   ]
 }

package/templates/modules/dependency-management/skills/dependency-audit.md

@@ -20,7 +20,7 @@ You are responsible for keeping the project's dependencies healthy, secure, and
    - Can it be updated in-place (patch/minor bump)?
    - Does it require migration work (major version, breaking changes)?
    - Are there alternatives if the dependency is abandoned?
-5. **Document** findings in `../../docs/DEPENDENCY-AUDIT.md`:
+5. **Document** findings in `docs/DEPENDENCY-AUDIT.md`:
    - Summary table of dependencies by status (current, outdated, vulnerable, deprecated)
    - Prioritized upgrade plan with estimated effort
    - Lock file hygiene notes
@@ -34,7 +34,7 @@ When assigned a "Dependency audit" routine-run issue:
 1. Run the vulnerability scan: `npm audit --json` (or equivalent for the project's package manager). Flag any new Critical or High CVEs not present in the last audit.
 2. Check for newly outdated dependencies: compare current versions against the latest. Flag anything more than one major version behind.
 3. Apply safe patch updates (semver patch-only, no breaking changes): update, run the test suite, commit if green.
-4. Update `../../docs/DEPENDENCY-AUDIT.md` with the new scan date, any new findings, and any updates applied.
+4. Update `docs/DEPENDENCY-AUDIT.md` with the new scan date, any new findings, and any updates applied.
 5. Mark the routine issue done. If Critical CVEs were found that cannot be patched, create a separate high-priority issue for each and escalate to CEO.
 
 ## Rules

package/templates/modules/game-design/agents/ceo/skills/game-design.fallback.md

@@ -4,7 +4,7 @@ The Game Designer or Engineer primarily owns the game design. You are the fallba
 
 ## Game Design (Fallback)
 
-1. If no `../../docs/GDD.md` exists and no one else has started:
+1. If no `docs/GDD.md` exists and no one else has started:
    - Write a minimal Game Design Document covering: concept pitch, core mechanic, basic game loop, target platform
    - List obvious design questions that need answers (progression, win conditions, art style)
    - Mark the document as **provisional** — it needs a thorough design review

package/templates/modules/game-design/agents/engineer/skills/game-design.fallback.md

@@ -4,7 +4,7 @@ The Game Designer primarily owns the game design. You are the engineering fallba
 
 ## Game Design (Fallback)
 
-1. If no `../../docs/GDD.md` exists and no Game Designer is active:
+1. If no `docs/GDD.md` exists and no Game Designer is active:
    - Write a minimal Game Design Document covering concept, core mechanic, game loop, platform, controls, and technical constraints.
    - Identify implementation risks: physics, input, asset pipeline, save state, performance, and browser/device support.
    - Mark open design questions explicitly so a Game Designer or CEO can resolve them later.

package/templates/modules/game-design/agents/game-designer/skills/game-design.md

@@ -4,7 +4,7 @@ You are the primary owner of the game design. This is your core responsibility.
 
 ## Game Design Document
 
-Create and maintain `../../docs/GDD.md` as the single source of truth. Cover every section thoroughly:
+Create and maintain `docs/GDD.md` as the single source of truth. Cover every section thoroughly:
 
 1. **Concept** — One-paragraph pitch. Genre, theme, target platform, target audience. What makes this game unique?
 2. **Core mechanic** — The central verb. Define precisely: input → action → feedback → consequence. What makes it feel good?
@@ -28,7 +28,7 @@ Create and maintain `../../docs/GDD.md` as the single source of truth. Cover eve
 
 After each playtest round:
 
-1. Read `../../docs/PLAYTEST-RESULTS.md` (if it exists).
+1. Read `docs/PLAYTEST-RESULTS.md` (if it exists).
 2. Identify the top 3 balance issues by player impact.
 3. Adjust tuning parameters with clear rationale.
 4. Update the GDD with new values.

package/templates/modules/game-design/module.meta.json

@@ -34,7 +34,7 @@
     {
       "title": "Create Game Design Document",
       "assignTo": "capability:game-design",
-      "description": "Define the game's core design: genre, core mechanic, game loop, progression system, win/lose conditions, control scheme, and target audience. Document everything in ../../docs/GDD.md. This is the single source of truth for what the game is."
+      "description": "Define the game's core design: genre, core mechanic, game loop, progression system, win/lose conditions, control scheme, and target audience. Document everything in docs/GDD.md. This is the single source of truth for what the game is."
     }
   ]
 }

package/templates/modules/game-design/skills/audio-design.fallback.md

@@ -4,9 +4,9 @@ The Audio Designer primarily owns the game's audio. You are the fallback — ste
 
 ## Audio Design (Fallback)
 
-1. If `../../docs/GDD.md` exists but there is no audio and no audio designer is active:
+1. If `docs/GDD.md` exists but there is no audio and no audio designer is active:
    - Add placeholder sounds for the gameplay-critical events first (player action, hit, pickup, success, failure) so feedback is legible.
-   - Note the intended character of each sound in `../../docs/AUDIO-DIRECTION.md` and mark it **provisional**.
+   - Note the intended character of each sound in `docs/AUDIO-DIRECTION.md` and mark it **provisional**.
    - Keep volumes in config, not hardcoded.
 2. If an audio designer is active, skip this entirely.
 

package/templates/modules/game-design/skills/audio-design.md

@@ -1,10 +1,10 @@
 # Skill: Audio Design
 
-You own the game's audio: sound effects, music, ambient soundscapes, and the systems that play them. You turn the audio direction in `../../docs/GDD.md` into concrete, production-quality audio.
+You own the game's audio: sound effects, music, ambient soundscapes, and the systems that play them. You turn the audio direction in `docs/GDD.md` into concrete, production-quality audio.
 
 ## Audio Design Document
 
-Create and maintain `../../docs/AUDIO-DIRECTION.md`. It must cover:
+Create and maintain `docs/AUDIO-DIRECTION.md`. It must cover:
 
 1. **Audio vision** — The feeling the audio should evoke and reference tracks/games. One paragraph.
 2. **Music** — Themes per context (menu, gameplay, boss, victory, defeat), tempo/mood, and whether audio is adaptive (layers/stems that respond to state).
@@ -18,7 +18,7 @@ Create and maintain `../../docs/AUDIO-DIRECTION.md`. It must cover:
 1. Produce audio with AI generation tools, code-based synthesis, or processing pipelines — whatever the tech stack supports.
 2. Replace any placeholder/programmer sounds the engineer added with production audio.
 3. Keep every gameplay-critical action audibly distinct — the player should recognize what happened without looking.
-4. On each heartbeat, if `../../docs/GDD.md` exists, check for new mechanics or events that lack audio and create issues to cover them.
+4. On each heartbeat, if `docs/GDD.md` exists, check for new mechanics or events that lack audio and create issues to cover them.
 
 ## Rules
 

package/templates/modules/game-design/skills/game-design.bar.md

@@ -1,7 +1,7 @@
 ## Game Design — Done Bar
 
 **Done:**
-- `../../docs/GDD.md` (Game Design Document) exists and covers all required sections: Overview, Core Loop, Game Mechanics, Progression System, Technical Constraints, and Art Direction.
+- `docs/GDD.md` (Game Design Document) exists and covers all required sections: Overview, Core Loop, Game Mechanics, Progression System, Technical Constraints, and Art Direction.
 - Tuning parameters are externalized: every balance-critical value (player speed, damage, cooldown, score multipliers) is defined as a named parameter with its default value and valid range documented in the GDD (format: `parameter_name: default (range: min–max)`). No magic numbers hardcoded in engine scripts without a GDD reference.
 - A playtest loop is defined: the GDD specifies at minimum one measurable success criterion per core loop iteration (e.g., "average session length > 8 minutes", "level 1 completion rate > 70%").
 - Art and audio direction are present: the GDD includes a visual style reference (mood board description or reference images) and an audio/music direction note.

package/templates/modules/game-design/skills/game-design.md

@@ -4,7 +4,7 @@ You own the Game Design Document (GDD) and the ongoing design of the game's mech
 
 ## Game Design Document
 
-Create and maintain `../../docs/GDD.md` as the single source of truth. It must cover:
+Create and maintain `docs/GDD.md` as the single source of truth. It must cover:
 
 1. **Concept** — One-paragraph pitch. Genre, theme, target platform, target audience.
 2. **Core mechanic** — The one thing the player does most. Define it precisely: input → action → feedback → consequence.
@@ -24,9 +24,9 @@ Create and maintain `../../docs/GDD.md` as the single source of truth. It must c
 
 ## Ongoing Design Work
 
-On each heartbeat when `../../docs/GDD.md` exists:
+On each heartbeat when `docs/GDD.md` exists:
 
-1. Review recent playtesting feedback (if `../../docs/PLAYTEST-RESULTS.md` exists).
+1. Review recent playtesting feedback (if `docs/PLAYTEST-RESULTS.md` exists).
 2. Identify mechanics that aren't working — not fun, confusing, or broken.
 3. Propose design changes with clear rationale: what's wrong, what to try, expected impact.
 4. Update tuning parameters based on playtest data.

package/templates/modules/game-design/skills/level-design.fallback.md

@@ -4,8 +4,8 @@ The Level Designer primarily owns level layout and pacing. You are the fallback
 
 ## Level Design (Fallback)
 
-1. If `../../docs/GDD.md` exists but no level structure has been defined and no level designer is active:
-   - Sketch a minimal progression in `../../docs/LEVEL-DESIGN.md`: an ordered list of levels/areas and the one mechanic or challenge each introduces.
+1. If `docs/GDD.md` exists but no level structure has been defined and no level designer is active:
+   - Sketch a minimal progression in `docs/LEVEL-DESIGN.md`: an ordered list of levels/areas and the one mechanic or challenge each introduces.
    - Set a rough difficulty curve (easy → hard) and place checkpoints generously.
    - Mark the document as **provisional** — it needs a dedicated level-design pass.
 2. If a level designer is active, skip this entirely.

package/templates/modules/game-design/skills/level-design.md

@@ -1,10 +1,10 @@
 # Skill: Level Design
 
-You own the layout, pacing, and difficulty progression of the game's playable spaces. You translate the mechanics defined in `../../docs/GDD.md` into concrete levels the player moves through.
+You own the layout, pacing, and difficulty progression of the game's playable spaces. You translate the mechanics defined in `docs/GDD.md` into concrete levels the player moves through.
 
 ## Level Design Document
 
-Create and maintain `../../docs/LEVEL-DESIGN.md`. It must cover:
+Create and maintain `docs/LEVEL-DESIGN.md`. It must cover:
 
 1. **Progression map** — The order players experience levels/areas, and what each one introduces (a new mechanic, enemy, or twist). Nothing should appear before it's taught.
 2. **Difficulty curve** — How challenge ramps across the game. Mark intended spikes (boss, finale) and recovery beats (safe rooms, low-stakes sections).
@@ -15,9 +15,9 @@ Create and maintain `../../docs/LEVEL-DESIGN.md`. It must cover:
 
 ## Ongoing Design Work
 
-On each heartbeat when `../../docs/GDD.md` exists:
+On each heartbeat when `docs/GDD.md` exists:
 
-1. If `../../docs/PLAYTEST-RESULTS.md` exists, look for levels where players got stuck, lost, or bored, and where the difficulty curve broke.
+1. If `docs/PLAYTEST-RESULTS.md` exists, look for levels where players got stuck, lost, or bored, and where the difficulty curve broke.
 2. Adjust layout, checkpoint placement, or pacing — change one variable at a time so cause and effect stay legible.
 3. Create issues for new levels, reworks, or difficulty passes, each tied to a specific player-experience problem.
 

package/templates/modules/github-repo/agents/engineer/skills/git-workflow.md

@@ -1,15 +1,15 @@
 # Skill: Git Workflow
 
-You work in a GitHub repository. Follow the conventions in `../../docs/git-workflow.md` in the project root. The PR-specific steps in that doc apply only to the PR fallback below and to the PR-review flow — your default without a review module is to work directly on the base branch.
+You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md` (paths in this skill are relative to your working directory, the company workspace). The PR-specific steps in that doc apply only to the PR fallback below and to the PR-review flow — your default without a review module is to work directly on the base branch.
 
 ## Direct-to-Base Flow (no pr-review module)
 
 Use this flow when the **pr-review module is not active** — there is no Code Reviewer and no executionPolicy review stages. With no reviewer, a per-change pull request adds no value and is exactly where branches pile up unmerged, so you work **directly on the base branch**: verify locally, then commit and push to the base ref. You open a PR only as a *fallback* when branch protection rejects the direct push.
 
-1. **Auth (first push on a project):** confirm the GitHub credential helper from `../../docs/git-workflow.md` → *GitHub Push Authentication* is installed in the primary repository. If `GH_TOKEN` is not injected or the helper cache is empty, stop and escalate instead of attempting unauthenticated pushes.
-2. **Resolve the base ref** from project workspace metadata or the issue's `heartbeat-context`. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from the current shell branch and never rewrite the configured ref. If none is configured, use whatever `origin/HEAD` points at (`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`.
-3. **Update to latest base:** `git fetch origin`, check out the base branch, and fast-forward: `git pull --ff-only origin <base-branch>` (`<base-branch>` = the plain name, strip any `origin/` prefix).
-4. **Make your changes** on the base branch (or a short-lived local branch you fast-forward back into the base before pushing — your choice). Do **not** open a GitHub PR.
+1. **Auth (first push on a project):** confirm the GitHub credential helper from `docs/git-workflow.md` → *GitHub Push Authentication* is installed in the primary repository. If `GH_TOKEN` is not injected or the helper cache is empty, stop and escalate instead of attempting unauthenticated pushes.
+2. **Resolve the base ref** from project workspace metadata or the issue's `heartbeat-context`. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from the current shell branch and never rewrite the configured ref. If none is configured, use whatever `origin/HEAD` points at (`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`.
+3. **Preserve the managed issue branch:** if Paperclip supplies `executionWorkspace.branchName`, verify `git branch --show-current` matches it, fetch, and rebase onto the configured base as needed. Do not switch or rename branches in a managed worktree. Only in an unmanaged, exclusively held checkout, check out the base and fast-forward with `git pull --ff-only origin <base-branch>`.
+4. **Make your changes** on that managed issue branch when supplied, otherwise on the base branch. Push HEAD to the base without switching the managed branch. Do **not** open a GitHub PR unless repository rules require it.
 5. **Run the authoritative gate locally — always:** lint, typecheck, the full test suite, and the build. Paste the real command output into the issue. **This local executed verification is the merge gate** when the company has no CI/CD module. Do not commit/push work whose local checks fail.
 6. **Commit** using Conventional Commits (`<type>: <description>`), referencing the issue in the body (e.g. `Closes YES-5`). Keep commits focused — one concern each.
 7. **Push to the base ref:** `git push origin HEAD:<base-branch>`.
@@ -17,31 +17,32 @@ Use this flow when the **pr-review module is not active** — there is no Code R
    - If the push is **rejected by branch protection** (e.g. "protected branch hook declined" / a PR is required), use the **PR fallback** below. This is the only case where you open a PR in this flow.
 8. **Confirm it landed:** `git log origin/<base-branch> -1` shows your commit.
 9. If the issue uses an isolated execution workspace (worktree), leave it reusable after the push. Do not archive/delete it during issue completion; workspace retirement is a separate board/operator action.
-10. **Company-owned CI/CD only:** if the `ci-cd` module is active and the base CI goes red after your push, run the baseline-emergency protocol in `../../docs/git-workflow.md` → *Base-branch-red deadlock*. A pre-existing repo check the company never configured is **advisory** — do not treat it as a gate or let it block your work.
+10. If required base CI goes red after your push, diagnose and repair it using `docs/git-workflow.md` → *Base-branch-red deadlock*. Required repository checks remain binding without the `ci-cd` module; only optional, non-required checks are advisory.
 
 ### PR fallback (only when branch protection requires a PR)
 
 If, and only if, a direct push is rejected by branch protection:
 
-1. Create a feature branch from the base ref: `git checkout -b <issue-id>-<short-desc> <base-ref>`.
+1. Retain Paperclip's managed issue branch when supplied. In an unmanaged checkout, create a feature branch from the current HEAD containing your delivery commits; do not reset to a stale base and lose the work from the rejected push.
 2. Push it: `git push -u origin <branch-name>`.
 3. Open a PR: `gh pr create --base <base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>` (plain base name; write the body to a temp file — never inline `--body "..."`). Register it as a work product (see below).
-4. Confirm it is not conflicting (`gh pr view <N> --json mergeable,mergeStateStatus`; resolve per *Resolving merge conflicts* if `CONFLICTING`/`DIRTY`), then merge it yourself: `gh pr merge <N> --merge --delete-branch`. Update the work product to `"status": "merged"`. Do not wait for a reviewer — there is none in this flow.
+4. Confirm it is not conflicting (`gh pr view <N> --json mergeable,mergeStateStatus`; resolve per *Resolving merge conflicts* if `CONFLICTING`/`DIRTY`) and required checks/rules are satisfied, then merge it yourself: `gh pr merge <N> --merge`. Preserve the managed issue branch and workspace. Update the work product to `"status": "merged"`. Obtain any reviewer required by existing repository rules.
 
-The cleanest fix, though, is to not require a PR for an unreviewed company: see *Branch Protection Setup*.
+Respect the repository's existing rules when choosing this flow; see *Branch Protection Setup*.
 
 ## Branch Protection Setup
 
 Configure branch protection once during initial repository setup (part of the "Prepare GitHub repository" foundation issue).
 
-- **No pr-review module (this flow):** do **not** require pull requests — the team pushes directly to the base ref. Leave the base branch pushable (no `required_pull_request_reviews`). You may still set `required_status_checks` to the company's own CI contexts **only if the `ci-cd` module is active**; otherwise leave it `null` so no external/inherited check can block pushes.
-- **With pr-review active:** require a PR before merging, but do **not** require GitHub-native approving reviews — all agents share one GitHub account and cannot formally approve their own PRs (unless the project has distinct non-author reviewer credentials). See `skills/pr-workflow.md`.
+- Inspect and preserve existing branch protection, required checks, and organization rules before configuring anything. Never clear them with null defaults or weaken them to accommodate shared credentials. Existing requirements need eligible credentials or an explicit repository-owner decision.
+- **No pr-review module (this flow):** on a new repository, direct pushes may be allowed under company policy. On an existing repository, follow its rules and use the PR fallback when required. Absence of the `ci-cd` module does not disable required checks.
+- **With pr-review active:** require a PR before merging, but do **not** require GitHub-native approving reviews — all agents share one GitHub account and cannot formally approve their own PRs (unless the project has distinct non-author reviewer credentials). See your installed `pr-workflow` skill.
 
 Escalate to CEO if `GH_TOKEN` does not have admin rights on the repository.
 
 ## When PR Review IS Active
 
-If the pr-review module is active, do NOT use the Direct-to-Base Flow. Use the PR Workflow skill (`skills/pr-workflow.md`): open a PR, set the executionPolicy review stages, and let the Code Reviewer (the non-author merge gate) land the branch. Never push directly to the base ref when a PR review workflow is in place.
+If the pr-review module is active, do NOT use the Direct-to-Base Flow. Use your installed `pr-workflow` skill: open a PR, set the executionPolicy review stages, and let the Code Reviewer (the non-author merge gate) land the branch. Never push directly to the base ref when a PR review workflow is in place.
 
 ## Register the PR as a Work Product
 
@@ -78,7 +79,7 @@ Notes:
 - Before marking `done`, verify there is no uncommitted work (`git status --short` should be clean) and that `git log origin/<base-branch> -1` shows your commit landed.
 - If no repository change is required, do not mark `done` silently: leave an issue comment explaining why and escalate to the CEO.
 - **Default to a direct push to the base ref.** Open a PR only when branch protection rejects the direct push (the PR fallback) or when the pr-review module is active. Do not open a PR per change for an unreviewed company — that is where unmerged branches accumulate.
-- **CI is a gate only for company-owned CI/CD (`ci-cd` module active).** Without it, your local lint/test/build is the authoritative gate; treat any pre-existing repo checks as advisory and never block a merge/push solely on an external check the company never configured.
+- **Required CI and repository rules remain binding**, regardless of who configured them or whether the `ci-cd` module is selected. Only optional, non-required checks are advisory. Use the complete local verification gate when required CI does not exist.
 
 ## Resolving merge conflicts
 
@@ -92,6 +93,6 @@ For the **PR fallback** when `gh pr merge` fails or `gh pr view <N> --json merge
 4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
 5. `git push --force-with-lease origin <branch-name>` — never `--force`.
 6. Verify: `gh pr view <N> --json mergeable` returns `MERGEABLE`.
-7. Retry: `gh pr merge <N> --merge --delete-branch`.
+7. Retry: `gh pr merge <N> --merge`. Preserve a managed issue branch and its workspace after merge.
 
 If a conflict is too complex to resolve safely, leave an issue comment describing the exact conflict and escalate to the CEO before abandoning the branch.

package/templates/modules/github-repo/docs/git-workflow.md

@@ -81,22 +81,22 @@ Rules:
 
 ## Direct-to-Base Flow
 
-Use this flow when the **pr-review module is not active** (no Code Reviewer role, no executionPolicy review stages). With no reviewer, a per-change pull request adds no value and is where branches pile up unmerged, so you work **directly on the base branch**: verify locally, then commit and push to the base ref. Open a PR only as a *fallback* when branch protection rejects the direct push. When PR review is active, use the PR workflow from `../../docs/pr-conventions.md` instead.
+Use this flow when the **pr-review module is not active** (no Code Reviewer role, no executionPolicy review stages). With no reviewer, a per-change pull request adds no value and is where branches pile up unmerged, so you work **directly on the base branch**: verify locally, then commit and push to the base ref. Open a PR only as a *fallback* when branch protection rejects the direct push. When PR review is active, use the PR workflow from `docs/pr-conventions.md` instead.
 
 1. Resolve the configured base ref from project workspace metadata or the issue's `heartbeat-context` before touching Git. Do not infer it from the current shell branch and do not rewrite it to `main`, `master`, or `origin/*`.
    - External repos: use the project/worktree `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as configured.
    - Fresh/local repos: use the configured local branch.
    - Only if no base ref is configured anywhere, detect the repository's default branch — see *Resolving the default branch* below. Never hard-code `main`.
-2. Update to latest base: `git fetch origin`, check out the base branch, `git pull --ff-only origin <base-branch>` (`<base-branch>` = plain name, strip any `origin/` prefix).
-3. Make changes (on the base branch, or a short-lived local branch you fast-forward back into the base before pushing). Do not open a GitHub PR.
+2. Inspect the resolved workspace. If Paperclip supplied a managed issue branch (`executionWorkspace.branchName`), verify the current branch matches it and keep that branch; do not check out the base inside the managed worktree. Fetch and rebase that branch onto the configured base if needed. In an unmanaged, exclusively held checkout, `git fetch origin`, check out the base branch, and `git pull --ff-only origin <base-branch>` (`<base-branch>` = plain name, strip any `origin/` prefix).
+3. Make changes on the managed issue branch when supplied, otherwise on the base branch. A direct-to-base delivery can push the managed branch's HEAD to the base without switching branches. Do not open a GitHub PR unless repository rules require one.
 4. **Run the authoritative gate locally — always:** lint, typecheck, the full test suite, and the build; paste the real output into the issue. This local executed verification is the merge gate when the company has no CI/CD module.
 5. Commit with a Conventional Commit message, referencing the issue in the body (`Closes <issue-id>`).
 6. Push to the base ref: `git push origin HEAD:<base-branch>`.
    - Rejected as **non-fast-forward**: `git pull --rebase origin <base-branch>`, re-run checks, push again.
-   - Rejected by **branch protection** (PR required): use the PR fallback — feature branch → `git push -u origin <branch-name>` → `gh pr create --base <base-branch> ... --body-file <file>` (register the PR as a work product) → `gh pr merge <N> --merge --delete-branch`. This is the only case where you open a PR.
+   - Rejected by **branch protection** (PR required): use the PR fallback — retain the managed issue branch, or create a feature branch in an unmanaged checkout → `git push -u origin <branch-name>` → `gh pr create --base <base-branch> ... --body-file <file>` (register the PR as a work product) → `gh pr merge <N> --merge`. Preserve the branch and workspace after merge. This is the only case where you open a PR.
 7. Confirm it landed: `git log origin/<base-branch> -1` shows your commit.
 8. If the issue uses an isolated execution workspace (worktree), leave it reusable after the push. Do not archive/delete it during issue completion; workspace retirement is a separate board/operator action.
-9. **Company-owned CI/CD only** (`ci-cd` module active): if the base CI goes red after your push, fix it immediately (see *Base-branch-red deadlock*). A pre-existing repo check the company never configured is advisory — not a gate.
+9. If required base CI goes red after your push, diagnose and repair it (see *Base-branch-red deadlock*). Existing required checks remain binding even without the `ci-cd` module; only optional, non-required checks are advisory.
 
 ## Resolving the default branch
 
@@ -140,7 +140,7 @@ For a brand-new local repository there is no remote yet, so initialize on `main`
 
 ## Branch Safety
 
-- **Match the branch to the flow.** In the **Direct-to-Base Flow** (no pr-review module) you commit on the base ref and push to it directly — that is intended. In the **PR-review flow** (and the PR fallback) you must work on a feature branch and never push the base ref as a feature branch: before `git push -u origin <branch-name>`, confirm `git branch --show-current` prints the feature branch name, not the base ref.
+- **Preserve managed branch identity.** When Paperclip supplies `executionWorkspace.branchName`, keep the checkout on that branch throughout the run; finalization validates the persisted branch identity. Direct-to-base delivery may push its HEAD to the base without switching. In unmanaged checkouts, match the branch to the selected flow. Before a PR push, verify `git branch --show-current` is the intended feature branch, not the base ref.
 - **Always pull/fast-forward before pushing to the base ref** so your push is a fast-forward; if it is rejected as non-fast-forward, `git pull --rebase` and retry. Never force-push the base branch.
 
 ## Resolving merge conflicts
@@ -181,7 +181,7 @@ If the base is red, classify the situation **BASE-BRANCH-RED** and run the basel
 When the base branch's CI is red:
 
 1. **Pause new feature PRs.** Do not open new feature PRs on a red base — they inherit the failure and pile up. In-flight branches can finish, but leave them unmerged with an issue comment tagged `waiting-on-baseline` until the base is green.
-2. **Claim and fix main first.** The first agent to detect BASE-BRANCH-RED claims the restore by commenting on the triage issue (or creating one) so concurrent detectors do not open duplicate restore PRs. Create a single baseline-restore PR from the base ref that fixes the base failure (CI config, the failing code path, or the secret/scan config). Title it `fix(ci): restore base CI` (or `fix: restore base — <cause>`). Scope the diff to the failure fix only — no feature work in this PR.
+2. **Assign and restore the configured base first.** The first detector records BASE-BRANCH-RED evidence and routes it to the backlog owner/CEO, who deduplicates detections into one separately owned baseline-restore issue with an explicit implementation assignee. Do not self-claim additional work or use a feature issue's workspace for the repair. The assigned owner creates a single baseline-restore branch/PR from the configured base ref that fixes the base failure (CI config, the failing code path, or the secret/scan config). Title it `fix(ci): restore base CI` (or `fix: restore base — <cause>`). Scope the diff to the failure fix only — no feature work in this PR.
 3. **Fast-track the baseline-restore PR.** Its own CI will still show the inherited base failure (the base is red), so the normal "green CI" gate cannot pass. The merge owner (the Code Reviewer in PR-Gate mode, or the engineer in Self-Merge mode) merges it under the narrow exception below.
 4. **Re-verify the base.** After the baseline-restore PR merges, re-run CI on the base: `gh api repos/{owner}/{repo}/commits/<new-base-sha>/check-runs`. If still red, repeat from step 2. Once the base is green:
 5. **Drain the queue.** Rebase each queued feature PR onto the now-green base (`git rebase origin/<base-branch>`, resolve, `git push --force-with-lease`), re-run checks, and merge in order. The inherited baseline failures are gone, so feature PR CI now reflects only their own diffs.

package/templates/modules/github-repo/module.meta.json

@@ -9,7 +9,7 @@
       "priority": "critical",
       "bootstrapPhase": "foundation",
       "labels": ["chore"],
-      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize the local workspace with a README or bootstrap commit, add origin, push the default branch (`main` for a fresh repo), and record the repository URL. For an existing repository, verify the workspace has a reachable remote and a starter commit state, then determine the repository's default branch and confirm it is recorded as the project workspace `defaultRef`/`repoRef` so isolated worktrees branch from the correct base. The default branch is whatever `origin/HEAD` points at — name-agnostic (`main`, `master`, `trunk`, etc.); use it exactly as the remote advertises it (`git ls-remote --symref origin HEAD`). Only if the remote advertises no default HEAD, fall back to `main`, then `master`. Never assume `main` for an existing repo. Install the Paperclip GitHub credential helper from `../../docs/git-workflow.md` before the first push so `git push` uses the injected `GH_TOKEN` project secret even when sandboxed subprocesses strip environment variables at credential-lookup time. Escalate to CEO if repo setup or `GH_TOKEN` is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
+      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize the local workspace with a README or bootstrap commit, add origin, push the default branch (`main` for a fresh repo), and record the repository URL. For an existing repository, verify the workspace has a reachable remote and a starter commit state, then determine the repository's default branch and confirm it is recorded as the project workspace `defaultRef`/`repoRef` so isolated worktrees branch from the correct base. The default branch is whatever `origin/HEAD` points at — name-agnostic (`main`, `master`, `trunk`, etc.); use it exactly as the remote advertises it (`git ls-remote --symref origin HEAD`). Only if the remote advertises no default HEAD, fall back to `main`, then `master`. Never assume `main` for an existing repo. Install the Paperclip GitHub credential helper from `docs/git-workflow.md` before the first push so `git push` uses the injected `GH_TOKEN` project secret even when sandboxed subprocesses strip environment variables at credential-lookup time. Escalate to CEO if repo setup or `GH_TOKEN` is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
     }
   ]
 }

package/templates/modules/lean-delivery/docs/lean-delivery.md

@@ -0,0 +1,15 @@
+# Lean Delivery Contract
+
+This contract is binding only when the optional `lean-delivery` module is selected during company setup. It replaces the standard staged PR-review workflow with one merge gate; `pr-review` alone does not enable it. Neither mode imposes a numeric PR cap. API authorization, workspace safety, and explicit company/board requirements still apply.
+
+1. **One origin issue, one implementation owner, one PR.** Work only on explicitly assigned, acceptance-ready issues; do not self-claim unassigned work. Keep implementation, verification, corrections, PR-introduced CI repair, merge-conflict repair, and merge evidence on the originating issue and existing branch/PR. **Inherited BASE-BRANCH-RED is the narrow exception:** leave the feature issue/PR waiting and route the baseline repair to exactly one separately owned baseline-restore issue, branch, and PR created from the base ref, following the baseline-emergency protocol in `docs/git-workflow.md`; never mix that unrelated repair into the feature PR.
+2. **Product before code.** Freeze outcome and acceptance criteria before assignment. Product Owner is not a routine post-code stage; request one same-issue decision only for unresolved scope, release, legal, licensing, or residual-risk acceptance.
+3. **Exactly one default executionPolicy stage.** Use the non-author Code Reviewer as the sole default approval/merge gate. If no eligible non-author Code Reviewer is present, set no stages and use the documented self-merge path. QA, Security, UX, Product, and DevOps provide bounded evidence only when a concrete trigger applies; they are not a serial chain. Before opening the gate, assign the originating issue to each triggered specialist for one bounded check, then return it to the implementation owner. Assignment is the wake signal; a passive comment is not.
+4. **No handoff ping-pong.** A specialist finding returns directly to the same implementation owner and PR. Specialists do not hand the issue to one another, and resolved evidence is not replayed after every correction.
+5. **No technical board deadlock.** Technical defects, stale bases, merge conflicts, missing tests, and incomplete acceptance criteria return to the implementation owner with one precise action. Never assign the board user as an execution participant for technical repair. Use a first-class interaction/approval only for a genuine human decision.
+6. **Exact-head verification.** The author runs focused checks. When required company CI is green on the exact reviewed head, the Code Reviewer verifies head/base/check identity and adds only the smallest independent risk check. Run the complete local lint/test/typecheck/build gate once only when required checks do not yet exist or CI is unavailable. Pending or failed required checks are not unavailable CI: wait for or repair them rather than substituting local output. Inherited base-red uses only the documented baseline-restore exception.
+7. **Status semantics.** `in_review` requires a runtime-recognized action path such as the Code Reviewer executionPolicy stage or a first-class human interaction/approval. Agent reassignment alone is not a no-policy review path. `blocked` means a real unresolved dependency or external gate, not ordinary review waiting or workspace cleanup.
+8. **No issue factories.** Do not create review-only, evidence-only, queue-drain, status-repair, summary, watchdog, or workspace-cleanup wrapper issues. Create a follow-up only for independently deliverable, non-blocking work outside current acceptance criteria. The single separately owned baseline-restore issue/PR required for inherited BASE-BRANCH-RED is operational repair, not a review wrapper; deduplicate concurrent detections into that one repair.
+9. **Parallel delivery.** Open PR count is advisory, not a dispatch freeze. Continue assigning independent acceptance-ready work while every PR has an owner and concrete next action. Prioritize stale, conflicting, red, or ownerless PR repair without blocking unrelated implementation, and never model open-PR count as issue dependencies.
+10. **Decision record.** Every handoff comment names the full `owner/repo#number`, exact head/base, checks, decision, next owner, and next action. A bare PR number is not globally unique.
+11. **Verify effective state.** Approval, custodian attestation, or configuration text authorizes verification but is not proof that access or a capability works. Before closure, probe from the intended consumer runtime and re-read the final remote PR head; recheck previously resolved findings against that effective state.

package/templates/modules/lean-delivery/module.meta.json

@@ -0,0 +1,6 @@
+{
+  "name": "lean-delivery",
+  "description": "Optional lean delivery: one non-author Code Reviewer merge gate, risk-triggered specialist evidence, and same-issue correction loops. Open PR count is advisory, not a numeric assignment cap. Opt in during setup; without this module, PR review retains its role-based stages.",
+  "requires": ["pr-review"],
+  "capabilities": []
+}

package/templates/modules/market-analysis/agents/ceo/skills/market-analysis.fallback.md

@@ -4,10 +4,10 @@ The UX Researcher, CMO, and PO all own market research above you. You are the la
 
 ## Market Analysis (Fallback)
 
-1. If no `../../docs/MARKET-ANALYSIS.md` exists and the PO hasn't started:
+1. If no `docs/MARKET-ANALYSIS.md` exists and the PO hasn't started:
    - Write a brief competitive landscape overview
    - Identify the top 2-3 competitors and key differentiators
-   - Document in `../../docs/MARKET-ANALYSIS.md`
+   - Document in `docs/MARKET-ANALYSIS.md`
    - Tag the researcher, CMO, or PO to expand and maintain the analysis
 2. If the researcher, CMO, or PO is active, skip this entirely.
 

package/templates/modules/market-analysis/agents/cmo/skills/market-analysis.fallback.md

@@ -4,11 +4,11 @@ The UX Researcher primarily owns market research and competitive analysis. You a
 
 ## Market Analysis (Fallback)
 
-1. If no `../../docs/MARKET-ANALYSIS.md` exists and the researcher hasn't started:
+1. If no `docs/MARKET-ANALYSIS.md` exists and the researcher hasn't started:
    - Define market positioning and target audience from a marketing perspective
    - Identify the top 3-5 competitors with competitive differentiators
    - Outline go-to-market considerations and messaging angles
-   - Document in `../../docs/MARKET-ANALYSIS.md`
+   - Document in `docs/MARKET-ANALYSIS.md`
    - Tag the researcher or PO to expand with user research data
 2. If the researcher or PO is active, skip this entirely.
 

package/templates/modules/market-analysis/agents/product-owner/skills/market-analysis.fallback.md

@@ -4,11 +4,11 @@ The UX Researcher and CMO primarily own market research. You are the fallback
 
 ## Market Analysis (Fallback)
 
-1. If no `../../docs/MARKET-ANALYSIS.md` exists and no one above you has started:
+1. If no `docs/MARKET-ANALYSIS.md` exists and no one above you has started:
    - Write a brief competitive landscape overview from a product perspective
    - Identify the top 2-3 competitors and key differentiators
    - Note user pain points and unmet needs relevant to the product roadmap
-   - Document in `../../docs/MARKET-ANALYSIS.md`
+   - Document in `docs/MARKET-ANALYSIS.md`
    - Tag the researcher or CMO to expand with deeper research
 2. If the researcher or CMO is active, skip this entirely.
 

package/templates/modules/market-analysis/agents/ux-researcher/skills/market-analysis.md

@@ -5,14 +5,14 @@ You own market research with a focus on user needs and behavior. This is your co
 ## Market Analysis Process
 
 1. Review the company goal and project description
-2. Research and document in `../../docs/MARKET-ANALYSIS.md`:
+2. Research and document in `docs/MARKET-ANALYSIS.md`:
    - **Target users**: Detailed user profiles, needs, pain points, current workarounds
    - **User segments**: Primary, secondary, and edge-case user groups
    - **Competitors**: How competitors serve these users, where they fall short
    - **Positioning**: Where the biggest user need gaps are
    - **Risks**: Adoption barriers, user switching costs, behavioral resistance
 3. Create follow-up issues for deeper research if needed:
-   - `POST /api/companies/{companyId}/issues` for user interview plans, usability benchmarks. 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 user interview plans or usability benchmarks. 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. Share findings by updating the assigned issue/document and assigning concrete follow-up actions to the Product Owner and CEO when needed; do not rely on generic @-mentions.
 
 ## Rules

package/templates/modules/market-analysis/module.meta.json

@@ -17,7 +17,7 @@
     {
       "title": "Conduct initial market analysis",
       "assignTo": "capability:market-analysis",
-      "description": "Research the target market, identify competitors, analyze positioning opportunities, and document findings in ../../docs/MARKET-ANALYSIS.md. This informs the product roadmap and strategic priorities."
+      "description": "Research the target market, identify competitors, analyze positioning opportunities, and document findings in docs/MARKET-ANALYSIS.md. This informs the product roadmap and strategic priorities."
     }
   ]
 }

package/templates/modules/market-analysis/skills/market-analysis.bar.md

@@ -2,7 +2,7 @@
 
 A good market analysis:
 
-- A `../../docs/MARKET-ANALYSIS.md` that covers: target market (who the users are and what problem is being solved), a competitor breakdown with each player's strengths and weaknesses, a clear positioning statement with a unique value proposition, and identified market/adoption risks.
+- A `docs/MARKET-ANALYSIS.md` that covers: target market (who the users are and what problem is being solved), a competitor breakdown with each player's strengths and weaknesses, a clear positioning statement with a unique value proposition, and identified market/adoption risks.
 - Each insight is evidence-based and tied to a concrete product decision or follow-up action.
 
 Not done:

package/templates/modules/market-analysis/skills/market-analysis.md

@@ -5,13 +5,13 @@ You own market research and competitive analysis. This informs the product roadm
 ## Market Analysis Process
 
 1. Review the company goal and project description
-2. Research and document in `../../docs/MARKET-ANALYSIS.md`:
+2. Research and document in `docs/MARKET-ANALYSIS.md`:
    - **Target market**: Who are the users? What problem are we solving?
    - **Competitors**: Who else operates in this space? What are their strengths and weaknesses?
    - **Positioning**: How do we differentiate? What's our unique value proposition?
    - **Risks**: Market risks, timing risks, adoption barriers
 3. Create follow-up issues for any strategic decisions needed:
-   - `POST /api/companies/{companyId}/issues` with findings that require input. 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 findings that require input. 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/monitoring/agents/devops/skills/monitoring.md

@@ -11,7 +11,7 @@ You are the DevOps engineer and observability is your core domain. You own the f
 5. Define alert thresholds for key metrics (error rate, latency, uptime, resource usage).
 6. Set up dashboards for operational visibility (API latency, error rates, infrastructure health).
 7. Configure on-call routing and escalation policies.
-8. Document the full observability strategy in `../../docs/MONITORING.md`.
+8. Document the full observability strategy in `docs/MONITORING.md`.
 
 ## Rules
 

package/templates/modules/monitoring/agents/engineer/skills/monitoring.fallback.md

@@ -4,10 +4,10 @@ The DevOps engineer primarily owns monitoring and observability. You are the fal
 
 ## Monitoring (Fallback)
 
-1. If no `../../docs/MONITORING.md` exists and DevOps hasn't started:
+1. If no `docs/MONITORING.md` exists and DevOps hasn't started:
    - Add basic health check endpoints (liveness and readiness probes returning 200)
    - Set up structured JSON logging with timestamp, level, and service fields
-   - Document the setup in `../../docs/MONITORING.md`
+   - Document the setup in `docs/MONITORING.md`
    - Mark the strategy as **provisional** — it needs DevOps review for alerting, dashboards, and SLOs
 2. If DevOps is active, skip this entirely.
 

package/templates/modules/monitoring/module.meta.json

@@ -18,7 +18,7 @@
     {
       "title": "Set up monitoring and observability",
       "assignTo": "capability:monitoring",
-      "description": "Configure health checks, error tracking, logging, and alerting. Document the observability strategy in ../../docs/MONITORING.md."
+      "description": "Configure health checks, error tracking, logging, and alerting. Document the observability strategy in docs/MONITORING.md."
     }
   ]
 }

package/templates/modules/monitoring/skills/monitoring.bar.md

@@ -2,7 +2,7 @@
 
 A good monitoring setup:
 
-- Health check endpoints (liveness + readiness) for all services, error tracking with full context (request ID, user, stack trace), structured JSON logs with consistent fields (timestamp, level, service, correlation ID), and alert thresholds for key metrics (error rate, latency, uptime), all documented in `../../docs/MONITORING.md`.
+- Health check endpoints (liveness + readiness) for all services, error tracking with full context (request ID, user, stack trace), structured JSON logs with consistent fields (timestamp, level, service, correlation ID), and alert thresholds for key metrics (error rate, latency, uptime), all documented in `docs/MONITORING.md`.
 - Every alert is symptom-based (user impact), actionable, and has a runbook — no alert fires without a documented response.
 
 Not done:

package/templates/modules/monitoring/skills/monitoring.md

@@ -1,6 +1,6 @@
 # Skill: Monitoring
 
-You are responsible for setting up observability, alerting, and health checks for the project. Follow the conventions in `../../docs/MONITORING.md` in the project root.
+You are responsible for setting up observability, alerting, and health checks for the project. Follow the conventions in `docs/MONITORING.md` (paths in this skill are relative to your working directory, the company workspace).
 
 ## Steps
 
@@ -9,8 +9,8 @@ You are responsible for setting up observability, alerting, and health checks fo
 3. Configure error tracking — capture unhandled exceptions with context (request ID, user, stack trace).
 4. Set up structured logging — all log output must be machine-parseable JSON with consistent fields.
 5. Define alert thresholds for key metrics (error rate, latency, uptime, resource usage).
-6. Set up a basic operational dashboard (in the monitoring tool configured for this project) showing: request rate, error rate, latency (p50/p99), and the key health indicators defined above. Document the dashboard URL/name in `../../docs/MONITORING.md`.
-7. Document the full observability strategy in `../../docs/MONITORING.md`.
+6. Set up a basic operational dashboard (in the monitoring tool configured for this project) showing: request rate, error rate, latency (p50/p99), and the key health indicators defined above. Document the dashboard URL/name in `docs/MONITORING.md`.
+7. Document the full observability strategy in `docs/MONITORING.md`.
 
 ## Rules