@starlein/paperclip-plugin-company-wizard 0.4.13 → 0.4.17

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 every sec
 
 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 cover:
 
 ## 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,59 +1,51 @@
 # Skill: Git Workflow
 
-You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md` in the project root.
-
-## PR Self-Merge Flow (no pr-review module)
-
-Use this flow when the **pr-review module is not active**. You open a PR and merge it yourself — there is no external review gate, but all changes go through a PR so the branch history is preserved and branch protection is respected.
-
-1. Before the 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 to `main`, `master`, or `origin/*`. If no base ref is configured anywhere, use the repository's actual default branch — whatever `origin/HEAD` points at, regardless of name (`main`/`master`/`trunk`/…); fall back to `main` then `master` only if the remote advertises no default HEAD. See `docs/git-workflow.md` → *Resolving the default branch*. Never hard-code `main`.
-3. Pull/update latest from that base:
-   - external: `git fetch origin`, then integrate from the configured base ref
-   - local: update from the configured local branch
-4. **Create a feature branch** from the base ref: `git checkout -b <branch-name> <base-ref>`. Never commit directly on the base branch. The branch name should reference the issue (e.g., `LEA-5-add-landing-hero`). If you are already on a correctly named feature branch, skip this step.
-5. Verify you are on the feature branch before making changes: `git branch --show-current` must print `<branch-name>`, not the base ref. If it prints the base ref name, you forgot step 4 — create the branch now.
-6. Make your changes
-7. Run available checks (lint, typecheck, tests)
-8. Commit using Conventional Commits: `<type>: <description>`
-9. Verify the current branch one more time, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-10. Open a pull request against the base ref: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body to a temp file first — never inline `--body "..."`. Register the PR as a Paperclip work product (see *Register the PR as a Work Product* below). Verify the PR base matches the configured base ref before merging.
-11. Before merging, check that the PR is not conflicting: `gh pr view <PR-number> --json mergeable,mergeStateStatus`. If `mergeable` is `CONFLICTING` or `mergeStateStatus` is `DIRTY`, resolve the conflict before merging — see *Resolving merge conflicts* below. Also check CI: `gh pr checks <PR-number>`. If CI is failing, run the **base-branch-red detection** in `docs/git-workflow.md` → *Base-branch-red deadlock* before merging — a red base poisons every PR and a feature PR on a red base must not merge. Follow the baseline-emergency protocol there (fix main first, then drain the queue).
-12. Merge the PR yourself: `gh pr merge <PR-number> --merge`. After opening the PR, merge it yourself promptly — do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing. **Baseline-restore exception (Self-Merge mode):** if this PR is the `fix(ci): restore base CI` PR opened under a declared baseline emergency, its CI will still be red from the inherited base failure — you may merge it via `gh pr merge <PR-number> --merge` despite red CI, provided you ran the exact failing checks locally and pasted the passing output into the issue, and the remaining failing checks are exactly the inherited baseline failures. See `docs/git-workflow.md` → *Narrow exception*. This exception never applies to a feature PR.
-13. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local). Update the Paperclip work product to `"status": "merged"` via `PATCH /api/work-products/{workProductId}`.
-14. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
-15. If CI fails on the base branch after the merge, run the baseline-emergency protocol in `docs/git-workflow.md` → *Base-branch-red deadlock* (detect base-red, fix main first with a `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base is green, then rebase and drain the feature-PR queue). A red base blocks everyone — do not leave it red and do not pile new feature PRs onto it.
+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.
+
+## 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.
+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>`.
+   - If the push is **rejected as non-fast-forward** (someone else pushed), `git pull --rebase origin <base-branch>`, re-run the checks, and push again.
+   - 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), archive it from your `heartbeat-context` after the push.
+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.
+
+### 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>`.
+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.
+
+The cleanest fix, though, is to not require a PR for an unreviewed company: see *Branch Protection Setup*.
 
 ## Branch Protection Setup
 
-Configure branch protection once during initial repository setup (this is part of the "Prepare GitHub repository" foundation issue). Branch protection must require a PR before merging but must 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 GitHub reviewer credentials, in which case `required_approving_review_count` may be raised).
+Configure branch protection once during initial repository setup (part of the "Prepare GitHub repository" foundation issue).
 
-```bash
-gh api repos/{owner}/{repo}/branches/{base}/protection \
-  --method PUT --input - <<'EOF'
-{
-  "required_status_checks": null,
-  "enforce_admins": true,
-  "required_pull_request_reviews": {
-    "required_approving_review_count": 0,
-    "dismiss_stale_reviews": false
-  },
-  "restrictions": null
-}
-EOF
-```
+- **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`.
 
-Replace `{owner}`, `{repo}`, `{base}` with the actual values. `enforce_admins: true` so the shared admin account cannot bypass the PR requirement with a direct push — with `required_approving_review_count: 0` the admin can still open a PR and merge it with zero approvals, so the self-merge flow keeps working. `restrictions: null` means no push allowlist; the PR gate still applies (do not "fix" it with an empty array, which would block all pushes). If CI is configured (e.g. the ci-cd module is active), replace `"required_status_checks": null` with the CI context string instead of `null`. Escalate to CEO if `GH_TOKEN` does not have admin rights on the repository.
+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 PR Self-Merge Flow. Instead, use the PR Workflow skill (`skills/pr-workflow.md`):
-- **With a Code Reviewer on the team (PR-Gate mode):** Open a PR, set executionPolicy review stages, and let the Code Reviewer (non-author merge gate) land the branch. Never merge your own branch in this mode.
-- **Without a Code Reviewer (PR Self-Merge Flow):** Open a PR via `gh pr create`, but skip executionPolicy stages entirely. Other review roles (qa, product-owner, security-engineer) may leave advisory comments. Merge the PR yourself via `gh pr merge <N> --merge` once CI is green. See `skills/pr-workflow.md` step 12 for the full self-merge path.
+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.
 
 ## Register the PR as a Work Product
 
-Whenever you open a pull request (via `gh pr create`), immediately register it as a Paperclip work product so it shows up on the issue and the board. Creating the PR on GitHub alone does **not** make it visible in Paperclip.
+Whenever you open a pull request (the PR fallback, or the pr-review flow), immediately register it as a Paperclip work product so it shows up on the issue and the board. Creating the PR on GitHub alone does **not** make it visible in Paperclip.
 
 ```
 POST /api/issues/{issueId}/work-products
@@ -71,36 +63,35 @@ Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLI
 
 Notes:
 - `title` and `url` are required; `url` must be the full PR URL.
-- If the issue runs in an isolated execution workspace, also pass `"executionWorkspaceId"` from your `heartbeat-context` so the PR is linked to that worktree.
+- If the issue runs in an isolated execution workspace, also pass `"executionWorkspaceId"` from your `heartbeat-context`.
 - When the PR later merges or closes, update the work product (`PATCH /api/work-products/{workProductId}`) with `"status": "merged"` or `"closed"`.
 
 ## Rules
 
-- Always pull before starting work to avoid conflicts.
+- Always fetch/pull before starting work to avoid conflicts.
 - Keep commits focused — one concern per commit.
 - Never force push to the base branch.
-- Use the configured base ref. For external repos, branch and compare from the configured remote/ref and push/merge back to the matching remote branch.
+- Use the configured base ref. For external repos, push back to the matching remote branch.
 - Treat push authentication as repository setup, not as an issue blocker. If `git push` says credentials are missing or invalid, verify the helper and `GH_TOKEN` binding first.
-- If `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY`, resolve the conflict before retrying — see *Resolving merge conflicts* below. Never leave a PR in an unresolved conflicting state without either fixing it or leaving an explicit issue comment with the blocker.
 - Reference the issue ID in the commit body (e.g., `Closes YES-5`).
-- Never mark an issue as `done` unless at least one new commit was created for that issue's work and has been pushed.
-- Before marking `done`, verify there is no uncommitted work (`git status --short` should be clean).
-- If no repository change is required, do not mark `done` silently: leave an issue comment explaining why no code change was needed and escalate to the CEO for decision.
-- You are always the merge owner when no code-reviewer is present. Open a PR and merge it yourself via `gh pr merge <N> --merge` promptly — do not leave branches dangling unmerged. Never do a direct `git merge` + push to the base branch; always go through a PR so the branch history is preserved and branch protection is respected (typos/comment-only/doc fixes with an issue reference may be committed directly to the base ref only when branch protection allows it — see `docs/git-workflow.md` → *Dev Cycle Rules*).
-- **Always work on a feature branch, never on the base branch.** Create the branch with `git checkout -b <branch-name> <base-ref>` before committing. Verify with `git branch --show-current` before every push.
-- **Never push the base ref as if it were a feature branch.** Before `git push -u origin <branch-name>`, confirm that `git branch --show-current` matches `<branch-name>`. If it prints the base ref name instead, you are on the wrong branch — create or switch to the feature branch first.
-- **Do not open new feature PRs on a red base.** When the base branch's CI is red, every PR inherits the failure at baseline setup and the queue deadlocks under "never merge without green CI". Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock* and run the baseline-emergency protocol (fix main first, fast-track the baseline-restore PR, then drain the queue) before opening or merging feature PRs.
+- Never mark an issue as `done` unless at least one new commit was created for that issue's work and has been pushed to the base ref (or merged via the PR fallback).
+- 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.
 
 ## Resolving merge conflicts
 
-When `gh pr merge` fails or `gh pr view <N> --json mergeable,mergeStateStatus` returns `CONFLICTING` / `DIRTY`:
+For a **direct push** rejected as non-fast-forward: `git fetch origin`, `git pull --rebase origin <base-branch>`, resolve each conflict marker, `git rebase --continue`, re-run the full check suite, then push again.
+
+For the **PR fallback** when `gh pr merge` fails or `gh pr view <N> --json mergeable,mergeStateStatus` returns `CONFLICTING` / `DIRTY`:
 
 1. `git fetch origin`
 2. `git checkout <branch-name>`
-3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve each conflict marker, then `git rebase --continue`.
+3. `git rebase origin/<base-branch>` (plain base name; strip any `origin/` prefix). Resolve each conflict marker, then `git rebase --continue`.
 4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
-5. `git push --force-with-lease origin <branch-name>` — never `--force`, use `--force-with-lease` to avoid overwriting concurrent pushes.
-6. Verify the conflict is gone: `gh pr view <N> --json mergeable` should return `MERGEABLE`.
-7. Retry the merge: `gh pr merge <N> --merge`.
+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`.
 
-If the conflict is too complex to resolve safely (e.g., a large structural conflict with another in-flight PR), leave an issue comment describing the exact conflict and escalate to the CEO for prioritization before abandoning the branch.
+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

@@ -79,26 +79,24 @@ Rules:
   should print the helper path, and `test -s "$(git rev-parse --git-common-dir)/paperclip-gh-token-cache"`
   should succeed after a run where `GH_TOKEN` was injected.
 
-## PR Self-Merge Flow
+## Direct-to-Base Flow
 
-Use this flow when the **pr-review module is not active** (no Code Reviewer role, no executionPolicy review stages). You open a PR and merge it yourself — there is no external review gate, but all changes go through a PR so branch history is preserved and branch protection is respected. 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. Pull/fetch latest from that base before editing.
-3. **Create a feature branch** from the base ref: `git checkout -b <branch-name> <base-ref>`. Never commit directly on the base branch. The branch name should reference the issue (e.g., `LEA-5-add-landing-hero`). If you are already on a correctly named feature branch, skip this step.
-4. **Verify you are on the feature branch** before making changes: `git branch --show-current` must print `<branch-name>`, not the base ref. If it prints the base ref name, you forgot step 3 — create the branch now.
-5. Make changes
-6. Run tests/linting locally if available
-7. Commit with conventional commit message
-8. **Verify the current branch one more time**, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-9. Open a pull request against the base ref: write the PR body to a temp file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal (see *Posting PR Bodies & Comments* in `docs/pr-conventions.md`). `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured ref `origin/main` → `--base main`; configured ref `main` → `--base main`). GitHub does not recognise remote-tracking names. Verify the PR base matches the configured base ref before merging.
-10. Merge the PR yourself: `gh pr merge <PR-number> --merge`. Do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing. Never do a direct `git merge` + push to the base branch; always go through a PR.
-11. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local).
-12. If the issue uses an isolated execution workspace (worktree), archive it from `heartbeat-context` after the merge is pushed.
-13. Verify CI passes on the base branch (if configured). If CI fails, fix immediately.
+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.
+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.
+7. Confirm it landed: `git log origin/<base-branch> -1` shows your commit.
+8. If the issue uses an isolated execution workspace (worktree), archive it from `heartbeat-context` after the push.
+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.
 
 ## Resolving the default branch
 
@@ -142,8 +140,8 @@ For a brand-new local repository there is no remote yet, so initialize on `main`
 
 ## Branch Safety
 
-- **Always work on a feature branch, never on the base branch.** Create the branch with `git checkout -b <branch-name> <base-ref>` before committing any changes. If you are resuming work on an existing issue, `git branch --show-current` should already show the feature branch name.
-- **Verify your branch before pushing.** Before running `git push -u origin <branch-name>`, confirm that `git branch --show-current` prints the feature branch name — not the base ref. If it prints the base ref, you are on the wrong branch: stop and create/switch to the feature branch first. Pushing the base ref as a feature branch corrupts upstream tracking and causes incorrect branch divergence reports.
+- **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.
+- **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
 

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/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,7 +5,7 @@ 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

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,7 +5,7 @@ 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?

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` in the project root.
 
 ## 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
 

package/templates/modules/pr-review/README.md

@@ -29,7 +29,7 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 
 ## Handover mechanism
 
-The issue's native `executionPolicy` (`review`/`approval` stages). Each reviewer is the active participant of a stage and records an `approved` / `changes_requested` decision through the normal issue update route; Paperclip stores the reviewer/approver audit trail on the issue (`reviewed_by` / `approved_by` metadata where exposed). The decision may be mirrored as a GitHub PR comment. Do not create separate review subissues. If a reviewer doesn't wake, the CEO's stall-detection (if enabled) will catch it.
+The issue's native `executionPolicy` (`review`/`approval` stages). Each reviewer is the active participant of a stage and records an `approved` / `changes_requested` decision through the normal issue update route; Paperclip stores the reviewer/approver audit trail on the issue (`reviewed_by` / `approved_by` metadata where exposed). The decision may be mirrored as a GitHub PR comment. Do not create separate review subissues, and **do not model the merge as a standalone "Code review and merge PR #N" issue that is `blockedBy` the review issues** — that strands the merge once the reviews close `done` (Paperclip won't reliably re-wake a `blocked` issue whose blockers are all `done`), so the PR is never merged even when green. The merge gate is the **last `executionPolicy` stage on the same implementation issue**, which advances in place. If a reviewer doesn't wake, or a merge issue ends up stranded `blocked`, the CEO's stall-detection (if enabled) will catch it (*Stranded blocked* / *PR-queue hygiene*).
 
 ## Best for