@starlein/paperclip-plugin-company-wizard 0.4.9 → 0.4.11

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to the Company Wizard plugin are documented here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.4.11] - 2026-06-23
+
+### Fixed
+
+**Author-only first executionPolicy stage — a stall the v0.4.10 misrouted-`in_review` detection missed**
+
+v0.4.10 caught `in_review` with `executionPolicy: null` (or no non-author stage at all). It did **not** catch `in_review` whose policy *has* non-author stages later, but whose **first/current stage lists only the assignee (author) as a participant**. Paperclip excludes the executor from every stage, so that first stage has no eligible participant and the issue stalls at stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`) — even though later stages look fine. Observed on LeadConversionOptimizer (LEAA-79/76): engineering tasks were misassigned to QA, QA authored the work, moved to `in_review`, and the first review stage was set to QA itself (self-review) → permanent stall the old scan skipped as "pending review".
+
+Four template files close the gap:
+
+- `stall-detection.md` (CEO skill): step 4 skip-rule tightened — "genuinely pending review" now requires the **current (first unapproved) stage** to have a non-author participant. New `## Author-only first stage` section: detect via `GET /api/issues/{id}` (the list endpoint omits `executionPolicy`), inspect `stages[0].participants` vs `assigneeAgentId`; flag `AUTHOR-ONLY-STAGE`; recover with `PATCH {"executionPolicy":null}` (returns the issue to `in_progress` — a bare `{"status":"in_progress"}` is rejected with `422` while a policy is active), then reassign to the correct owner with a non-author first stage or self-merge.
+- `roles/engineer/HEARTBEAT.md` step 5: after moving to `in_review`, `GET` the issue and confirm `stages[0].participants` is not just you; if it is, null the policy and re-set with a non-author first stage. Generalizes "executor" → "assignee/executor (whoever did the work)".
+- `roles/qa/HEARTBEAT.md`: new guard — QA is a **reviewer, not an author**. Implementation tasks assigned to QA are a misassignment: flag and reassign to the engineer instead of authoring + self-reviewing. Never set an `executionPolicy` stage whose only participant is the assignee; self-recovery via `PATCH {"executionPolicy":null}`.
+- `pr-review/docs/pr-conventions.md` step 3: the "never list the executor as a stage participant" rule generalized from "the engineer who authored the work" to "the issue's assignee/executor (engineer, QA, or any role)", with explicit first-stage-author-only stall warning + null-policy recovery; non-engineer roles must not author implementation work and then self-review it.
+
+## [0.4.10] - 2026-06-22
+
+### Fixed
+
+**Root-cause fix: base-branch-red deadlock, misrouted `in_review`, and missing PR-queue hygiene**
+
+Investigates the LeadConversionOptimizer pile-up (LEAA-89, 18 open PRs) where `origin/main` CI was red, every PR inherited the red baseline and failed CI in 1-3 seconds at setup, and "never merge without green CI" deadlocked the entire queue. Three independent root causes fixed:
+
+**A — Base-branch-red deadlock (7 files)**
+- `docs/git-workflow.md`: new `## Base-branch-red deadlock` section — agents now detect whether a PR's CI failure is *inherited* (same check failing on the base commit itself) or *introduced* by the PR's diff, using `gh api repos/{owner}/{repo}/commits/<base-sha>/check-runs` for comparison. If the base is red, the situation is classified `BASE-BRANCH-RED` and the baseline-emergency protocol triggers instead.
+- `docs/git-workflow.md`: new `## Baseline-emergency protocol` — pause new feature PRs, claim the restore with a comment so concurrent detectors do not open duplicate restore PRs, create a single `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base commit's checks, then rebase and drain the feature-PR queue. If the failing check cannot be reproduced locally (missing secrets / runner-only state), escalate to the board/human rather than stalling.
+- `docs/git-workflow.md`: new `## Narrow exception: merging the baseline-restore PR on a red base` — the baseline-restore PR (and only that PR) may merge with red CI when: diff is scoped to the base failure fix; the exact failing checks pass locally (paste real output); remaining failing checks exactly match the inherited baseline set (not introduced by the diff). Replaces CI-green with local-executed-verification + diff-scope proof; never waives the verification gate; never applies to feature PRs.
+- `git-workflow.md` skill (engineer): step 11 adds a pre-merge CI check (`gh pr checks <N>`) and triggers base-red detection before merging; step 12 adds the Self-Merge baseline-restore exception for the engineer; step 15 routes post-merge base-red to the protocol; new rule in `## Rules` prohibits opening new feature PRs on a red base.
+- `pr-workflow.md` skill (engineer): new `## Base-branch-red deadlock` section — in PR-Gate mode (Code Reviewer present) the engineer comments `BASE-BRANCH-RED` and starts the baseline-restore PR immediately, without waiting for the Code Reviewer's `changes_requested` route-back; in Self-Merge mode the engineer cannot merge a feature PR on a red base but may merge the baseline-restore PR under the narrow exception. The engineer **cannot** record `changes_requested` in PR-Gate mode (author excluded by runtime — 422); this is now explicitly stated in all relevant paths including the merge-conflict closing rule.
+- `code-review.md` (Code Reviewer): hard-gate bullet added after the "cited executed verification" rule — base-red detection + `changes_requested` citing `BASE-BRANCH-RED` for feature PRs; baseline-restore exception for the `fix(ci)` PR with scoped diff + local verification. The existing "Never merge without green CI" rule (§ Rules) is **modified** (not just appended) to carry the same exception caveat.
+- `pr-conventions.md` (shared doc): the `## Merge Rules` "With CI: must be green, cannot be skipped" bullet is **modified** to add the baseline-restore exception caveat — without this the doc injected into the Code Reviewer contradicted the new exception and would re-deadlock.
+
+**B — Misrouted `in_review` with `executionPolicy: null` (3 files)**
+- `engineer/HEARTBEAT.md` step 5: replaced "move to `in_review`" with an explicit guard — verify a review path exists (Code Reviewer present → set `executionPolicy` stages before moving; no Code Reviewer → self-merge path, never `in_review`); recover already-stuck null-policy issues by moving back to `in_progress` and then choosing the right path.
+- `pr-workflow.md` skill: new `## Misrouted in_review (null executionPolicy)` recovery section — move to `in_progress`, set `executionPolicy` stages (Code Reviewer present) or self-merge the PR (no Code Reviewer); leave a comment naming the misroute.
+- `stall-detection.md` step 4: updated to no longer skip `in_review` + `executionPolicy: null` as "pending review" — this is now explicitly identified as a misrouted stall, not a pending approval.
+
+**C — PR-queue hygiene: no monitoring (1 file)**
+- `stall-detection.md`: new `## Misrouted in_review` section — detects `in_review` + null policy during the regular scan (before the summary step), flags as `MISROUTED-REVIEW`, assigns back to the engineer with the recovery action.
+- `stall-detection.md`: new `## PR-queue hygiene` section — every stall-detection routine run (when the `github-repo` module is active) scans the repository's open PR queue via `gh pr list`. Escalates a triage issue when 3+ PRs are UNSTABLE/DIRTY or 8+ PRs are open total. Runs base-branch-red detection first: if the base is red, the triage issue names `BASE-BRANCH-RED` and instructs the baseline-emergency protocol; if the base is green, lists each UNSTABLE/DIRTY PR with its owner and next action (rebase / fix the introduced failure). First detector claims the restore PR by comment to prevent duplicate opens.
+
+---
+
 ## [0.4.9] - 2026-06-22
 
 ### Fixed

package/dist/manifest.js

@@ -2,7 +2,7 @@
 var manifest = {
   id: "starlein.paperclip-plugin-company-wizard",
   apiVersion: 1,
-  version: "0.4.9",
+  version: "0.4.11",
   displayName: "Company Wizard",
   description: "AI-powered wizard to bootstrap agent companies from composable templates",
   author: "Sascha Pietrowski <sp@speednetwork.de>",

package/dist/manifest.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/manifest.ts"],
-  "sourcesContent": ["import type { PaperclipPluginManifestV1 } from '@paperclipai/plugin-sdk';\n\nconst manifest: PaperclipPluginManifestV1 = {\n  id: 'starlein.paperclip-plugin-company-wizard',\n  apiVersion: 1,\n  version: '0.4.9',\n  displayName: 'Company Wizard',\n  description: 'AI-powered wizard to bootstrap agent companies from composable templates',\n  author: 'Sascha Pietrowski <sp@speednetwork.de>',\n  categories: ['workspace', 'ui'],\n  capabilities: [\n    'companies.read',\n    'issues.create',\n    'issues.read',\n    'issues.update',\n    'goals.create',\n    'goals.read',\n    'agents.read',\n    'projects.read',\n    'plugin.state.read',\n    'plugin.state.write',\n    'secrets.read-ref',\n    'events.subscribe',\n    'ui.page.register',\n    'ui.sidebar.register',\n  ],\n  instanceConfigSchema: {\n    type: 'object',\n    properties: {\n      companiesDir: {\n        type: 'string',\n        description:\n          'Directory where assembled company workspaces are written. Auto-detected: ~/instances/default/companies in Docker setups, ~/.paperclip/instances/default/companies otherwise. Rarely needs manual override.',\n      },\n      templatesPath: {\n        type: 'string',\n        description:\n          'Path to the templates directory. Auto-detected: ~/plugin-templates in Docker setups, ~/.paperclip/plugin-templates otherwise. Rarely needs manual override.',\n      },\n      templatesRepoUrl: {\n        type: 'string',\n        default: 'https://github.com/starlein/paperclip-plugin-company-wizard/tree/main/templates',\n        description:\n          'GitHub tree URL for template downloads. The default is correct for most setups \u2014 only change this if using a custom fork.',\n      },\n      anthropicApiKey: {\n        type: 'string',\n        description:\n          'Anthropic API key for the AI wizard (e.g. sk-ant-...). Required to use the AI-powered company setup path.',\n      },\n      paperclipUrl: {\n        type: 'string',\n        description:\n          'Paperclip instance URL. Defaults to http://localhost:3100 or the PAPERCLIP_PUBLIC_URL env var.',\n      },\n      paperclipEmail: {\n        type: 'string',\n        description: 'Board login email (for authenticated instances).',\n      },\n      paperclipPassword: {\n        type: 'string',\n        description: 'Board login password (for authenticated instances).',\n      },\n    },\n  },\n  entrypoints: {\n    worker: './dist/worker.js',\n    ui: './dist/ui',\n  },\n  ui: {\n    slots: [\n      {\n        type: 'page',\n        id: 'company-wizard',\n        displayName: 'Company Wizard',\n        exportName: 'WizardPage',\n        routePath: 'company-creator',\n      },\n      {\n        type: 'sidebar',\n        id: 'company-wizard-link',\n        displayName: 'Create Company',\n        exportName: 'SidebarLink',\n      },\n    ],\n  },\n};\n\nexport default manifest;\n"],
+  "sourcesContent": ["import type { PaperclipPluginManifestV1 } from '@paperclipai/plugin-sdk';\n\nconst manifest: PaperclipPluginManifestV1 = {\n  id: 'starlein.paperclip-plugin-company-wizard',\n  apiVersion: 1,\n  version: '0.4.11',\n  displayName: 'Company Wizard',\n  description: 'AI-powered wizard to bootstrap agent companies from composable templates',\n  author: 'Sascha Pietrowski <sp@speednetwork.de>',\n  categories: ['workspace', 'ui'],\n  capabilities: [\n    'companies.read',\n    'issues.create',\n    'issues.read',\n    'issues.update',\n    'goals.create',\n    'goals.read',\n    'agents.read',\n    'projects.read',\n    'plugin.state.read',\n    'plugin.state.write',\n    'secrets.read-ref',\n    'events.subscribe',\n    'ui.page.register',\n    'ui.sidebar.register',\n  ],\n  instanceConfigSchema: {\n    type: 'object',\n    properties: {\n      companiesDir: {\n        type: 'string',\n        description:\n          'Directory where assembled company workspaces are written. Auto-detected: ~/instances/default/companies in Docker setups, ~/.paperclip/instances/default/companies otherwise. Rarely needs manual override.',\n      },\n      templatesPath: {\n        type: 'string',\n        description:\n          'Path to the templates directory. Auto-detected: ~/plugin-templates in Docker setups, ~/.paperclip/plugin-templates otherwise. Rarely needs manual override.',\n      },\n      templatesRepoUrl: {\n        type: 'string',\n        default: 'https://github.com/starlein/paperclip-plugin-company-wizard/tree/main/templates',\n        description:\n          'GitHub tree URL for template downloads. The default is correct for most setups \u2014 only change this if using a custom fork.',\n      },\n      anthropicApiKey: {\n        type: 'string',\n        description:\n          'Anthropic API key for the AI wizard (e.g. sk-ant-...). Required to use the AI-powered company setup path.',\n      },\n      paperclipUrl: {\n        type: 'string',\n        description:\n          'Paperclip instance URL. Defaults to http://localhost:3100 or the PAPERCLIP_PUBLIC_URL env var.',\n      },\n      paperclipEmail: {\n        type: 'string',\n        description: 'Board login email (for authenticated instances).',\n      },\n      paperclipPassword: {\n        type: 'string',\n        description: 'Board login password (for authenticated instances).',\n      },\n    },\n  },\n  entrypoints: {\n    worker: './dist/worker.js',\n    ui: './dist/ui',\n  },\n  ui: {\n    slots: [\n      {\n        type: 'page',\n        id: 'company-wizard',\n        displayName: 'Company Wizard',\n        exportName: 'WizardPage',\n        routePath: 'company-creator',\n      },\n      {\n        type: 'sidebar',\n        id: 'company-wizard-link',\n        displayName: 'Create Company',\n        exportName: 'SidebarLink',\n      },\n    ],\n  },\n};\n\nexport default manifest;\n"],
   "mappings": ";AAEA,IAAM,WAAsC;AAAA,EAC1C,IAAI;AAAA,EACJ,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,aAAa;AAAA,EACb,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,YAAY,CAAC,aAAa,IAAI;AAAA,EAC9B,cAAc;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,sBAAsB;AAAA,IACpB,MAAM;AAAA,IACN,YAAY;AAAA,MACV,cAAc;AAAA,QACZ,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,eAAe;AAAA,QACb,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,kBAAkB;AAAA,QAChB,MAAM;AAAA,QACN,SAAS;AAAA,QACT,aACE;AAAA,MACJ;AAAA,MACA,iBAAiB;AAAA,QACf,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,cAAc;AAAA,QACZ,MAAM;AAAA,QACN,aACE;AAAA,MACJ;AAAA,MACA,gBAAgB;AAAA,QACd,MAAM;AAAA,QACN,aAAa;AAAA,MACf;AAAA,MACA,mBAAmB;AAAA,QACjB,MAAM;AAAA,QACN,aAAa;AAAA,MACf;AAAA,IACF;AAAA,EACF;AAAA,EACA,aAAa;AAAA,IACX,QAAQ;AAAA,IACR,IAAI;AAAA,EACN;AAAA,EACA,IAAI;AAAA,IACF,OAAO;AAAA,MACL;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,QACZ,WAAW;AAAA,MACb;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,MACd;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAO,mBAAQ;",
   "names": []
 }

package/dist/worker.js

@@ -11003,7 +11003,7 @@ var __dirname = path2.dirname(fileURLToPath2(import.meta.url));
 var DEFAULT_TEMPLATES_REPO_URL = "https://github.com/starlein/paperclip-plugin-company-wizard/tree/main/templates";
 var BUNDLED_TEMPLATES_DIR = path2.resolve(__dirname, "..", "templates");
 var PLUGIN_PACKAGE_NAME = "@starlein/paperclip-plugin-company-wizard";
-var CURRENT_PLUGIN_VERSION = "0.4.9";
+var CURRENT_PLUGIN_VERSION = "0.4.11";
 var NPM_LATEST_URL = "https://registry.npmjs.org/@starlein%2Fpaperclip-plugin-company-wizard/latest";
 function copyDirSync(src, dest) {
   fs2.mkdirSync(dest, { recursive: true });