orchestrix-skills 0.10.0 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Capability-first AI development skill graph (Anthropic-native): plan → build with a warm-context orchestrator, contract-wired skills, and independent verification.",
   "author": "Orchestrix",
   "homepage": "https://orchestrix-mcp.youlidao.ai",

package/README.md

@@ -23,12 +23,36 @@ intent
        │                              (objective)      ↑ accept (batched)
        ├─ (verify failing, cause unknown?) ──→ investigate (root cause → rework)
        ├─ (runnable app?) ──→ smoke-test (drive real flows, evidence captured)
+       ├─ (team mode?) ──→ pull-request after commit (PR on GitHub, MR on GitLab; CI red re-enters rework)
        └─ (accepted + ship it?) ──→ deploy (inline gate, rollback-first)
 ```
 
 Human gates are front-loaded (planning = direction) and at the end (acceptance);
 the build loop runs lights-out, gated only by objective `verify`.
 
+## Team mode
+
+Uncomment the `collaboration:` block in `core-config.yaml` and the same loop
+runs for a team. Planning happens once, on a planning branch, and reaches the
+base branch through a PR. Each story is then one run on its own branch
+(`story/<origin>/<slug>`) in its own workspace — a `git worktree` when several
+sessions share a machine, a clone elsewhere — and ends with `pull-request`
+instead of a local commit. Merging stays a reviewer's act in the forge.
+
+There is no board file. A story's state is derived from git and the forge each
+time it is needed: a remote branch means claimed, an open PR means in review, a
+merged PR means done. Claiming is one push that the remote rejects if the
+branch already exists, so two people cannot take the same story. The PR body
+carries the run's evidence (acceptance criteria → code → test → verify log),
+because `.orchestrate/` never leaves the machine that produced it.
+
+GitHub and GitLab are supported through `adapters/forge/`; the exact CLI
+commands are inlined in the `pull-request` skill and kept identical by test.
+Team mode needs that forge's CLI (`gh` or `glab`) installed and logged in on
+each machine. `install` and `doctor` check for it once the block is active;
+without it a builder run still pushes its branch, then stops and asks a human
+to open the PR — it never pretends the PR exists.
+
 ## Install
 
 ```bash
@@ -51,7 +75,7 @@ Re-running `install` refreshes the skills in place. It also writes a stamp at
 `<skills-dir>/.orchestrix-skills.json`:
 
 ```json
-{ "version": "0.10.0", "ide": "claude", "skills": ["brainstorm", "commit", "…"] }
+{ "version": "0.11.0", "ide": "claude", "skills": ["brainstorm", "commit", "…"] }
 ```
 
 Two things read it. The installer prunes skills a previous version placed that
@@ -93,11 +117,16 @@ The root skill is where the interesting engineering lives. Beyond wiring:
 - **Model tiers are declared, not guessed.** Each skill states
   `requires.model: frontier | capable | cheap`; the adapter maps the tier to a
   model, and the resolved model is recorded on every ledger step.
+- **A team adds no shared state.** In team mode a run lives on a branch in
+  its own workspace, story state is derived from git and the forge, and an
+  epic is accepted on base with `smoke-test` — N green PRs do not prove the
+  composition.
 
 ## Runtime adapters
 
 `skills/` is the runtime-neutral source of truth. `adapters/` describes how a
-runtime maps generic capabilities to its tools. During a Codex install the CLI
+runtime maps generic capabilities to its tools, and how a forge (GitHub,
+GitLab) maps the generic pull-request operations to its CLI. During a Codex install the CLI
 removes Claude-only `allowed-tools`, preserves the contract, and adds Codex
 runtime guidance. If the target has an unmanaged `AGENTS.md`, its content is left
 untouched and the guidance is placed at `.codex/orchestrix/AGENTS.md` for manual

package/adapters/claude/runtime.json

@@ -9,7 +9,8 @@
     "shell.execute": "Bash",
     "web.read": "WebSearch, WebFetch",
     "agent.spawn": "Task",
-    "design.canvas": "the bundled design skill (Claude Design canvas) + Artifact publish"
+    "design.canvas": "the bundled design skill (Claude Design canvas) + Artifact publish",
+    "forge.pr": "Bash + the forge CLI (gh | glab) named by core-config collaboration.forge; op table in the pull-request skill"
   },
   "models": {
     "frontier": "fable",

package/adapters/codex/AGENTS.md

@@ -9,4 +9,5 @@
 - When isolated agents are available, dispatch independent leaf skills concurrently and await them. Otherwise execute leaf skills sequentially in the current context, reading only their declared inputs before each step.
 - Independently run every objective verification command. Never accept an agent's success report as proof.
 - Keep runtime evidence at the fixed `.orchestrate/` path described by the `orchestrate` skill.
+- When `core-config.yaml` has a `collaboration:` block, follow the `orchestrate` skill's Collaboration section: one story per branch per workspace (`git worktree add`, then `cd` into it — Codex has no worktree tool), builder runs end with `pull-request`, and forge operations come from that skill's op table.
 <!-- orchestrix:end -->

package/adapters/codex/runtime.json

@@ -9,7 +9,8 @@
     "shell.execute": "runtime shell tool",
     "web.read": "runtime web tools when enabled",
     "agent.spawn": "optional collaboration tools; otherwise sequential fallback",
-    "design.canvas": "not available; design skills write standalone HTML files"
+    "design.canvas": "not available; design skills write standalone HTML files",
+    "forge.pr": "runtime shell tool + the forge CLI (gh | glab) named by core-config collaboration.forge; op table in the pull-request skill"
   },
   "models": {
     "frontier": "the most capable model the session can select; else the session model, recorded in the ledger",

package/adapters/forge/github.json

@@ -0,0 +1,20 @@
+{
+  "name": "github",
+  "term": "pull request",
+  "cli": "gh",
+  "ops": {
+    "auth": "gh auth status",
+    "pr_for_branch": "gh pr list --head {branch} --state all --json number,url,state,isDraft,headRefOid,mergedAt",
+    "pr_create_draft": "gh pr create --draft --base {base} --head {branch} --title {title} --body-file {body_file}",
+    "pr_view": "gh pr view {pr} --json number,url,state,isDraft,headRefOid,baseRefName",
+    "pr_update_body": "gh pr edit {pr} --body-file {body_file}",
+    "pr_ready": "gh pr ready {pr}",
+    "ci_status": "gh pr checks {pr}",
+    "ci_watch": "gh pr checks {pr} --watch --fail-fast"
+  },
+  "notes": {
+    "pr_for_branch": "An empty JSON array means no PR exists for the branch.",
+    "ci_status": "Exit code 0 = all checks passed, 8 = pending, 1 = at least one failed (gh 2.63).",
+    "protection": "Enforce on the base branch via rulesets: require a pull request, require status checks, require the branch to be up to date before merging."
+  }
+}

package/adapters/forge/gitlab.json

@@ -0,0 +1,20 @@
+{
+  "name": "gitlab",
+  "term": "merge request",
+  "cli": "glab",
+  "ops": {
+    "auth": "glab auth status",
+    "pr_for_branch": "glab mr list --source-branch {branch} --all --output json",
+    "pr_create_draft": "glab mr create --draft --yes --source-branch {branch} --target-branch {base} --title {title} --description \"$(cat {body_file})\"",
+    "pr_view": "glab mr view {pr} --output json",
+    "pr_update_body": "glab mr update {pr} --description \"$(cat {body_file})\"",
+    "pr_ready": "glab mr update {pr} --ready",
+    "ci_status": "glab ci status --branch {branch} --compact",
+    "ci_watch": "glab ci status --branch {branch} --live"
+  },
+  "notes": {
+    "pr_for_branch": "An empty JSON array means no MR exists for the branch. The JSON carries state (opened | merged | closed), sha, and web_url.",
+    "ci_status": "Read the pipeline status word from the output (success | failed | running | pending); the exit code alone does not encode it in glab 1.50.",
+    "protection": "Enforce on the target branch: protected branch (no direct push), merge requests required, pipelines must succeed, and the merge method setting that requires the source to be up to date (fast-forward or semi-linear)."
+  }
+}

package/bin/install.js

@@ -3,7 +3,7 @@
 // Copies skills into the runtime's skills dir + scaffolds knowledge/.
 // No MCP, no license, no network calls. The hosted layer is a separate opt-in.
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -45,6 +45,7 @@ What it does:
   1. Copies the skills into your runtime's skills dir (default: .claude/skills/)
   2. Scaffolds knowledge/ + core-config.yaml (never overwrites an existing brain)
   3. Stamps <skills-dir>/.orchestrix-skills.json so upgrades and pruning are exact
+  4. Adds .orchestrate/ to .gitignore (once; ledger and verify logs are per-run state)
 
 Hosted orchestration, knowledge hosting, and team features:
   see https://orchestrix-mcp.youlidao.ai`);
@@ -115,6 +116,18 @@ function installSkills(dir, runtimeName, runtime) {
   return { count: names.length, pruned };
 }
 
+// The ledger and verify logs are per-run, per-workspace state. Committed, they
+// conflict on every PR in team mode, so the ignore line is written once and
+// left alone if the project already has it.
+function ignoreRuntimeDir(dir) {
+  const path = join(dir, ".gitignore");
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (current.split("\n").some((line) => /^\.orchestrate\/?\s*$/.test(line))) return false;
+  const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+  writeFileSync(path, `${current}${separator}.orchestrate/\n`);
+  return true;
+}
+
 function installRuntimeGuidance(dir, runtimeName) {
   if (runtimeName !== "codex") return;
   const source = join(PKG, "adapters", "codex", "AGENTS.md");
@@ -160,6 +173,37 @@ function nonemptyFile(path) {
   return isFile(path) && readFileSync(path, "utf8").trim().length > 0;
 }
 
+// Team mode is opt-in: an uncommented `collaboration:` block in core-config.
+// Returns the forge name it declares, or null when the block is absent.
+function activeForge(configContent) {
+  const block = configContent.match(/^collaboration:\s*(?:#.*)?\n((?:[ \t]+.*\n?)*)/m);
+  if (!block) return null;
+  return block[1].match(/^[ \t]+forge:\s*([A-Za-z0-9_-]+)/m)?.[1] ?? "";
+}
+
+function forgeCli(forge) {
+  const path = join(PKG, "adapters", "forge", `${forge}.json`);
+  return isFile(path) ? JSON.parse(readFileSync(path, "utf8")).cli : null;
+}
+
+function onPath(bin) {
+  const exts = process.platform === "win32" ? ["", ".exe", ".cmd"] : [""];
+  return (process.env.PATH ?? "").split(delimiter).some((dir) => dir && exts.some((ext) => isFile(join(dir, bin + ext))));
+}
+
+// The pull-request skill drives the forge through its CLI (gh | glab). Without
+// it, builder runs stop at "push the branch, open the PR by hand" — better to
+// hear that from install/doctor than mid-run.
+function forgeCheck(configContent) {
+  const forge = activeForge(configContent);
+  if (forge === null) return null;
+  const cli = forgeCli(forge);
+  if (!cli) return { ok: false, detail: `collaboration.forge "${forge}" has no adapter (known: github, gitlab)` };
+  return onPath(cli)
+    ? { ok: true, detail: `${cli} on PATH (collaboration.forge: ${forge})` }
+    : { ok: false, detail: `${cli} not on PATH — team mode needs it installed and logged in (collaboration.forge: ${forge})` };
+}
+
 function validSkill(path, runtimeName, expectedName) {
   if (!nonemptyFile(path)) return false;
   const content = readFileSync(path, "utf8");
@@ -203,6 +247,14 @@ function install() {
     console.log("✓ core-config.yaml scaffolded");
   }
 
+  // 4. Runtime dir — ledger + verify logs never belong in history.
+  if (ignoreRuntimeDir(dir)) console.log("✓ .orchestrate/ added to .gitignore");
+  else console.log("• .gitignore already ignores .orchestrate/");
+
+  // 5. Team mode, if the project turned it on: say now whether the forge CLI is there.
+  const forge = forgeCheck(nonemptyFile(cfgTarget) ? readFileSync(cfgTarget, "utf8") : "");
+  if (forge) console.log(`${forge.ok ? "✓" : "✗"} forge CLI: ${forge.detail}`);
+
   if (ide === "cursor" || ide === "windsurf") {
     console.log(`\nNote: ${ide} does not auto-load Anthropic skills yet — copied as reference rules.`);
   }
@@ -234,6 +286,8 @@ function doctor() {
     ["core config valid", /(^|\n)knowledge:\s*(#.*)?\n/.test(configContent) && /(^|\n)work:\s*(#.*)?\n/.test(configContent), configPath],
     ["knowledge brain", isDirectory(join(dir, "knowledge")), join(dir, "knowledge")],
   ];
+  const forge = forgeCheck(configContent);
+  if (forge) checks.push(["forge CLI (team mode)", forge.ok, forge.detail]);
   if (ide === "codex") {
     const reference = join(dir, ".codex", "orchestrix", "AGENTS.md");
     const rootInstructions = join(dir, "AGENTS.md");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Capability-first AI development skill graph — Anthropic-native skills that run in any agent runtime.",
   "type": "module",
   "bin": {

package/project-scaffold/core-config.yaml

@@ -18,6 +18,20 @@ work: # work products — skills WRITE these (outputs:), humans review at gates
 # here for transparency only.
 runtime: .orchestrate # ledger + verify logs (ephemeral, gitignored)
 
+# Team mode (opt-in). Uncomment to make orchestrate run each story on its own
+# branch in its own workspace and end builder runs with a PR/MR instead of a
+# local commit. Absent = solo behaviour, unchanged. See the orchestrate skill,
+# "Collaboration".
+#
+# collaboration:
+#   forge: github # github | gitlab
+#   base: main
+#   branch: story/{origin}/{slug}
+#   plan_branch: plan/{origin}
+#   workspace: worktree # worktree (same machine) | in-place (a clone elsewhere)
+#   pr:
+#     reviewers: []
+
 # Org-level cascade (shared taste/standards across many products) is intentionally
 # NOT enabled yet (YAGNI). When needed: add an `extends:` base that project paths
 # override. The logical namespaces above do not change when cascade is added.

package/skills/README.md

@@ -61,7 +61,7 @@ intent
        ├─ brainstorm ──(needs facts?)─→ research
        ├─ (has UI?) ──→ design-directions (human picks a rendered direction) → design-system (once) → design-ui
        ├─ (arch decision?) ──→ design-architecture
-       └─ draft-story → implement → run-tests → review-code → commit
+       └─ draft-story → implement → run-tests → review-code → commit ──(team mode)─→ pull-request
                                       ↑ verify         ↑ design-review (UI only)
                                       (objective)      ↑ accept (batched)
 ```
@@ -86,6 +86,7 @@ Human gates are front-loaded (planning = direction) and at the very end
 | `review-code`         | build                    | deferred           |
 | `design-review`       | build (UI only)          | deferred           |
 | `commit`              | build                    | deferred           |
+| `pull-request`        | build (team mode)        | inline (first open) |
 
 ## Attribution
 

package/skills/draft-story/SKILL.md

@@ -12,7 +12,7 @@ metadata:
     reads: [taste/coding-standards, registry/api, registry/db, "front-end-spec?"]
     outputs: [stories/<slug>.md]
     authority: "Write one flat story file in the stories namespace (physical path from core-config.yaml; default docs/stories/). No folders. No source code. No production. No spend."
-    verify: "Every requirement maps to at least one acceptance criterion; constraints are copied verbatim; no placeholders (no TBD/TODO/'handle edge cases')."
+    verify: "Every requirement maps to at least one acceptance criterion; constraints are copied verbatim; no placeholders (no TBD/TODO/'handle edge cases'); depends_on names only stories of the same origin whose Interfaces produce what this one consumes; touches equals the File Map."
     accept:
       when: "Always — this output sets the direction the whole build rests on."
       timing: inline
@@ -36,6 +36,8 @@ these sections (with frontmatter) and nothing more.
 ```markdown
 ---
 origin: <stable short handle of the requirement this story came from>
+depends_on: [] # slugs of same-origin stories whose Produces this story Consumes
+touches: [] # every path in File Map (Create + Modify), as written there
 ---
 
 # <Story title>
@@ -85,6 +87,12 @@ What this story deliberately does NOT do.
 - **Flat, no hierarchy.** One file per story in the stories dir. Grouping is
   the `origin` field (a query the AI runs), never a folder. Order comes from
   Interfaces (dependencies), never from a number.
+- **Dependencies and footprint are explicit.** `depends_on` is derived from
+  Interfaces: a story that Consumes a signature another same-origin story
+  Produces depends on it — nothing else qualifies. `touches` repeats the
+  File Map so a team run can detect two stories that would edit the same
+  file without opening either. Both are empty lists when there is nothing
+  to list, never omitted.
 - **No placeholders.** "Add validation", "handle errors", "TBD" are failures.
   State the actual condition.
 - **Acceptance criteria are observable.** "Works well" is not an AC. "Returns
@@ -102,6 +110,8 @@ What this story deliberately does NOT do.
 2. Are all hard constraints copied verbatim, not paraphrased?
 3. Any placeholder text? Replace with the real condition.
 4. Do the names in Interfaces match across sections?
+5. Does `depends_on` name exactly the same-origin stories whose Produces
+   this story Consumes, and does `touches` equal the File Map?
 
 ## Done
 

package/skills/orchestrate/SKILL.md

@@ -4,9 +4,9 @@ description: Use when a goal must be delivered end-to-end by composing skills, w
 license: MIT
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task, Skill, Artifact]
 metadata:
-  version: 7
+  version: 8
   requires:
-    capabilities: [filesystem.read, filesystem.write, shell.execute, "agent.spawn?", "design.canvas?"]
+    capabilities: [filesystem.read, filesystem.write, shell.execute, "agent.spawn?", "design.canvas?", "forge.pr?"]
     model: frontier
   contract:
     inputs: [intent, "constraints?"]
@@ -146,6 +146,121 @@ CANNOT reach — wire these by rule, not by match:
      gate, hand the human's pick to `design-system` as `chosen_direction`,
      then `design-ui`.
    A direction the human has not seen rendered is not a direction.
+3. **An epic is accepted on base, not story by story.** In collaboration
+   mode (below), when every story of an origin is `done`, offer the
+   integration run: on base, `smoke-test` with flows from the spec's
+   acceptance criteria, final acceptance against the original intent, then
+   `deploy` if asked. N green PRs prove N stories; they do not prove the
+   composition. No output→input match reaches this step.
+
+## Collaboration (team mode, opt-in)
+
+Enabled only when `core-config.yaml` has a `collaboration:` block. Without it,
+nothing in this section applies and the run behaves exactly as described
+above. With it, the same loop runs; what changes is where a run lives (a
+branch in its own workspace), how a run ends (a PR/MR, not a local commit),
+and one preflight.
+
+```yaml
+collaboration:
+  forge: github # github | gitlab — op table in the pull-request skill (and adapters/forge/<forge>.json)
+  base: main
+  branch: story/{origin}/{slug} # one story, one branch, one run
+  plan_branch: plan/{origin} # planning runs (specs, stories, knowledge)
+  workspace: worktree # worktree (same machine) | in-place (a clone elsewhere)
+  pr:
+    reviewers: []
+```
+
+**Principle: no new shared state.** Which stories are open, claimed, in
+review, or done is derived from git and the forge every time it is needed,
+never written to a board file that would need its own merge strategy.
+
+| Story state | Derived from |
+| --- | --- |
+| `open` | no remote branch for the story (`git ls-remote --heads origin <branch>` is empty) and no merged PR/MR |
+| `claimed` | remote branch exists, no PR/MR (`pr_for_branch` is empty) |
+| `in_review` | an open PR/MR for the branch |
+| `done` | the forge reports a merged PR/MR for the branch (squash merges leave no ancestry, so `git branch --merged` cannot be the source) |
+| `blocked` | any story in `depends_on` is not `done` |
+| `stale` | `claimed`, and the branch's last commit is older than 7 days |
+| `unknown` | the forge could not be queried — never treated as `open` |
+
+### Preflight (deterministic, after binding intent)
+
+1. `git fetch origin`, then bring the base checkout up to date with
+   `git merge --ff-only origin/<base>`. If that fails, stop: the checkout
+   has diverged from base and the brain it would read is stale.
+2. Run the forge `auth` op (`gh auth status` | `glab auth status`; the full
+   op table is in the `pull-request` skill). Not authenticated → stop;
+   logging in is the human's act on this machine.
+3. `git worktree prune`, then remove worktrees whose story is `done`.
+4. `.orchestrate/` must be ignored (`git check-ignore -q .orchestrate`). If
+   not, add the line to `.gitignore` before anything else — a committed
+   ledger conflicts on every PR.
+
+### Planning runs end in a planning PR
+
+A run that wires any skill writing to the specs, stories, or knowledge
+namespaces (`brainstorm`, `research`, `design-*`, `draft-story`,
+`map-codebase`) runs on `plan_branch` and ends with `commit` →
+`pull-request`. The backlog exists for the team only once that PR is merged
+to base: a story that is not on base cannot be claimed. Do not build in the
+same run that planned; the builder run starts from base.
+
+### Builder runs: pick → workspace → claim → build → pull-request
+
+1. **Pick.** Compute the board for the origin. The intent names a story, or
+   you propose the first `open`, not `blocked` story in dependency order.
+   Two `open` stories whose `touches` globs overlap are serialized: name the
+   conflict and pick only one. The human confirms the pick at the front gate
+   you already hold. Picking is a human act; there is no assign skill.
+2. **Workspace.** Create the branch without checking it out, then give it a
+   working tree. Order matters: `git worktree add` refuses a branch that is
+   already checked out anywhere, so the branch must not be switched to in
+   the base checkout first.
+
+   ```
+   git branch <branch> origin/<base>
+   git worktree add ../<repo>--<slug> <branch>     # workspace: worktree
+   git switch <branch>                             # workspace: in-place
+   ```
+
+   From here on, the workspace directory is the working directory for every
+   dispatch and every namespace resolution. One story per workspace is
+   enforced by git itself, not by this skill.
+3. **Claim — atomic on the remote.** Inside the workspace, make one empty
+   commit (`git commit --allow-empty -m "chore(story): claim <slug>"`) so
+   the claim has a SHA and an author, then push it so that the push fails
+   if the branch already exists on the remote:
+
+   ```
+   git push -u --force-with-lease=refs/heads/<branch>: origin <branch>
+   ```
+
+   The empty expectation after the colon means "the ref must not exist". A
+   rejected push (`stale info`) means someone else claimed it: remove the
+   workspace (`git worktree remove`, `git branch -D`), recompute the board,
+   pick again. Only after the push succeeds, write `run_start` followed by
+   `workspace` in the workspace's own `.orchestrate/ledger.jsonl`.
+4. **Build — unchanged.** The loop above, gated by `verify`. Namespace paths
+   resolve inside the workspace.
+5. **Tail.** `commit` → `pull-request`. Its `ci_status` is a verify result:
+   `red` re-enters the rework loop with the failing job's log as
+   `qa_feedback` (investigate first when the cause is not understood; the
+   3-attempt cap applies); `pending` at the ceiling is a gate, not a pass.
+6. **Deliver** when the PR/MR is open and `ci_status` is `green`. Write
+   `run_end` with the `pr` URL. Merging is the reviewer's act in the forge;
+   this run does not wait for it.
+
+### Parallel hazards on one machine
+
+Two workspaces sharing one local database, port, or container project
+corrupt each other's `smoke-test` and `design-review`. Unless `registry/app`
+declares the app parallel-safe (per-workspace database name, port from
+`$PORT` or `0`, distinct compose project), run those two skills under a lock
+file in the git common dir (`git rev-parse --git-common-dir`) so only one
+workspace drives an app at a time.
 
 ## Accept gate
 
@@ -233,11 +348,12 @@ Events and when to write them:
 
 | Event | When | Shape |
 | ----- | ---- | ----- |
-| `run_start` | right after binding intent | `{"e":"run_start","run":"r-<yyyymmdd>-<slug>","intent":"...","ts":"..."}` |
+| `run_start` | right after binding intent (in collaboration mode: as the first line of the workspace's ledger) | `{"e":"run_start","run":"r-<yyyymmdd>-<slug>","intent":"...","actor":"<git user.email>","ts":"..."}` |
+| `workspace` | collaboration mode only, right after `run_start` | `{"e":"workspace","run":"...","branch":"story/<origin>/<slug>","path":"<absolute workspace path>","base":"<origin/base sha at claim>","ts":"..."}` |
 | `plan` | after wiring the graph, and EVERY time the graph changes | `{"e":"plan","run":"...","steps":[{"n":1,"skill":"research","title":"..."}, …]}` — full current plan; latest `plan` line wins; steps may be added, never removed |
 | `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed\|skipped","attempt":1,"model":"<resolved model, or session>","evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt`; a step a replan made obsolete gets `skipped` with the reason in `evidence` (plan lines are never removed, so this is how an obsolete step closes) |
 | `gate` | when stopping at a human gate | `{"e":"gate","run":"...","kind":"inline_accept","question":"...","shows":"<artboard URL or path, visual gates only>","ts":"..."}` |
-| `run_end` | at delivery or abandonment | `{"e":"run_end","run":"...","result":"delivered\|paused\|abandoned","ts":"..."}` |
+| `run_end` | at delivery or abandonment | `{"e":"run_end","run":"...","result":"delivered\|paused\|abandoned","pr":"<PR/MR URL, collaboration mode only>","ts":"..."}` |
 
 A step recorded `done` is done — do not re-dispatch it. `evidence` on a `done`
 step is required and should be the step's verify log path
@@ -261,6 +377,11 @@ session, or a wake-up — do NOT continue from what you remember. Replay:
    Fail → re-dispatch as the next attempt.
 4. Continue the loop from the first open step. If the run was stopped at a
    `gate`, re-ask that gate's question — never assume it was answered.
+5. In collaboration mode, the `workspace` line says which branch and
+   directory the run lives in. Resume from inside that workspace; the base
+   checkout's ledger never holds a builder run. A `workspace` line whose
+   path no longer exists means the worktree was removed: the run is
+   `abandoned`, write `run_end` and say so.
 
 ## Context discipline (stay lean)
 
@@ -312,3 +433,10 @@ implementer missed; mechanical skills are `cheap`.
 - Running a `frontier` step on a cheaper model without recording it in the
   ledger
 - Marking the run complete without every step's `verify` evidence
+- Collaboration mode: building on base, or in the same run that planned
+- Collaboration mode: claiming with a plain push (two claims both succeed),
+  or switching to the story branch before `git worktree add` (which then
+  refuses it)
+- Collaboration mode: treating `ci_status: pending` or `unknown` as green, or
+  delivering a builder run with no `pr` on `run_end`
+- Collaboration mode: two workspaces driving one local app with no lock

package/skills/pull-request/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: pull-request
+description: Use when a verified story branch (or a planning branch) must be published for team review as a pull request (GitHub) or merge request (GitLab), and its CI result pulled back into the run. Never merges. Not for solo runs with no collaboration block.
+license: MIT
+allowed-tools: [Read, Bash]
+metadata:
+  requires:
+    capabilities: [filesystem.read, shell.execute, forge.pr]
+    model: cheap
+  contract:
+    inputs: [branch, story, verification_report, "ac_traceability?", "review_report?", "smoke_report?", "design_review_report?", "pr?"]
+    reads: [core-config]
+    outputs: [pr_url, ci_status]
+    authority: "Rebase the current branch onto base, push it, and open or update ONE pull/merge request against base. Never merge, never push to base, never force-push over commits you did not make (--force-with-lease only), never change forge settings."
+    verify: "The forge returns a PR/MR for the branch whose head SHA equals local HEAD; ci_status is green, red, or pending — never unknown; the body lists every acceptance criterion with its evidence."
+    accept:
+      when: "The first open of a PR/MR — the human approves title, body, and reviewers once. Later updates to the same PR/MR need no gate."
+      timing: inline
+---
+
+# Pull Request
+
+Publish a verified branch for team review. A pull request (GitHub) and a merge
+request (GitLab) are the same object: a request to merge one branch into
+another with review and CI attached. This skill speaks to whichever forge
+`core-config.yaml` names and treats the two identically.
+
+**Core principle:** The PR body is the run's evidence, made portable. Verify
+logs live in `.orchestrate/`, which never leaves the machine. A reviewer on
+another machine sees only what this skill puts in the body — so the body is
+assembled from the run's files, never from memory.
+
+## Preconditions — verify each now
+
+1. `core-config.yaml` has a `collaboration:` block. Absent → this skill does
+   not apply; stop and say so.
+2. The forge CLI is authenticated: run the `auth` op. Not authenticated →
+   stop; authentication is the human's act on this machine.
+3. The current branch matches `collaboration.branch` (story) or
+   `collaboration.plan_branch` (planning), and is not `collaboration.base`.
+4. `verification_report` is a fresh green run — not a remembered one.
+
+## Forge operations
+
+`collaboration.forge` selects the column. Substitute `{base}`, `{branch}`,
+`{pr}`, `{title}`, `{body_file}`. The same table ships as
+`adapters/forge/<forge>.json` for tools that read it as data; the two are
+kept identical by test.
+
+| Op | GitHub (`gh`) | GitLab (`glab`) |
+| --- | --- | --- |
+| `auth` | `gh auth status` | `glab auth status` |
+| `pr_for_branch` | `gh pr list --head {branch} --state all --json number,url,state,isDraft,headRefOid,mergedAt` | `glab mr list --source-branch {branch} --all --output json` |
+| `pr_create_draft` | `gh pr create --draft --base {base} --head {branch} --title {title} --body-file {body_file}` | `glab mr create --draft --yes --source-branch {branch} --target-branch {base} --title {title} --description "$(cat {body_file})"` |
+| `pr_view` | `gh pr view {pr} --json number,url,state,isDraft,headRefOid,baseRefName` | `glab mr view {pr} --output json` |
+| `pr_update_body` | `gh pr edit {pr} --body-file {body_file}` | `glab mr update {pr} --description "$(cat {body_file})"` |
+| `pr_ready` | `gh pr ready {pr}` | `glab mr update {pr} --ready` |
+| `ci_status` | `gh pr checks {pr}` | `glab ci status --branch {branch} --compact` |
+| `ci_watch` | `gh pr checks {pr} --watch --fail-fast` | `glab ci status --branch {branch} --live` |
+
+Reading results: an empty JSON array from `pr_for_branch` means no PR/MR
+exists. `gh pr checks` exits 0 when every check passed, 8 while checks are
+pending, 1 when one failed. `glab ci status` encodes the pipeline state in
+its output words (`success`, `failed`, `running`, `pending`), not in its
+exit code — read the text.
+
+An unknown forge name, or a CLI missing from PATH → push the branch, print
+the URL a human would use to open the PR/MR, and return `ci_status:
+unknown`. That fails this skill's verify on purpose: the run stops at a gate
+instead of pretending.
+
+## Process
+
+1. **Sync with base.** `git fetch origin`, then rebase onto
+   `origin/<base>`. A conflict outside the knowledge namespace → stop and
+   hand the conflict to the human; do not resolve source conflicts. A
+   conflict inside the knowledge namespace is resolved by **keyed union**:
+   keep every entry from both sides, matching on the entry's key (`id` for
+   taste rows, `path` for registry endpoints, the ADR id for decisions),
+   prefer the base side when the same key differs, and list what you merged
+   in the body under Brain changes.
+2. **Re-verify on the rebased tree.** Run the project's test command fresh
+   and capture it to `.orchestrate/verify/pull-request-tests.log`. Red →
+   return `ci_status: red` with the failing output as the reason; do not
+   push a red branch.
+3. **Push** with `git push --force-with-lease origin <branch>`.
+   `--force-with-lease` protects commits you did not make; plain `--force`
+   is forbidden.
+4. **Find or create.** `pr_for_branch`. None → assemble the body (below),
+   write it to `.orchestrate/pr-body.md`, then stop for the inline gate:
+   show title, body, and reviewers; create as draft only on sign-off.
+   Exists → `pr_update_body` with the re-assembled body; no gate.
+5. **Wait for CI, bounded.** `ci_watch` with a ceiling of about 15 minutes.
+   Green → `pr_ready`, return `ci_status: green`. Red → return
+   `ci_status: red` with the failing job name and its log tail as the
+   reason. Still pending at the ceiling → return `ci_status: pending`.
+6. **Verify.** `pr_view`: head SHA must equal `git rev-parse HEAD`. Mismatch
+   means the push did not land or someone else pushed; report it as a
+   failure, never as done.
+
+## The body
+
+Every section is filled from a file the run produced. A missing input leaves
+its section reading `not run this run`, never blank and never invented.
+
+```markdown
+# <story title>
+
+`<branch>` → `<base>` · story: `<stories path>` · origin: `<origin>`
+
+## Acceptance criteria → evidence
+| AC | Code | Test | Verify log |
+| --- | --- | --- | --- |
+| AC1 <text> | src/x.ts:42-58 | tests/x.test.ts 'rejects empty email' | step-4-attempt-1.log · exit 0 |
+
+## Verification
+- run-tests: <passed>/<failed> · `<command>`
+- smoke-test: <passed> passed · <failed> failed · <untested> untested (<reasons>)
+- review-code: <verdict>; findings routed back: <n>
+- design-review: <verdict> · coverage <full|partial> (<untested checks>)
+
+## Brain changes — review these; a bad lesson contaminates every later run
+- taste/<file>: <+n rows | none>
+- registry/<file>: <+n entries | none>
+- architecture/decisions: <ids added | none>
+
+## Run
+actor <email> · run <id> · attempts per step: <n:k, …> · models: <skill=model, …>
+```
+
+Title: the story title, prefixed with the conventional-commit type of the
+dominant change (`feat:`, `fix:`, …). Reviewers: `collaboration.pr.reviewers`.
+
+## Output
+
+```yaml
+pr_url: https://…
+ci_status: green # green | red | pending | unknown
+reason: "" # required when red or unknown: failing job + log tail, or what is missing
+head: <sha>
+```
+
+## Red flags — stop
+
+- Pushing a branch whose fresh test run is red
+- `git push --force` without `--force-with-lease`
+- Resolving a source-code conflict yourself during the rebase
+- A body section written from memory instead of from the run's files
+- Creating the PR/MR before the inline gate on first open
+- Reporting `green` from the CI tool's summary without reading which checks ran
+- Merging, or marking ready while CI is red or pending
+
+## Done
+
+PR/MR exists, head SHA matches local HEAD, `ci_status` is known. Return
+`pr_url` and `ci_status`; the orchestrator records `pr_url` on `run_end` and
+routes a `red` result into the rework loop.