@hegemonart/get-design-done 1.39.5 → 1.40.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.39.5"
+    "version": "1.40.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.39.5",
+      "version": "1.40.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.39.5",
+  "version": "1.40.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.40.0] - 2026-06-01
+
+### Phase 40 — Team Collaboration Mode
+
+The largest architectural phase: GDD's single-operator baseline (Phase 20 lockfile + atomic STATE.md) now extends to **multiple developers**. Multi-writer STATE.md merges per-section, decisions are attributed + reviewed through an async queue with hard locks, a conflict-resolver reconciles parallel branches, decisions export to a read-only shared journal, and per-section permissions + sectional handoff gate who writes what. Everything is **git-native + advisory** — no server, no live multiplayer, no SSO. **No new runtime dependency, no new egress.**
+
+### Breaking changes
+
+**None.** Every Phase 40 surface is additive and **off by default**: `gdd_cycle_mode` defaults to `full` (current behavior), `permissions` absent = everyone is `owner`, `collab.multi_writer_enabled` defaults to `false`, `collab.sync_backend` defaults to `git`, and the decision attribution suffix is optional + backward-compatible. A single-operator project upgrading to v1.40.0 behaves exactly as it did on v1.39.5.
+
+### Added
+
+- **`reference/multi-author-model.md`** — the team-collaboration contract (merge model, attribution, review queue + locks, lock policy, sectional handoff, permissions, journal export + PR threading, opt-in sync). Registered.
+- **`scripts/lib/collab/`** — 7 pure, dep-free cores: `attribution` (decision `[author= co-author=]` suffix), `section-merge` (git-merge-driver per-section semantic merge — union by D-id, conflict only on same-id divergence), `lock-policy` (team-mode advisory-lock backoff), `review-queue` (proposed→reviewing→approved→locked + audited unlock), `cycle-mode` (sectional handoff stage gate), `permissions` (per-section `can()`), `sync-backend` (git/s3/git-lfs selector).
+- **`agents/conflict-resolver.md`** — three-way STATE.md merge, per-section + human-confirmed; never auto-picks or drops a decision.
+- **`agents/decision-journal-exporter.md`** — `<decisions>` → `pseudonymize` → read-only Notion/Confluence on cycle close (write-only; degrades to local markdown).
+- **`skills/review-decisions/SKILL.md`** (`/gdd:review-decisions`) + **`skills/unlock-decision/SKILL.md`** (`/gdd:unlock-decision <id> --approver`, the only audited escape from a hard lock).
+
+### Changed
+
+- **`reference/schemas/config.schema.json`** — + `gdd_cycle_mode` (designer|dev|full) + `permissions` + `collab` (multi_writer_enabled / lock_timeout_ms / sync_backend); `generated.d.ts` regenerated.
+- **`reference/STATE-TEMPLATE.md`** — document the optional decision attribution suffix.
+- **`agents/design-reflector.md`** — a "Per-author patterns" note (reads attribution).
+- **`agents/pr-commenter.md`** — thread PR comments on `D-XX` decisions (team-mode).
+
+### Notes
+
+- **No new runtime dependency, no new egress** — 7 pure cores + reference/agent/skill prose + an additive config-schema; the live S3/git-LFS sync client is explicitly out of scope (the selector ships, the backend is pluggable).
+- 6-manifest lockstep at **v1.40.0** + `OFF_CADENCE_VERSIONS.add('1.40.0')` (a minor bump) + the 33 live-pinned `manifests-version.txt` baselines forward-propagated 1.39.5 → 1.40.0.
+- Inventory relock: registry-diff 158 → 159 (+`multi-author-model`), skill-list 80 → 82 (+`review-decisions`, +`unlock-decision`), agent-list +`conflict-resolver` +`decision-journal-exporter` + both frontmatter-snapshots, skill-length-distribution relocked, tarball golden 709 → 721 (+12). Root `SKILL.md` command table += both skills.
+
+---
+
 ## [1.39.5] - 2026-06-01
 
 ### Phase 39.5 — GDD Self-Migration Tooling

package/README.md

@@ -190,6 +190,10 @@ GDD already tracks cost per task and per runtime — now it **forecasts** it, **
 
 GDD migrates *your* design systems (above) — now it migrates **itself**. When GDD ships a breaking path change (like the Phase 31.5 `scripts/lib/**` → `sdk/**` reorg), a machine-readable registry in [`reference/DEPRECATIONS.md`](reference/DEPRECATIONS.md) records `Since · Removed in · Old · New · hint`. After an upgrade, [`/gdd:update`](skills/update/SKILL.md) flags anything that crossed into deprecated/removed, and [`/gdd:migrate`](skills/migrate/SKILL.md) rewrites your project's stale references — **previewing a diff first, never silent** — via the pure [`deprecation-registry`](scripts/lib/deprecation-registry.cjs). Two CI gates keep the system honest: a completeness check (every entry has a shim or a confirmed removal) and `lint-changelog` (every future minor must declare a `### Breaking changes` section). **No new runtime dependency, no new egress.**
 
+### Team collaboration mode (v1.40.0)
+
+GDD's single-operator baseline now extends to **teams** — git-native + advisory, no server. Two developers working a cycle on parallel branches merge their `.design/STATE.md` **per section** ([`section-merge`](scripts/lib/collab/section-merge.cjs) unions decisions by `D-id`; a real conflict is only a same-id divergence, which [`conflict-resolver`](agents/conflict-resolver.md) reconciles with human confirmation — never auto-picking or dropping a decision). Decisions carry optional `[author= co-author=]` attribution, move through an async review queue (`proposed → reviewing → approved → locked`) with **hard locks** (the only escape is an audited [`/gdd:unlock-decision`](skills/unlock-decision/SKILL.md)), and [`/gdd:review-decisions`](skills/review-decisions/SKILL.md) surfaces what's pending. [`decision-journal-exporter`](agents/decision-journal-exporter.md) publishes a **pseudonymized, read-only** Notion/Confluence journal for stakeholders who don't run GDD. `gdd_cycle_mode` (designer/dev/full) partitions a cycle by role, a `permissions` model gates per-section writes, and `collab.multi_writer_enabled` switches the advisory lock to a team-mode backoff. The full contract: [`reference/multi-author-model.md`](reference/multi-author-model.md). **Everything is off by default** — a single-operator project is unaffected. **No new runtime dependency.**
+
 ### Previous releases
 
 - **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).

package/SKILL.md

@@ -105,6 +105,8 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `budget [--cycles N] [--scenario best\|typical\|worst]` | `get-design-done:gdd-budget` | Phase 39.2 — forecast design-cycle spend (best/typical/worst from telemetry variance) via `cost-forecaster`; "at the current rate you'll hit your $X project cap in Y cycles." Read-only — never spends, edits `budget.json`, or halts (the budget-enforcer hook halts) |
 | `roi [--since <date>] [--window-days 14]` | `get-design-done:gdd-roi` | Phase 39.2 — ROI table joining per-cycle cost with commits that shipped (survived ≥14d) vs reverted → cost-per-shipped-commit + stick rate. Read-only markdown report |
 | `migrate [--yes] [--dry-run]` | `get-design-done:gdd-migrate` | Phase 39.5 — migrate a project off GDD's own deprecated paths after an upgrade; reads `reference/DEPRECATIONS.md` via `deprecation-registry.cjs`, previews a diff, applies on confirm. Preview-first; never edits silently |
+| `review-decisions [<id>] [--pending]` | `get-design-done:gdd-review-decisions` | Phase 40 — surface the async decision-review queue (`proposed → reviewing → approved → locked`); `--pending` shows decisions still awaiting action. Read-only |
+| `unlock-decision <id> --approver <who> [--reason <text>] [--dry-run]` | `get-design-done:gdd-unlock-decision` | Phase 40 — reopen a LOCKED decision (the only escape hatch); requires an approver + writes an audit entry; previews before writing |
 
 ## Handoff Routing
 

package/agents/conflict-resolver.md

@@ -0,0 +1,80 @@
+---
+name: conflict-resolver
+description: Resolves design-artifact merge conflicts when two developers worked a cycle on parallel branches. Reads the conflicted STATE.md from both sides (ours/theirs) plus the merge base, runs the pure scripts/lib/collab/section-merge.cjs per-section semantic merge (union the <decisions> by D-id; a real conflict is only a same-id divergence), and proposes a resolution PER SECTION for explicit human confirmation. Never auto-commits a conflicted section — decisions are durable. Spawned during a team-mode merge.
+tools: Read, Bash, Grep, Glob
+color: green
+default-tier: sonnet
+tier-rationale: "Three-way semantic merge of a structured STATE.md via a pure helper + a human-confirmed per-section proposal; bounded reconciliation, not open design judgment — sonnet-tier."
+size_budget: M
+size_budget_rationale: "Honest tier sized to the ~95-line body. DELEGATES the merge math to scripts/lib/collab/section-merge.cjs + the attribution parse to scripts/lib/collab/attribution.cjs, and the model to reference/multi-author-model.md."
+parallel-safe: false
+typical-duration-seconds: 45
+reads-only: false
+required_reading:
+  - "reference/multi-author-model.md"
+writes:
+  - ".design/STATE.md (only the sections the human confirms)"
+---
+
+# conflict-resolver
+
+Two developers ran a GDD cycle on parallel branches; their `.design/STATE.md` now conflicts. You
+reconcile it **per section, with human confirmation** — you never silently pick a winner, and you
+never drop a decision. **Read `reference/multi-author-model.md` first** (the merge model).
+
+## Inputs
+
+A git merge conflict in `.design/STATE.md`. Recover the three versions:
+
+```bash
+git show :1:.design/STATE.md > /tmp/state.base   # merge base (common ancestor)
+git show :2:.design/STATE.md > /tmp/state.ours   # ours (current branch)
+git show :3:.design/STATE.md > /tmp/state.theirs # theirs (incoming)
+```
+
+(If a stage isn't available — e.g. an add/add conflict with no base — treat the base as empty.)
+
+## Procedure
+
+1. **Parse each side's `<decisions>` block** with `scripts/lib/collab/attribution.cjs`
+   (`parseDecisionsBlock`), preserving the `[author= co-author=]` attribution.
+2. **Three-way merge** via the pure helper — never merge by hand:
+
+   ```bash
+   node -e '
+     const fs = require("fs");
+     const at = require("./scripts/lib/collab/attribution.cjs");
+     const sm = require("./scripts/lib/collab/section-merge.cjs");
+     const block = (f) => { const m = fs.readFileSync(f,"utf8").match(/<decisions>([\s\S]*?)<\/decisions>/); return m ? at.parseDecisionsBlock(m[1]) : []; };
+     const r = sm.mergeDecisions(block("/tmp/state.base"), block("/tmp/state.ours"), block("/tmp/state.theirs"));
+     console.log(JSON.stringify(r, null, 2));
+   '
+   ```
+
+3. **Report the proposal per section.** For `<decisions>`:
+   - the clean union (auto-mergeable D-NN, both new adds kept) — show it,
+   - each **conflict** (same D-id, divergent text/status) — show ours vs theirs side by side and ask
+     the human which to keep (or to author a merged text). Never decide unilaterally.
+   Repeat for any other conflicted section (status, `<prototyping>`, `<rollout_status>`) using
+   `mergeStatusScalar` for single-value sections.
+4. **Apply only confirmed sections.** Write the merged `<decisions>` (re-formatted via
+   `attribution.formatDecisionLine`, attribution preserved) back to `.design/STATE.md`, leaving any
+   unconfirmed conflict marked for the human. Then `git add .design/STATE.md` is the human's call.
+5. **Never drop a decision.** A `D-NN` removed on one side but unchanged on the other is kept — surface
+   it, don't delete it.
+
+## Record
+
+Print a `## Conflict resolution` summary: sections merged, D-NN auto-unioned, conflicts surfaced +
+how each was resolved, and any section left for the human. Append one JSONL line to
+`.design/intel/insights.jsonl` recording the merge outcome. Close with:
+
+```
+## CONFLICT RESOLUTION COMPLETE
+```
+
+## Boundaries
+
+- Per-section, human-confirmed; no unilateral winner, no silent deletion.
+- Reconciles design artifacts (STATE.md); it does not run `git commit` or resolve source-code conflicts.
+- No network.

package/agents/decision-journal-exporter.md

@@ -0,0 +1,68 @@
+---
+name: decision-journal-exporter
+description: Exports a cycle's design decisions to a read-only shared journal (Notion/Confluence) so PMs, designers, and stakeholders who don't run GDD locally can see what was decided and why. Reads STATE.md <decisions>, pipes every line through scripts/lib/pseudonymize.cjs (git identity + stable hash) so author names are masked before leaving the repo, and writes a read-only page via the connections/notion.md interface on cycle close. Write-only (non-GDD users read; they never write back). Degrades to a local markdown file when no Notion connection is available.
+tools: Read, Write, Bash, Grep, Glob, ToolSearch
+color: green
+default-tier: sonnet
+tier-rationale: "Reads a STATE block, redacts via a pure helper, and renders a page through an existing connection; bounded transform + publish, no design judgment — sonnet-tier."
+size_budget: M
+size_budget_rationale: "Honest tier sized to the ~90-line body. DELEGATES redaction to scripts/lib/pseudonymize.cjs, the Notion write to connections/notion.md, and the contract to reference/multi-author-model.md."
+parallel-safe: false
+typical-duration-seconds: 45
+reads-only: false
+required_reading:
+  - "reference/multi-author-model.md"
+  - "connections/notion.md"
+writes:
+  - "a read-only Notion/Confluence page (external) OR .design/exports/decisions-<cycle>.md (fallback)"
+---
+
+# decision-journal-exporter
+
+You publish a cycle's decisions to a **read-only shared journal** so non-GDD stakeholders can follow
+the "what + why" without the repo. You run on cycle close. **Read `reference/multi-author-model.md`
+and `connections/notion.md` first.** Every author name is **pseudonymized before it leaves the repo**.
+
+## Procedure
+
+1. **Read the decisions.** Parse `.design/STATE.md` `<decisions>` (with
+   `scripts/lib/collab/attribution.cjs` `parseDecisionsBlock`), capturing id, text, status, and
+   attribution.
+2. **Pseudonymize.** Pipe the rendered decision text through `scripts/lib/pseudonymize.cjs` BEFORE any
+   outbound call — R1 (git identity) + R8 (stable pseudonym) mask `author=`/`co-author=` into a stable
+   hash. Never publish a raw git identity.
+
+   ```bash
+   node -e '
+     const fs = require("fs");
+     const { pseudonymize } = require("./scripts/lib/pseudonymize.cjs");
+     const raw = fs.readFileSync(0, "utf8");
+     process.stdout.write(pseudonymize(raw, {}));
+   ' < /tmp/decisions.md > /tmp/decisions.redacted.md
+   ```
+
+3. **Render** a read-only page: cycle id, the decision table (id · text · status · pseudonymous
+   author), and a "generated by GDD on cycle close — read-only" header. Regenerate each cycle (replace,
+   don't append duplicates).
+4. **Publish.** If a Notion connection is `available` (probe via `connections/notion.md`), write the
+   page through its write interface (redaction already applied; the connection's own redact pass is a
+   second belt). Otherwise **degrade**: write `.design/exports/decisions-<cycle>.md` locally and tell
+   the user to share it manually. Confluence follows the same shape if its connection is present.
+5. **Write-only.** You publish; you never read stakeholder edits back into STATE.md (bidirectional sync
+   is out of scope this phase).
+
+## Record
+
+Print a `## Decision journal export` summary: cycle, decisions exported, destination (Notion page /
+local fallback), and confirmation that redaction ran. Append one JSONL line to
+`.design/intel/insights.jsonl`. Close with:
+
+```
+## DECISION JOURNAL EXPORT COMPLETE
+```
+
+## Boundaries
+
+- **Pseudonymize before publish** — no raw git identity ever leaves the repo.
+- Write-only, read-only-for-readers; no bidirectional sync; degrade to local markdown on no connection.
+- Only the `<decisions>` block — not the full STATE.md, not telemetry.

package/agents/design-reflector.md

@@ -92,6 +92,8 @@ After listing standard surprises, apply the **Four Principles Checks** from `ref
 
 Scan STATE.md `<decisions>` block for D-XX codes. Cross-reference `.design/learnings/` files from prior cycles if present. Flag decisions that: (a) appeared in multiple sessions of the same cycle, or (b) appear under the same keyword in learnings from ≥2 prior cycles. These are candidates for `reference/` additions.
 
+**Per-author patterns (Phase 40, team mode).** When decisions carry the `[author= co-author=]` attribution suffix (see `reference/multi-author-model.md`), parse it with `scripts/lib/collab/attribution.cjs` (`parseDecisionsBlock` + `groupByAuthor`) and add a brief **Per-author patterns** sub-note: who locks decisions early, whose decisions get reverted or unlocked most, and any author whose decisions cluster around a recurring keyword. Skip silently when no decision is attributed (single-author projects).
+
 ### 3. Agent Performance
 
 Read `.design/agent-metrics.json`. For each agent:

package/agents/pr-commenter.md

@@ -67,6 +67,7 @@ const safeBody = redact(commentBody);
 1. **Inline review comments** — for each verify/audit finding that maps to a changed file+line, post an inline comment via `gh api repos/{owner}/{repo}/pulls/{n}/comments` (path + line + redacted body: the finding, the rule/pillar, and a one-line suggested fix). Findings with no changed-line locus go into a single summary review comment, not scattered.
 2. **Screenshot pairs (degrade, D-04)** — when `.design/STATE.md` `<connections>` shows `preview: available` or `chromatic: available` AND a before-after pair exists for a changed surface, attach the image refs in the comment/PR timeline. When absent → text-only; never a precondition.
 3. **`gdd/design-review` check-run (D-03)** — `gh api repos/{owner}/{repo}/check-runs` with `name: "gdd/design-review"`, a `conclusion` (`success` if verify passed + no blocker pillars, `failure` if verify failed or a11y-gate failed, else `neutral`), and an `output.summary` carrying the audit pillar scores + verify pass/fail + a11y result. This is the gate a teammate's branch-protection rule can require — see the reference for the required-check setup (`scripts/apply-branch-protection.sh`); you **register** the check, you never edit branch protection.
+4. **Decision threading (Phase 40, team mode)** — for each `D-XX` decision referenced in the PR's `DESIGN.md` / `DESIGN-VERIFICATION.md`, thread a PR comment keyed to that decision (one comment per `D-XX`, body = the decision text + its `proposed/reviewing/approved/locked` review state from `reference/multi-author-model.md`), so decision discussion persists as part of the PR history. Redacted like every other body; degrade-to-noop when `gh` is absent. This makes a decision's rationale reviewable inline by teammates who don't run GDD.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.39.5",
+  "version": "1.40.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/STATE-TEMPLATE.md

@@ -47,6 +47,9 @@ skipped_stages: ""
 <decisions>
 <!-- Filled by discover stage. Format: -->
 <!-- D-01: [decision text] (locked | tentative) -->
+<!-- Phase 40 (team mode): an optional attribution suffix records provenance for multi-author merges: -->
+<!-- D-01: [decision text] (locked | tentative) [author=<git-user> co-author=<gdd-instance-id>] -->
+<!-- The suffix is optional + backward-compatible; see reference/multi-author-model.md. -->
 </decisions>
 
 <must_haves>

package/reference/config-schema.md

@@ -376,3 +376,22 @@ If `.design/cache-manifest.json` is missing when `hooks/budget-enforcer.js` read
 - `.design/budget.json` — provides `cache_ttl_seconds` default.
 - `.design/telemetry/costs.jsonl` (Plan 10.1-05) — records `cache_hit: true` rows with zero tokens and zero cost when the short-circuit fires.
 - D-05, D-08, D-09 in `.planning/phases/10.1-optimization-layer-cost-governance/10.1-CONTEXT.md` — decision lineage.
+
+## Team collaboration (Phase 40)
+
+Three optional top-level `.design/config.json` keys enable team mode. All are absent/off by default —
+single-operator projects are unaffected. Full contract: `reference/multi-author-model.md`.
+
+- **`gdd_cycle_mode`** (`designer` | `dev` | `full`, default `full`) — sectional handoff. `designer`
+  permits Brief + Explore writes; `dev` permits Plan + Design + Verify; `full` = all stages.
+  `scripts/lib/collab/cycle-mode.cjs` `stagePermitted(mode, stage)` gates STATE writes by stage.
+- **`permissions`** — per-section write permissions (`scripts/lib/collab/permissions.cjs`). Permissive
+  by default (absent = everyone `owner`). Shape: `{ default, actors: {<actor>: <role>}, rules:
+  [{section, action, roles}] }`, roles in `owner|contributor|reviewer|viewer`. A rule restricts a
+  `(section, action)` to its listed roles; an unruled pair is allowed. `viewer` never mutates. A CI
+  gate calls `can(config, actor, section, action)` to enforce on PRs.
+- **`collab`** — `{ multi_writer_enabled (bool), lock_timeout_ms (int), sync_backend
+  (git|s3|git-lfs) }`. `multi_writer_enabled: true` switches the gdd-state advisory lock to the
+  team-mode policy (`scripts/lib/collab/lock-policy.cjs` — 30 s wait + 100 ms backoff);
+  `sync_backend` selects the cross-machine `.design/` backend (`scripts/lib/collab/sync-backend.cjs`,
+  default `git`; `s3`/`git-lfs` are opt-in declarations — a live client is not bundled this phase).

package/reference/multi-author-model.md

@@ -0,0 +1,112 @@
+# Multi-Author Model — Team Collaboration Contract
+
+Phase 40 contract. GDD's single-process baseline (Phase 20 lockfile + atomic STATE.md RMW) is safe for
+one operator. This file is the contract for **multiple developers** working a design in parallel: how
+STATE.md merges, how decisions are attributed and reviewed, how writes coordinate across processes,
+and who is allowed to write what. Everything here is **git-native + advisory** — no server, no live
+multiplayer, no SSO.
+
+## 1. Multi-writer STATE.md — git-merge-driver with per-section semantic merge
+
+GDD does **not** ship a CRDT or OT engine. The chosen model (lowest risk, highest familiarity) is a
+**git merge driver with per-section semantic conflict detection**. The append-mostly `<decisions>`
+block is the common case: two branches each adding a new `D-NN` must merge cleanly. The pure core
+`scripts/lib/collab/section-merge.cjs` implements the rule:
+
+- **Union by id.** A `D-NN` present on only one side (vs the merge base) is kept.
+- **Equal duplicates collapse.** The same `D-NN` with identical text/status/attribution on both sides
+  is kept once.
+- **Divergence is the only conflict.** The same `D-NN` with different text or status on the two sides
+  is a genuine conflict — surfaced to `agents/conflict-resolver.md`, never auto-resolved.
+- **Decisions are durable.** A `D-NN` removed on one side but unchanged on the other is **kept** — a
+  decision is never silently deleted by a merge; removal goes through the unlock flow (§3).
+
+A single-value section (e.g. `status`) merges with `mergeStatusScalar`: if only one side changed, take
+that side; if both changed differently, it's a conflict.
+
+## 2. Attribution
+
+A decision line carries an **optional** attribution suffix:
+
+```
+D-07: Use OKLCH design tokens (locked) [author=alice co-author=gdd-3f9a]
+```
+
+- `author` — the git user who made the decision.
+- `co-author` — the GDD instance id (which machine/agent run produced it).
+
+The suffix is backward-compatible: a plain `D-01: text (locked)` parses with `author`/`co-author` =
+null. `scripts/lib/collab/attribution.cjs` parses + formats the line and groups decisions by author.
+`agents/design-reflector.md` reads attribution to surface **per-author patterns** (who tends to lock
+early, whose decisions get reverted). This is the SC#5 "attribution field" — encoded in the line, not
+a schema-breaking change to the `Decision` type.
+
+## 3. Async review queue + decision locks
+
+Each decision under review lives at `.design/reviews/<decision-id>/`, moving through a state machine
+(`scripts/lib/collab/review-queue.cjs`):
+
+```
+proposed → reviewing → approved → locked
+```
+
+- **`locked` is terminal and hard.** A locked decision cannot be amended. `canAmend(state)` is true
+  only for `proposed`/`reviewing`.
+- **Unlock is explicit + audited.** `/gdd:unlock-decision <id> --approver <who>` moves `locked →
+  reviewing` and appends an audit entry (`{ from:'locked', to:'reviewing', approver, reason }`). There
+  is no silent unlock.
+- **`/gdd:review-decisions`** surfaces every queue entry by state (and `--pending` for the ones
+  awaiting action).
+
+## 4. Multi-writer lock policy
+
+`scripts/lib/collab/lock-policy.cjs` derives the `acquire()` options from config. In single-process
+mode the Phase 20 defaults apply (`maxWaitMs: 5000`). When `collab.multi_writer_enabled: true`, a
+teammate's write may be queued, so the policy waits up to **30 s** with a **100 ms** backoff poll and a
+2-minute stale threshold. `collab.lock_timeout_ms` overrides the wait. The gdd-state MCP write path
+passes these options to the existing advisory lock — coordinated multi-process writes, no new lock
+mechanism.
+
+## 5. Sectional handoff — `gdd_cycle_mode`
+
+`.design/config.json#gdd_cycle_mode` partitions a cycle by role (`scripts/lib/collab/cycle-mode.cjs`):
+
+| Mode | Permitted stages |
+|---|---|
+| `designer` | Brief, Explore |
+| `dev` | Plan, Design, Verify |
+| `full` | all (the default / current behavior) |
+
+`stagePermitted(mode, stage)` gates STATE writes by stage — a designer-mode cycle cannot write Plan/Design
+state, and vice versa. This lets a designer hand a brief to a dev without either overwriting the other's
+sections.
+
+## 6. Permissions
+
+`.design/config.json#permissions` declares who can write which sections
+(`scripts/lib/collab/permissions.cjs` `can(config, actor, section, action)`). The default policy is
+permissive (`owner` can do everything); an override can restrict, e.g. "only `@lead-designer` can
+`lock` decisions". A CI gate asserts the permission model is enforced on PRs.
+
+## 7. Decision-journal export + PR threading
+
+- **`agents/decision-journal-exporter.md`** writes a **read-only** Notion/Confluence page from the
+  `<decisions>` block on cycle close (write-only this phase; non-GDD stakeholders read it). Every
+  decision is piped through `scripts/lib/pseudonymize.cjs` first (R1 git-identity + R8 stable hash), so
+  author names are masked before they leave the repo. Degrades to a local markdown file when no Notion
+  connection is available.
+- **`agents/pr-commenter.md`** threads PR review comments on the `D-XX` decisions referenced in
+  DESIGN.md / DESIGN-VERIFICATION.md, so decision discussion persists as part of the PR history.
+
+## 8. Cross-machine sync (opt-in)
+
+`scripts/lib/collab/sync-backend.cjs` `resolveBackend(config)` selects the `.design/` sync backend:
+`git` (the **default** — existing behavior), or an opt-in `s3` / `git-lfs` for orgs whose git
+push/pull cadence is too slow. Sync is **opt-in and off by default**; a live S3/LFS client is out of
+scope for this phase — the selector + contract ship, the backend is pluggable.
+
+## Boundaries
+
+No real-time multiplayer, no SSO/SAML, no GDD-side user accounts (users are git authors), no
+bidirectional Notion, no merge-queue automation beyond the conflict-resolver. Everything is advisory
+and git-native: a team that already uses git + PRs gets collaboration without new infrastructure.

package/reference/registry.json

@@ -1028,6 +1028,13 @@
       "type": "heuristic",
       "phase": 39.2,
       "description": "Phase 39.2 cost-governance contract: the per-cycle forecast model (best/typical/worst from mean ± k·σ, cyclesToCap) via scripts/lib/budget/cost-forecast.cjs; the project_cap hard-halt (disabled by default, graceful PreToolUse:Agent block, warn 50/80 + halt 100) via scripts/lib/budget/project-cap.cjs + hooks/budget-enforcer.ts; the ROI dashboard (shipped = surviving >=14d, cost-per-shipped-commit) via scripts/lib/budget/roi.cjs; and the budget_forecast/project_cap_warning/project_cap_halt events. Agent agents/cost-forecaster.md; skills /gdd:budget + /gdd:roi. Read/report-only — the hook only blocks, never spends."
+    },
+    {
+      "name": "multi-author-model",
+      "path": "reference/multi-author-model.md",
+      "type": "meta-rules",
+      "phase": 40,
+      "description": "Phase 40 team-collaboration contract: multi-writer STATE.md via a git-merge-driver with per-section semantic merge (scripts/lib/collab/section-merge.cjs — union by D-id, conflict only on same-id divergence); decision attribution line-suffix [author= co-author=] (attribution.cjs); the async review queue proposed->reviewing->approved->locked with hard locks + audited /gdd:unlock-decision (review-queue.cjs); the multi-writer advisory-lock policy (lock-policy.cjs, 30s/100ms backoff in team mode); sectional handoff gdd_cycle_mode designer|dev|full (cycle-mode.cjs); the permission model (permissions.cjs) + CI gate; decision-journal-exporter (pseudonymized, write-only Notion) + pr-commenter D-XX threading; opt-in cross-machine sync (sync-backend.cjs, defaults to git). Agents conflict-resolver + decision-journal-exporter; skills /gdd:review-decisions + /gdd:unlock-decision."
     }
   ]
 }

package/reference/schemas/config.schema.json

@@ -40,6 +40,43 @@
     "update_dismissed": {
       "type": "string",
       "description": "Latest plugin tag (e.g. \"v1.0.7.3\") whose update nudge the user has dismissed. Set by /gdd:check-update --dismiss and by hooks/update-check.sh on the --dismiss code path. When a newer tag ships, the nudge reappears."
+    },
+    "gdd_cycle_mode": {
+      "type": "string",
+      "enum": ["designer", "dev", "full"],
+      "description": "Phase 40 sectional handoff. designer = Brief + Explore only; dev = Plan + Design + Verify; full = all stages (default). scripts/lib/collab/cycle-mode.cjs gates STATE writes by stage so a designer and a dev can hand a cycle back and forth without overwriting each other's sections."
+    },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Phase 40 per-section write permissions (scripts/lib/collab/permissions.cjs). Permissive by default (absent = everyone is owner). A team narrows it, e.g. only @lead-designer may lock decisions. A CI gate enforces on PRs.",
+      "properties": {
+        "default": { "type": "string", "enum": ["owner", "contributor", "reviewer", "viewer"], "description": "Role for any actor not listed in `actors`. Default owner." },
+        "actors": { "type": "object", "additionalProperties": { "type": "string", "enum": ["owner", "contributor", "reviewer", "viewer"] }, "description": "Per-actor role map (git user/handle -> role)." },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "section": { "type": "string", "description": "STATE.md section (decisions/prototyping/rollout_status/status/progress/blockers) or '*'." },
+              "action": { "type": "string", "enum": ["write", "lock", "unlock", "approve", "*"] },
+              "roles": { "type": "array", "items": { "type": "string", "enum": ["owner", "contributor", "reviewer", "viewer"] } }
+            }
+          },
+          "description": "Restrictive rules: a (section, action) is limited to the listed roles. No matching rule = allowed (permissive)."
+        }
+      }
+    },
+    "collab": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Phase 40 team-collaboration settings.",
+      "properties": {
+        "multi_writer_enabled": { "type": "boolean", "description": "When true, the gdd-state advisory lock uses the team-mode policy (longer wait + backoff) via scripts/lib/collab/lock-policy.cjs. Default false (single-process)." },
+        "lock_timeout_ms": { "type": "integer", "minimum": 0, "description": "Override the team-mode lock acquire maxWaitMs (default 30000)." },
+        "sync_backend": { "type": "string", "enum": ["git", "s3", "git-lfs"], "description": "Cross-machine .design/ sync backend (scripts/lib/collab/sync-backend.cjs). Default git (existing push/pull). s3 / git-lfs are opt-in declarations; a live client is not bundled this phase." }
+      }
     }
   }
 }

package/reference/schemas/generated.d.ts

@@ -101,6 +101,56 @@ export interface DesignConfigJson {
    * Latest plugin tag (e.g. "v1.0.7.3") whose update nudge the user has dismissed. Set by /gdd:check-update --dismiss and by hooks/update-check.sh on the --dismiss code path. When a newer tag ships, the nudge reappears.
    */
   update_dismissed?: string;
+  /**
+   * Phase 40 sectional handoff. designer = Brief + Explore only; dev = Plan + Design + Verify; full = all stages (default). scripts/lib/collab/cycle-mode.cjs gates STATE writes by stage so a designer and a dev can hand a cycle back and forth without overwriting each other's sections.
+   */
+  gdd_cycle_mode?: 'designer' | 'dev' | 'full';
+  /**
+   * Phase 40 per-section write permissions (scripts/lib/collab/permissions.cjs). Permissive by default (absent = everyone is owner). A team narrows it, e.g. only @lead-designer may lock decisions. A CI gate enforces on PRs.
+   */
+  permissions?: {
+    /**
+     * Role for any actor not listed in `actors`. Default owner.
+     */
+    default?: 'owner' | 'contributor' | 'reviewer' | 'viewer';
+    /**
+     * Per-actor role map (git user/handle -> role).
+     */
+    actors?: {
+      [k: string]: 'owner' | 'contributor' | 'reviewer' | 'viewer';
+    };
+    /**
+     * Restrictive rules: a (section, action) is limited to the listed roles. No matching rule = allowed (permissive).
+     */
+    rules?: {
+      /**
+       * STATE.md section (decisions/prototyping/rollout_status/status/progress/blockers) or '*'.
+       */
+      section?: string;
+      action?: 'write' | 'lock' | 'unlock' | 'approve' | '*';
+      roles?: ('owner' | 'contributor' | 'reviewer' | 'viewer')[];
+      [k: string]: unknown;
+    }[];
+    [k: string]: unknown;
+  };
+  /**
+   * Phase 40 team-collaboration settings.
+   */
+  collab?: {
+    /**
+     * When true, the gdd-state advisory lock uses the team-mode policy (longer wait + backoff) via scripts/lib/collab/lock-policy.cjs. Default false (single-process).
+     */
+    multi_writer_enabled?: boolean;
+    /**
+     * Override the team-mode lock acquire maxWaitMs (default 30000).
+     */
+    lock_timeout_ms?: number;
+    /**
+     * Cross-machine .design/ sync backend (scripts/lib/collab/sync-backend.cjs). Default git (existing push/pull). s3 / git-lfs are opt-in declarations; a live client is not bundled this phase.
+     */
+    sync_backend?: 'git' | 's3' | 'git-lfs';
+    [k: string]: unknown;
+  };
   [k: string]: unknown;
 }
 

package/scripts/lib/collab/attribution.cjs

@@ -0,0 +1,83 @@
+'use strict';
+// Phase 40 — attribution.cjs — PURE, dep-free parser/formatter for multi-author decision attribution.
+//
+// A STATE.md decision line carries an OPTIONAL attribution suffix so multiple developers' decisions
+// survive a merge with provenance intact (SC#5). The canonical line form is:
+//
+//   D-NN: <text> (<status>) [author=<git-user> co-author=<gdd-instance-id>]
+//
+// The suffix is optional and backward-compatible — a plain `D-01: text (locked)` parses with
+// author/coAuthor = null. This module does ONLY string parse/format + grouping; no fs, no clock.
+//
+// No `require` — pure. Deterministic.
+
+const STATUSES = Object.freeze(['locked', 'tentative']);
+
+/**
+ * Parse a single decision line into its parts. Returns null when the line is not a decision line.
+ * @returns {{id, text, status, author, coAuthor} | null}
+ */
+function parseDecisionLine(line) {
+  const s = String(line).trim().replace(/^[-*]\s+/, ''); // tolerate list-bullet prefixes
+  const m = s.match(/^(D-\d+)\s*:\s*(.*)$/);
+  if (!m) return null;
+  const id = m[1];
+  let rest = m[2].trim();
+  let author = null;
+  let coAuthor = null;
+  // Pull a trailing [author=... co-author=...] suffix (order-independent, both optional).
+  const attr = rest.match(/\[([^\]]*)\]\s*$/);
+  if (attr) {
+    const inner = attr[1];
+    const am = inner.match(/\bauthor=([^\s\]]+)/);
+    const cm = inner.match(/\bco-author=([^\s\]]+)/);
+    if (am) author = am[1];
+    if (cm) coAuthor = cm[1];
+    if (am || cm) rest = rest.slice(0, attr.index).trim();
+  }
+  // Pull a trailing (status).
+  let status = null;
+  const st = rest.match(/\(([a-z]+)\)\s*$/i);
+  if (st && STATUSES.includes(st[1].toLowerCase())) {
+    status = st[1].toLowerCase();
+    rest = rest.slice(0, st.index).trim();
+  }
+  return { id, text: rest, status, author, coAuthor };
+}
+
+/** Format a decision object back into the canonical line (omitting absent optional parts). */
+function formatDecisionLine(d) {
+  if (!d || !d.id) throw new Error('attribution: formatDecisionLine needs {id}');
+  let line = `${d.id}: ${String(d.text || '').trim()}`;
+  if (d.status) line += ` (${d.status})`;
+  const bits = [];
+  if (d.author) bits.push(`author=${d.author}`);
+  if (d.coAuthor) bits.push(`co-author=${d.coAuthor}`);
+  if (bits.length) line += ` [${bits.join(' ')}]`;
+  return line;
+}
+
+/** Group an array of decision objects by author → { '<author>': [decision,...], '<unattributed>': [...] }. */
+function groupByAuthor(decisions) {
+  if (!Array.isArray(decisions)) throw new Error('attribution: groupByAuthor needs an array');
+  const out = {};
+  for (const d of decisions) {
+    const key = d && d.author ? d.author : '<unattributed>';
+    (out[key] = out[key] || []).push(d);
+  }
+  return out;
+}
+
+/** Parse a whole `<decisions>` block body into decision objects (skips blanks/comments). */
+function parseDecisionsBlock(body) {
+  const out = [];
+  for (const line of String(body).replace(/\r\n/g, '\n').split('\n')) {
+    const t = line.trim();
+    if (!t || t.startsWith('<!--')) continue;
+    const d = parseDecisionLine(t);
+    if (d) out.push(d);
+  }
+  return out;
+}
+
+module.exports = { STATUSES, parseDecisionLine, formatDecisionLine, groupByAuthor, parseDecisionsBlock };

package/scripts/lib/collab/cycle-mode.cjs

@@ -0,0 +1,41 @@
+'use strict';
+// Phase 40 — cycle-mode.cjs — PURE, dep-free sectional-handoff gate (SC#8).
+//
+// `.design/config.json#gdd_cycle_mode` partitions a cycle by role so a designer can hand a brief to a
+// dev (and vice versa) without either overwriting the other's stages:
+//   designer → Brief, Explore
+//   dev      → Plan, Design, Verify
+//   full     → all stages (the default / current single-operator behavior)
+// `stagePermitted(mode, stage)` gates a STATE write by the stage that produced it.
+//
+// No `require` — pure. Deterministic.
+
+const MODES = Object.freeze(['designer', 'dev', 'full']);
+const ALL_STAGES = Object.freeze(['brief', 'explore', 'plan', 'design', 'verify']);
+
+const STAGES_BY_MODE = Object.freeze({
+  designer: Object.freeze(['brief', 'explore']),
+  dev: Object.freeze(['plan', 'design', 'verify']),
+  full: ALL_STAGES,
+});
+
+/** Normalize a mode value; unknown/missing → 'full' (the safe, backward-compatible default). */
+function normalizeMode(mode) {
+  const m = String(mode || 'full').toLowerCase().trim();
+  return MODES.includes(m) ? m : 'full';
+}
+
+/** Resolve the cycle mode from a parsed `.design/config.json` (defaults to 'full'). */
+function resolveMode(config) {
+  return normalizeMode(config && config.gdd_cycle_mode);
+}
+
+/** True when `stage` is writable under `mode`. Unknown stage → false. */
+function stagePermitted(mode, stage) {
+  const m = normalizeMode(mode);
+  const s = String(stage || '').toLowerCase().trim();
+  if (!ALL_STAGES.includes(s)) return false;
+  return STAGES_BY_MODE[m].includes(s);
+}
+
+module.exports = { MODES, ALL_STAGES, STAGES_BY_MODE, normalizeMode, resolveMode, stagePermitted };

package/scripts/lib/collab/lock-policy.cjs

@@ -0,0 +1,37 @@
+'use strict';
+// Phase 40 — lock-policy.cjs — PURE, dep-free advisory-lock policy for gdd-state multi-writer mode (SC#6).
+//
+// Phase 20's sdk/state/lockfile.ts already implements PID+timestamp advisory locks with retry
+// (staleMs / maxWaitMs / pollMs). "Multi-writer mode" is a POLICY layered on top: when a project
+// enables team mode (`.design/config.json#collab.multi_writer_enabled`), the state write path should
+// wait LONGER and poll on a backoff before giving up, because a teammate's write may be in flight.
+// This module derives the acquire-options object from config; the MCP write path passes it to acquire().
+//
+// No `require` — pure. Deterministic.
+
+// sdk/state/lockfile.ts defaults (single-process baseline).
+const SINGLE = Object.freeze({ staleMs: 60000, maxWaitMs: 5000, pollMs: 50 });
+// Team mode: a stuck teammate write is rare but a normal queued one is not — wait up to 30s,
+// poll slower (100ms) to reduce contention, and treat a lock older than 2min as stale.
+const TEAM = Object.freeze({ staleMs: 120000, maxWaitMs: 30000, pollMs: 100 });
+
+/** True when team multi-writer mode is enabled in config. */
+function isMultiWriter(config) {
+  return !!(config && config.collab && config.collab.multi_writer_enabled === true);
+}
+
+/**
+ * Resolve the acquire() options for the current config. A numeric `collab.lock_timeout_ms`
+ * overrides the team-mode maxWaitMs. Returns a fresh object (never the frozen constants).
+ */
+function acquireOpts(config) {
+  const base = isMultiWriter(config) ? TEAM : SINGLE;
+  const out = { staleMs: base.staleMs, maxWaitMs: base.maxWaitMs, pollMs: base.pollMs };
+  if (isMultiWriter(config)) {
+    const t = Number(config.collab.lock_timeout_ms);
+    if (Number.isFinite(t) && t > 0) out.maxWaitMs = t;
+  }
+  return out;
+}
+
+module.exports = { isMultiWriter, acquireOpts, SINGLE, TEAM };

package/scripts/lib/collab/permissions.cjs

@@ -0,0 +1,53 @@
+'use strict';
+// Phase 40 — permissions.cjs — PURE, dep-free section-write permission model (SC#10).
+//
+// `.design/config.json#permissions` declares who may perform which action on which STATE.md section.
+// The model is permissive-by-default (single-operator projects are unaffected): with no `permissions`
+// block, everyone is an `owner` and `can(...)` is always true. A team narrows it, e.g. "only
+// @lead-designer can `lock` decisions". A CI gate calls `can()` to enforce on PRs.
+//
+// Shape of config.permissions:
+//   {
+//     "default": "owner",                     // role for any actor not listed
+//     "actors": { "@alice": "reviewer", ... },// per-actor role
+//     "rules": [ { "section": "decisions", "action": "lock", "roles": ["owner"] }, ... ]
+//   }
+// A rule restricts (section, action) to the listed roles. No matching rule ⇒ allowed (permissive).
+//
+// No `require` — pure. Deterministic.
+
+const SECTIONS = Object.freeze(['decisions', 'prototyping', 'rollout_status', 'status', 'progress', 'blockers']);
+const ACTIONS = Object.freeze(['write', 'lock', 'unlock', 'approve']);
+const ROLES = Object.freeze(['owner', 'contributor', 'reviewer', 'viewer']);
+
+/** The role assigned to `actor` by the config (falls back to config.default, then 'owner'). */
+function roleOf(config, actor) {
+  const perms = (config && config.permissions) || {};
+  const actors = perms.actors || {};
+  if (actor && Object.prototype.hasOwnProperty.call(actors, actor)) return actors[actor];
+  return perms.default || 'owner';
+}
+
+/**
+ * May `actor` perform `action` on `section` under this config?
+ * Permissive by default: a (section, action) with no matching rule is allowed. A matching rule
+ * allows only its listed roles. `viewer` is denied any mutating action even absent a rule.
+ */
+function can(config, actor, section, action) {
+  const role = roleOf(config, actor);
+  if (role === 'viewer') return false; // viewers never mutate
+  const perms = (config && config.permissions) || {};
+  const rules = Array.isArray(perms.rules) ? perms.rules : [];
+  const matching = rules.filter(
+    (r) => r && (r.section === section || r.section === '*') && (r.action === action || r.action === '*'),
+  );
+  if (matching.length === 0) return true; // no restriction → allowed
+  return matching.some((r) => Array.isArray(r.roles) && r.roles.includes(role));
+}
+
+/** The default permissive policy (used when config has no permissions block). */
+function defaultPolicy() {
+  return { default: 'owner', actors: {}, rules: [] };
+}
+
+module.exports = { SECTIONS, ACTIONS, ROLES, roleOf, can, defaultPolicy };

package/scripts/lib/collab/review-queue.cjs

@@ -0,0 +1,64 @@
+'use strict';
+// Phase 40 — review-queue.cjs — PURE, dep-free async-review state machine for decisions (SC#7).
+//
+// Each decision under review lives at .design/reviews/<decision-id>/ and moves through:
+//   proposed → reviewing → approved → locked
+// `locked` is terminal and HARD: a locked decision cannot be amended. The only way back is an
+// explicit, AUDITED unlock (/gdd:unlock-decision <id> --approver <who>), which records who reopened
+// it and why. This module is the pure transition core — the skill does the filesystem I/O.
+//
+// No `require` — pure. Deterministic.
+
+const STATES = Object.freeze(['proposed', 'reviewing', 'approved', 'locked']);
+
+// Allowed forward transitions per state. `locked` has none (terminal — unlock() is the escape hatch).
+const TRANSITIONS = Object.freeze({
+  proposed: ['reviewing'],
+  reviewing: ['approved', 'proposed'], // can bounce back for revision
+  approved: ['locked', 'reviewing'],
+  locked: [],
+});
+
+/** True while a decision may still be edited (before it is locked). */
+function canAmend(state) {
+  return state === 'proposed' || state === 'reviewing';
+}
+
+/**
+ * Apply a transition. `event` is the TARGET state.
+ * @returns the new state string. Throws on an invalid transition.
+ */
+function transition(state, event) {
+  if (!STATES.includes(state)) throw new Error(`review-queue: unknown state "${state}"`);
+  if (!STATES.includes(event)) throw new Error(`review-queue: unknown target "${event}"`);
+  const allowed = TRANSITIONS[state];
+  if (!allowed.includes(event)) {
+    throw new Error(`review-queue: illegal transition ${state} -> ${event} (allowed: ${allowed.join(', ') || 'none'})`);
+  }
+  return event;
+}
+
+/**
+ * Explicit audited unlock of a locked decision. Moves locked -> reviewing and returns the new entry
+ * with an appended audit record. Requires a non-empty approver. Throws if the entry is not locked.
+ * @param {{id, state, audit?: Array}} entry
+ * @param {{approver: string, reason?: string}} opts
+ */
+function unlock(entry, opts) {
+  if (!entry || entry.state !== 'locked') {
+    throw new Error('review-queue: unlock() requires a locked decision');
+  }
+  const approver = opts && opts.approver ? String(opts.approver).trim() : '';
+  if (!approver) throw new Error('review-queue: unlock() requires an approver');
+  const audit = Array.isArray(entry.audit) ? entry.audit.slice() : [];
+  audit.push({ action: 'unlock', from: 'locked', to: 'reviewing', approver, reason: (opts && opts.reason) || '' });
+  return Object.assign({}, entry, { state: 'reviewing', audit });
+}
+
+/** Filter queue entries that still need a human action (not yet locked). */
+function pending(entries) {
+  if (!Array.isArray(entries)) throw new Error('review-queue: pending() needs an array');
+  return entries.filter((e) => e && e.state !== 'locked');
+}
+
+module.exports = { STATES, TRANSITIONS, canAmend, transition, unlock, pending };

package/scripts/lib/collab/section-merge.cjs

@@ -0,0 +1,77 @@
+'use strict';
+// Phase 40 — section-merge.cjs — PURE, dep-free per-section semantic merge for STATE.md (SC#1).
+//
+// The chosen multi-writer model (ROADMAP default) is a git-merge-driver with PER-SECTION semantic
+// conflict detection — strictly safer than a line-based merge for the append-mostly `<decisions>`
+// block. Two developers each adding a new D-NN on parallel branches should merge cleanly (union by
+// id); a real conflict is ONLY when the SAME id diverges in text or status. This module is the merge
+// core: it takes three decision arrays (base/ours/theirs, already parsed by attribution.cjs) and
+// returns the merged set plus any genuine conflicts for the conflict-resolver agent to resolve.
+//
+// No `require` — pure. Deterministic (stable id-sorted output).
+
+function byId(list) {
+  const m = new Map();
+  for (const d of list || []) if (d && d.id) m.set(d.id, d);
+  return m;
+}
+
+function sameDecision(a, b) {
+  return a.text === b.text && (a.status || null) === (b.status || null) &&
+    (a.author || null) === (b.author || null) && (a.coAuthor || null) === (b.coAuthor || null);
+}
+
+/** Numeric sort by the D-NN id (D-2 before D-10). */
+function idNum(id) {
+  const m = String(id).match(/(\d+)/);
+  return m ? parseInt(m[1], 10) : 0;
+}
+
+/**
+ * Three-way merge of `<decisions>` (base = common ancestor; ours/theirs = the two branches).
+ * @returns {{merged: Decision[], conflicts: [{id, ours, theirs}], added: string[]}}
+ *   - id only in one side (vs base) → kept (union).
+ *   - id in both sides, equal → kept once.
+ *   - id in both sides, divergent → CONFLICT (and `ours` is kept provisionally so the merged set is
+ *     still complete; the resolver overwrites after the human picks).
+ *   - id removed on one side but unchanged on the other → kept (deletions are never auto-applied —
+ *     decisions are durable; an explicit unlock/removal flow handles that).
+ */
+function mergeDecisions(base, ours, theirs) {
+  const B = byId(base);
+  const O = byId(ours);
+  const T = byId(theirs);
+  const ids = new Set([...O.keys(), ...T.keys(), ...B.keys()]);
+  const merged = [];
+  const conflicts = [];
+  const added = [];
+  for (const id of ids) {
+    const o = O.get(id);
+    const t = T.get(id);
+    const b = B.get(id);
+    if (o && t) {
+      if (sameDecision(o, t)) { merged.push(o); }
+      else { conflicts.push({ id, ours: o, theirs: t }); merged.push(o); }
+    } else if (o && !t) {
+      merged.push(o);
+      if (!b) added.push(id); // ours added it
+    } else if (!o && t) {
+      merged.push(t);
+      if (!b) added.push(id); // theirs added it
+    }
+    // (!o && !t) — present only in base, removed on both → drop.
+  }
+  merged.sort((a, x) => idNum(a.id) - idNum(x.id));
+  added.sort((a, x) => idNum(a) - idNum(x));
+  return { merged, conflicts, added };
+}
+
+/** Scalar merge for a single-value section (e.g. status): equal → value; divergent → conflict marker. */
+function mergeStatusScalar(base, ours, theirs) {
+  if (ours === theirs) return { value: ours, conflict: false };
+  if (ours === base) return { value: theirs, conflict: false }; // only theirs changed
+  if (theirs === base) return { value: ours, conflict: false }; // only ours changed
+  return { value: ours, conflict: true }; // both changed differently
+}
+
+module.exports = { mergeDecisions, mergeStatusScalar, sameDecision };

package/scripts/lib/collab/sync-backend.cjs

@@ -0,0 +1,36 @@
+'use strict';
+// Phase 40 — sync-backend.cjs — PURE, dep-free cross-machine sync backend selector (SC#9).
+//
+// `.design/` syncs between teammates over git by DEFAULT (existing behavior). Orgs whose git
+// push/pull cadence is too slow can opt into an `s3` or `git-lfs` backend. This module is the
+// SELECTOR + contract: it resolves which backend a config asks for and whether sync is opted in.
+// A live S3/LFS client is explicitly out of scope this phase — the selector ships, the backend is
+// pluggable. Defaulting to `git` means single-operator + most-team projects are unaffected.
+//
+// No `require` — pure. Deterministic.
+
+const BACKENDS = Object.freeze(['git', 's3', 'git-lfs']);
+const DEFAULT_BACKEND = 'git';
+
+/** True when the project opted into a non-git sync backend. */
+function isOptIn(config) {
+  const b = config && config.collab && config.collab.sync_backend;
+  return !!b && b !== 'git' && BACKENDS.includes(b);
+}
+
+/**
+ * Resolve the sync backend. Unknown/missing → 'git' (the safe default).
+ * @returns {{backend, optIn, supported}}  supported=false for opt-in backends whose live client
+ *   is not bundled this phase (the caller falls back to git + warns).
+ */
+function resolveBackend(config) {
+  const raw = config && config.collab && config.collab.sync_backend;
+  const backend = BACKENDS.includes(raw) ? raw : DEFAULT_BACKEND;
+  const optIn = backend !== DEFAULT_BACKEND;
+  // Phase 40 ships the selector only; no live S3/LFS client → opt-in backends are "declared but not
+  // yet executable". git is always supported (it's the existing push/pull path).
+  const supported = backend === DEFAULT_BACKEND;
+  return { backend, optIn, supported };
+}
+
+module.exports = { BACKENDS, DEFAULT_BACKEND, isOptIn, resolveBackend };

package/skills/review-decisions/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: gdd-review-decisions
+description: "Surfaces the async decision-review queue for team mode. Reads .design/reviews/<decision-id>/ entries and reports each decision's state in the proposed → reviewing → approved → locked machine (via scripts/lib/collab/review-queue.cjs), so a team can see what's awaiting review, what's approved, and what's locked. --pending shows only decisions still needing action. Read-only — it reports the queue; it never advances a decision (that's a reviewer's explicit call). Use to run an async design-decision review without a meeting."
+argument-hint: "[<decision-id>] [--pending]"
+user-invocable: true
+tools: Read, Bash, Grep, Glob
+---
+
+# /gdd:review-decisions
+
+Closes the async-review gap for team mode: design decisions move through an explicit review queue
+instead of being decided in a single operator's head. This skill reports where each decision is.
+**Read-only** — it surfaces state; advancing a decision is a reviewer's explicit action. Contract:
+`../../reference/multi-author-model.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:review-decisions` | Every decision in the queue, grouped by state. |
+| `/gdd:review-decisions <decision-id>` | One decision's state + audit trail. |
+| `/gdd:review-decisions --pending` | Only decisions not yet `locked` (awaiting action). |
+
+## Steps
+
+1. **Find the queue.** List `.design/reviews/*/` (each dir is a `<decision-id>`). No reviews dir →
+   print `review-decisions: no review queue yet (team mode not in use).` and exit.
+2. **Read each entry** (`.design/reviews/<id>/state.json` → `{ id, state, audit }`). Validate the
+   state against `scripts/lib/collab/review-queue.cjs` `STATES`.
+3. **Render** grouped by state: `proposed` / `reviewing` / `approved` / `locked`, each listing the
+   decision id + a one-line summary. For `--pending`, use `review-queue.pending(entries)` to show only
+   non-locked ones. For a single `<decision-id>`, also print its audit trail (transitions + approvers).
+4. **Do not advance.** Reporting only — moving a decision forward (or `/gdd:unlock-decision`) is the
+   reviewer's explicit call.
+
+## Output
+
+End with:
+
+```
+## REVIEW-DECISIONS COMPLETE
+```

package/skills/unlock-decision/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-unlock-decision
+description: "Reopens a LOCKED design decision — the only escape hatch from the hard lock. Requires an explicit --approver and writes an audit entry, then moves the decision locked → reviewing (via scripts/lib/collab/review-queue.cjs). Previews the audit record before writing; never unlocks silently. Use when a locked decision genuinely must change (a later constraint invalidated it) and a reviewer has signed off."
+argument-hint: "<decision-id> --approver <who> [--reason <text>] [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# /gdd:unlock-decision
+
+A `locked` decision is hard — it cannot be amended. This skill is the **only** way back, and it is
+deliberately heavyweight: it requires a named approver and records an audit entry, so reopening a
+locked decision is always traceable. Contract: `../../reference/multi-author-model.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:unlock-decision <id> --approver <who>` | Unlock `<id>` (locked → reviewing), recording the approver. |
+| `/gdd:unlock-decision <id> --approver <who> --reason <text>` | Same, with a reason in the audit entry. |
+| `/gdd:unlock-decision <id> --dry-run` | Preview the audit record + the resulting state; change nothing. |
+
+## Steps
+
+1. **Validate args.** `<decision-id>` required; `--approver` required (a non-empty name). Missing
+   `--approver` → print the usage + exit without changing anything.
+2. **Load the entry** from `.design/reviews/<decision-id>/state.json`. Not found → report it. Not in
+   `locked` state → print `unlock-decision: <id> is not locked (state: <state>); nothing to unlock.`
+3. **Preview.** Show the audit entry that will be appended (`{ action: unlock, from: locked, to:
+   reviewing, approver, reason }`) and the resulting state. If `--dry-run`, stop here.
+4. **Apply** via the pure helper:
+
+   ```bash
+   node -e '
+     const fs = require("fs");
+     const rq = require("./scripts/lib/collab/review-queue.cjs");
+     const p = process.argv[1], approver = process.argv[2], reason = process.argv[3] || "";
+     const entry = JSON.parse(fs.readFileSync(p, "utf8"));
+     const next = rq.unlock(entry, { approver, reason });
+     fs.writeFileSync(p, JSON.stringify(next, null, 2) + "\n");
+     console.log(JSON.stringify(next.audit[next.audit.length - 1]));
+   ' ".design/reviews/<id>/state.json" "<who>" "<reason>"
+   ```
+
+5. **Report** the new state + the recorded approver. The decision is now `reviewing` and amendable
+   again; it must be re-reviewed + re-locked to become durable.
+
+## Output
+
+End with:
+
+```
+## UNLOCK-DECISION COMPLETE
+```