@magnusekdahl/parallix 1.0.0

package/docs/adr/0034-module-and-skill-invocation-model.md

@@ -0,0 +1,202 @@
+# ADR 0034 — Module and Skill Invocation Model
+
+**Status:** Accepted
+**Date:** 2026-04-05
+
+## Context
+
+The repo already has:
+
+- `AGENTS.md` as the authority for hard rules, trust tiers, and verification commands
+- `MISSION_FLOW.md` plus mode prompts as the lifecycle and execution surface
+- `MISSION.md` as the per-mission execution contract
+- `Backlog.md` as the current-state layer
+- a Skills layer documented in `docs/ai-workflow/SKILLS_ARCHITECTURE.md`
+
+That architecture made the workflow modular, but it left one governance gap unresolved: how agents should select and re-select workflow modules and skills during execution.
+
+The current state had three weaknesses:
+
+1. the workflow rejected always-loaded optional context, but did not fully define the replacement model
+2. some documents implied explicit invocation, but the repo did not yet decide how much should be phase-driven versus self-invoked versus registry-driven
+3. no durable decision explained how autonomy, explicitness, debuggability, and validation guarantees should coexist
+
+This matters because the repo is intentionally multi-agent and tool-agnostic. A hidden or runtime-specific invocation model would undermine portability and make debugging difficult. A manual-only model would undermine autonomy. An always-loaded model would grow the default context surface every time the workflow added a new capability.
+
+## Decision Drivers
+
+- Keep default context bounded as the workflow gains more modules
+- Preserve autonomy for normal mission execution
+- Keep invocation behavior explicit and inspectable
+- Avoid hidden runtime-specific or wrapper-specific attachment logic
+- Guarantee that validation and review-critical modules cannot be silently skipped
+- Keep the model teachable across Claude, Codex, Gemini, and future runtimes
+- Avoid introducing a heavier registry/control-plane mechanism before it is justified
+
+## Considered Options
+
+### A. Manual human-triggered invocation
+
+Human explicitly names each optional module or skill to load.
+
+### B. Fully implicit model-driven auto-loading
+
+Runtime heuristics or the model silently decide which modules to attach.
+
+### C. Rule-based self-invocation with explicit declaration
+
+The agent loads optional modules using explicit repo rules and declares each load.
+
+### D. Phase-bound invocation
+
+Lifecycle stage determines which modules are used by default.
+
+### E. Registry-driven invocation
+
+A central registry maps task shape or triggers to module selection.
+
+### F. Context-splitting or subagent invocation
+
+When task shape changes materially, a new context or subagent handles the new slice.
+
+### G. Hybrid of C and D, with stronger guarantees for validation-critical modules
+
+Stage/mode establishes the baseline; the agent may explicitly add modules when trigger rules fire; validation and review-critical modules become mandatory once relevant.
+
+### H. GSD-style harness-mediated architecture
+
+Command entrypoints dispatch into workflow orchestrators, which load template-backed state, helper tooling, and specialized agents behind a compact command façade.
+
+## Comparison Summary
+
+The mission-local analysis artifact contains the full matrix and measurement evidence:
+
+- [Task 019 invocation analysis](../missions/2026/task-019/INVOCATION_MODEL_ANALYSIS.md)
+
+Summary outcome:
+
+- A is explicit but too dependent on the human
+- B is flexible but too opaque and runtime-sensitive
+- C is strong, but by itself does not give enough stage-level predictability
+- D is strong, but by itself is too rigid for real mid-flight shape changes
+- E is viable later, but too heavy for the current workflow maturity
+- F is a useful secondary tactic, not a good primary invocation model
+- H is credible and has real ergonomic strengths, but adopting it here would imply a broader workflow-architecture migration rather than a bounded invocation-governance decision
+- G best balances autonomy, boundedness, explicitness, and validation integrity
+
+## Decision
+
+Adopt this invocation model for the repo AI workflow:
+
+**Phase-bound default invocation with rule-based self-invocation, explicit declaration, and mandatory validation-module loading.**
+
+The model works as follows:
+
+1. **Stage-bound baseline**
+   - Mode, mission contract, and current checkpoint establish the mandatory baseline context.
+   - The baseline includes the relevant authority docs, the current mode prompt, and only the inventory-level visibility needed to discover optional modules.
+
+2. **Rule-based optional expansion**
+   - The agent may load additional modules or skills only when explicit trigger conditions are met.
+   - Trigger conditions include phase change, checkpoint change, entering a new restricted subsystem, failed verification, review feedback, blocked evidence path, or a material task-shape shift.
+
+3. **Explicit declaration**
+   - Optional module loads must be declared at load time.
+   - The declaration must make visible:
+     - what is being loaded
+     - what triggered the load
+     - why the already-loaded set is insufficient
+
+4. **Validation and review guarantees**
+   - Validation, gate, review, and integration-critical modules are not optional once their gate or handoff point is active.
+   - They may still be loaded on demand, but they cannot be skipped silently or replaced by vague "best effort" reasoning.
+
+5. **Fallback rule**
+   - If no existing module fits, the agent falls back to canonical authorities plus an explicit local plan.
+   - The agent does not invent hidden attachment behavior.
+   - If the gap is recurring and reusable, it becomes follow-up workflow work rather than an undocumented convention.
+
+6. **Context-splitting is secondary**
+   - New contexts or subagents may still be used when task shape changes materially.
+   - They are not the primary invocation mechanism and do not replace the declaration model above.
+
+## What Is Decided
+
+- Invocation is not manual-only.
+- Invocation is not hidden auto-loading.
+- Stage and lifecycle position matter for the baseline.
+- Optional expansion is allowed, but only through rule-bounded self-invocation with explicit declaration.
+- Validation and review-critical capabilities must remain impossible to skip silently.
+- The runtime-governing model is repo-defined and tool-agnostic.
+
+## What Is Not Decided
+
+- No registry schema or control-plane implementation is introduced here.
+- No wrapper-level auto-loader is introduced here.
+- No vendor-specific attachment behavior is standardized here.
+- No new subagent orchestration policy is introduced here beyond keeping it secondary.
+- No new skill inventory expansion is required by this ADR.
+
+## Consequences
+
+### Positive
+
+- The workflow gets an explicit answer for how invocation works without requiring always-loaded detail.
+- Agents retain autonomy during normal execution.
+- Invocation decisions become inspectable and teachable.
+- The Skills layer remains modular without drifting into hidden behavior.
+- The model scales to more modules without forcing them into the default read surface.
+
+### Negative
+
+- Agents must now follow declaration discipline when adding optional modules.
+- Some prompt and workflow docs need maintenance to keep trigger rules visible and aligned.
+- The model still relies on human-readable rule quality; poor trigger wording would weaken it.
+- Registry-driven automation is deferred, so repeated manual declaration patterns may still exist for a while.
+
+## Rejected Options And Why
+
+### Manual-only invocation
+
+Rejected because it makes autonomous execution too dependent on human prompting quality and handles mid-flight change poorly.
+
+### Fully implicit auto-loading
+
+Rejected because it weakens explicitness, portability, and debuggability, and creates silent validation risk.
+
+### Pure phase-bound invocation
+
+Rejected because it is too rigid for real checkpoint and evidence-path changes during execution.
+
+### Registry-driven invocation as the primary model
+
+Rejected for now because it adds control-plane and maintenance complexity before the governance model itself needs that weight.
+
+### Context-splitting or subagent-first invocation
+
+Rejected as the primary model because it is too heavy for routine execution and should remain a secondary tactic.
+
+### GSD-style harness-mediated architecture
+
+Rejected for this mission's target decision because it solves the invocation problem partly by changing a broader set of workflow assumptions:
+
+- command façade becomes the dominant entry surface
+- more workflow behavior moves behind installed harness files, templates, and helper tooling
+- the repo's current authority-first visibility would give way to a more orchestration-first model
+
+Those are real strengths in GSD, and this ADR does not dismiss them. But adopting that architecture here would exceed the scope of a bounded invocation-governance mission and would effectively reopen larger decisions about authority layout, state ownership, and workflow packaging.
+
+## Follow-On Implications
+
+- `docs/ai-workflow/CORE_WORKFLOW.md` should explain the invocation loop and re-evaluation triggers explicitly.
+- `docs/ai-workflow/SKILLS_ARCHITECTURE.md` should define the new invocation contract in operational terms.
+- Mode prompts should reference declaration and re-evaluation expectations where needed.
+- Future implementation missions may add metadata or registry support only if they preserve this ADR's explicit declaration and validation guarantees.
+
+## Links
+
+- [ADR 0023](0023-ai-sdlc-configuration.md)
+- [ADR 0026](0026-ai-task-state-and-agent-recovery-surface.md)
+- [ADR 0032](0032-mission-refinement-state-and-usage-budget-signals.md)
+- [Task 019 mission](../missions/2026/task-019/MISSION.md)
+- [Task 019 invocation analysis](../missions/2026/task-019/INVOCATION_MODEL_ANALYSIS.md)

package/docs/adr/0036-mission-sizing-and-dependency-wave-heuristics.md

@@ -0,0 +1,79 @@
+# ADR 0036: Mission Sizing and Dependency-Wave Heuristics
+
+**Status:** Accepted
+**Date:** 2026-04-05
+
+## Context
+
+As the number of concurrent missions and agents increases, the repository requires a standardized way to:
+1. Prevent missions from hitting agent limits (token/usage budgets) midway through implementation.
+2. Enable safe parallel work by managing dependencies.
+3. Optimize the use of finite token budgets across the mission portfolio.
+
+Previously, all missions followed the same full `MISSION.md` + checkpoint sequence, regardless of size. This created unnecessary ceremony for small fixes and led to "over-budget" failures for large ones.
+
+## Decision
+
+Introduce three sizing tracks and a dependency-wave planning heuristic.
+
+### 1. Sizing Tracks
+
+| Track | Scope | Process | Agent Budget |
+|-------|-------|---------|--------------|
+| **Quick Flow** | < 3 files, < 2h estimated, or docs-only. | Minimal `MISSION.md` (Goal, Why Now, Refinement Signals, Gates). Skip detailed checkpoints if straightforward. | < 10% of agent limit |
+| **Full Method** | > 3 files, complex logic, or > 2h. | Standard `MISSION.md` with all sections. Detailed checkpoints. Mandatory external review (C2 review remains required for sensitive scopes per AGENTS.md). | 10-50% of agent limit |
+| **Multi-Wave** | Very large, high risk, or complex dependencies. | Split into multiple `Full Method` missions (waves). | Total > 50% (requiring split) |
+
+### 2. "Too Large" Thresholds by Agent
+
+A mission is "Too Large" if its `Estimated agent % usage limit` exceeds the following thresholds per session/work-unit:
+
+- **Claude**: > 50% of daily limit.
+- **Codex**: > 25% of weekly limit.
+- **Gemini**: > 50% of the reasonable session/context budget (approx. 50k-100k tokens for execution).
+
+Missions exceeding these thresholds MUST be split into dependency waves before activation.
+
+### 3. Dependency-Wave Heuristic
+
+When a mission is too large or has complex dependencies, it must be planned in "waves":
+
+- **Wave 1: Foundation**: Infrastructure, core logic, or data models that other parts depend on.
+- **Wave 2: Implementation**: Main features or integration logic.
+- **Wave 3: Polish & Verification**: Advanced UI, edge cases, and final E2E validation.
+
+**Wave Execution Rules:**
+1. **Upfront Sequence**: The full sequence of waves must be defined during the `draft` phase of Wave 1.
+2. **Sequential Integration**: Each wave MUST reach `done` status (merged into `master`) before the next dependent wave can transition from `ready` to `active`. Parallel execution of dependent waves is NOT permitted.
+3. **Production Readiness**: Per trunk-based development, each wave MUST be production-ready, functional, and safe for production use upon integration into `master`. No "broken" or "partially-functional" states are permitted in the main branch.
+4. **Integration Boundary**: Each wave is a separate mission. Upon completion, its branch is merged into `master` via a single squash/merge commit.
+5. **Mandatory Review**: Each wave MUST pass its own external review (and C2 review if the scope is sensitive per AGENTS.md) before integration into `master`.
+6. **Context Clearing**: Each subsequent wave MUST be executed in a fresh agent session/context. This prevents context bloat and ensures the previous wave's outcomes are documented well enough for a "new" agent to resume work.
+7. **Context Carryover**: Each subsequent wave's `MISSION.md` must explicitly reference the completed mission and outcomes of the previous wave in its `## Why Now` or `## Context` section.
+8. **Verification Boundary**: Each wave must pass its own validation gates. Wave 3 (or the final wave) must include a full E2E validation of the entire multi-wave feature set.
+
+**Parallelism Rules:**
+- Missions can run in parallel ONLY if they do not touch the same files or shared logic.
+- If a dependency exists, the dependent mission must wait until the parent mission is `done` (merged to `master`).
+- Use the `dependencies` field in `Backlog.md` tasks to track these relationships.
+
+### 4. Mandatory Task Assignment
+
+Agents MUST assign themselves to a task in `Backlog.md` before beginning work in `active` mode. This provides immediate visibility into who is working on what across parallel worktrees.
+
+## Consequences
+
+### Positive
+- Reduced ceremony for small, straightforward changes.
+- Predictable mission completion within agent limits.
+- Clearer path for splitting large work into manageable units.
+- Improved visibility of parallel work via mandatory assignment.
+
+### Negative
+- Requires upfront estimation effort during the `draft` phase.
+- Agents must learn to judge their own usage limits accurately.
+
+## Links
+- [ADR 0032](0032-mission-refinement-state-and-usage-budget-signals.md)
+- [MISSION_FLOW.md](../../MISSION_FLOW.md)
+- [AGENTS.md](../../AGENTS.md)

package/docs/adr/0037-ai-workflow-coordination-architecture.md

@@ -0,0 +1,162 @@
+# ADR 0037: AI Workflow Coordination Architecture
+
+Status: Proposed
+Date: 2026-04-06
+
+## Context
+
+The repo's AI SDLC has a coordination problem that plays out at two points in every mission:
+
+**At session start:** A fresh agent must reconstruct the current mission state from multiple sources before doing any useful work. This reconstruction fails systematically — enough to have generated dedicated remediation missions (`backlog-sdlc-instructions-fix`, `repair-autonomous-review-launcher`, `fix-codex-crashes`). See `ARCHITECTURE_PROPOSAL.md §1.2` (task-068) for the full failure enumeration.
+
+**At session end or mid-session limit:** An agent hitting a usage limit needs to persist state so the next agent can resume. Currently this relies on checkpoint commits + git log inspection, which agents get wrong under pressure.
+
+The workflow already has scripted coordination for review and integration: `node workflow`, `scripts/autonomous-review.sh`, `scripts/verify-local.sh`, `scripts/cleanup-mission-worktree.sh`. Each replaced a documented procedure that agents were failing to follow. The pattern is established: **code beats documentation for coordination steps**.
+
+This ADR decides which architectural approach should extend that pattern to the remaining coordination gaps (startup, checkpoint persistence, session handoff).
+
+### State layer clarification
+
+The repo already has two layers of mission state that do not need to change:
+
+**Coarse task lifecycle state:** the Backlog task `status` field (`backlog/tasks/<task-id>*.md`, actual values in `backlog/config.yml`). The workflow uses virtual state names (`backlog | ready | active | review | approved | done`) mapped to actual backlog.md values via `workflow/config/state-map.json`. Authoritative task lifecycle per ADR 0026.
+
+**Session handover state:** checkpoint artifact files committed to the mission branch under `docs/missions/2026/<slug>/` (e.g. `CHECKPOINT_3_GSD_COMPARISON.md`). Existing practice for mid-mission handover between agents or sessions.
+
+No new state mechanism is needed. The coordination CLI reads these existing surfaces.
+
+### GSD CLI tools layer (reference architecture)
+
+GSD's `gsd-tools.cjs` is a Node.js CLI with 19 domain modules, handling state, config, phase operations, git commits, and verification. It replaces "repetitive inline bash patterns across ~50 GSD command/workflow/agent files." The architectural separation: agents call the CLI tools; they do not shell out to bash or parse files directly.
+
+The selected option below adapts this pattern to this repo's artifacts (MISSION.md, Backlog, Forgejo) instead of GSD's (.planning/, STATE.md, ROADMAP.md).
+
+## Decision
+
+**Adopt Option C' (Lightweight Node.js Harness, Repo-Adapted).**
+
+### Implementation contract
+
+- **Package:** `workflow/` directory at project root; entry point `workflow/index.js`; invoked as `node workflow <command> [args]`
+- **Module structure:** each command in its own module under `workflow/lib/` from the start — no accumulation in a single file
+- **Three initial commands:** `mission-start`, `checkpoint`, `status`
+- **State inputs:** Backlog task `status` field + existing checkpoint docs in `docs/missions/2026/<slug>/` — no new state store
+- **Integrates with:** calls Forgejo API via `workflow/lib/forgejo.js`, `scripts/verify-local.sh`, Backlog MCP
+- **New commands:** go in new `workflow/lib/<command>.js` files, not appended to `index.js`
+- **Grows only** when a new coordination gap is identified
+
+### Commands
+
+```
+node workflow mission-start <slug>
+    — verifies directory, branch, reads Backlog task status,
+      reads most recent checkpoint doc in docs/missions/2026/<slug>/,
+      reads Forgejo PR state, outputs structured PASS/WARN/FAIL report
+
+node workflow checkpoint <slug> <cp-name> "<next-action>"
+    — runs verify gate, stages all changes including checkpoint doc the agent
+      wrote under docs/missions/2026/<slug>/, commits, pushes
+
+node workflow status [<slug>]
+    — reads Backlog task status, most recent checkpoint doc, last 3 commits,
+      Forgejo PR state, uncommitted files; outputs human-readable summary
+```
+
+### Directory layout (initial)
+
+```
+workflow/
+  index.js          — CLI entry, command dispatch
+  lib/
+    mission-start.js
+    checkpoint.js
+    status.js
+    git.js          — shared git helpers
+    backlog.js      — Backlog task file reader
+    forgejo.js      — the Forgejo API client
+```
+
+### Fallback
+
+Option B (bash scripts) if the Node.js investment is deferred. The architectural principle — scripted coordination layer, agents do not follow documented procedures — is the same.
+
+## Decision matrix
+
+| Option | Coord. automation | Agent-agnostic | Adoption cost | Compatibility | State quality | Reversibility | Total |
+|---|---|---|---|---|---|---|---|
+| A: Extend instructions | 1 | 5 | 5 | 5 | 1 | 5 | 22 |
+| B: Bash scripts | 4 | 5 | 4 | 5 | 3 | 5 | 26 |
+| C: Full GSD | 5 | 3 | 1 | 3 | 5 | 2 | 19 |
+| **C': Lightweight Node.js** | **4** | **5** | **3** | **5** | **5** | **5** | **27** |
+| D: BMAD-like | 4 | 5 | 1 | 2 | 5 | 2 | 19 |
+| E: Gemini CLI-like | 3 | 3 | 3 | 4 | 3 | 5 | 21 |
+
+Scoring: 5 = strongest fit / 1 = weakest fit. Adoption cost scored inversely (5 = lowest cost).
+
+## Consequences
+
+### Positive
+
+- `node workflow` entry point replaces ad-hoc bash coordination across 50+ agent-followed steps
+- No new state store — reads existing Backlog task `status` + checkpoint docs in `docs/missions/2026/<slug>/`
+- Multi-file structure from the start prevents single-file accumulation; module boundaries set before complexity arrives
+- Extends the proven harness pattern (`node workflow`, `scripts/autonomous-review.sh`, `scripts/verify-local.sh`, `scripts/cleanup-mission-worktree.sh`)
+- Node.js handles JSON/YAML parsing, error handling, and testability natively
+
+### Negative
+
+- Node.js knowledge required for `workflow/` maintenance
+- `node workflow checkpoint` must be called by agents — behavior change from current manual commit practice
+- Module boundary decisions needed as new commands are added
+
+## Alternatives considered
+
+### Option A: Extend Current Instructions
+
+More documentation in AGENTS.md, MISSION_FLOW.md, execute.md.
+
+Positive: near-zero adoption cost, trivially reversible.
+
+Negative: all observed startup failures happen despite existing documentation. Adding more documentation extends the surface that can fail. Ruled out as primary approach.
+
+### Option B: Extend Scripting Support (Bash)
+
+Bash scripts in `scripts/`: `mission-start.sh`, `mission-checkpoint.sh`, `mission-status.sh`.
+
+Positive: proven pattern in this repo, no new dependencies, simple.
+
+Negative: bash quoting and error handling become fragile at scale. JSON/Markdown parsing in bash is error-prone. GSD's experience: gsd-tools.cjs replaced 50+ bash patterns precisely because bash at scale was unmaintainable. Retained as fallback if Node.js investment is deferred.
+
+### Option C: Full GSD-like Architecture
+
+Install `get-shit-done-cc` npm package; adopt full .planning/ file tree, 60+ commands, 21 specialist agents.
+
+Positive: very high coordination automation, excellent state quality.
+
+Negative: very high adoption cost, low compatibility (MISSION.md vs .planning/ authority conflict, low reversibility). Full adoption reopens authority questions without new evidence. The CLI tools layer concept is the one adoptable element — extracted as C'.
+
+### Option D: BMAD-like Architecture
+
+`_bmad/` directory, YAML state machine, 6 agent personas, 34+ workflow files.
+
+Positive: high coordination automation, excellent YAML-typed state.
+
+Negative: very high adoption cost, low compatibility with existing AGENTS.md + MISSION.md. Tier-1 ideas (readiness gate, adversarial review) already adopted via ADR 0033/TASK-055. Full framework disproportionate for a 5-8h/week personal project.
+
+### Option E: Gemini CLI-like Architecture
+
+Per-CLI config files (`~/.gemini/settings.json`, `.gemini/settings.json`) plus MCP server integration.
+
+Positive: correct for per-CLI workspace configuration (already in use).
+
+Negative: per-CLI config is correct for workspace scope, not session handoff. Session state must be git-native (on the mission branch) to be accessible to all agents. Wrong layer for this problem.
+
+## Links
+
+- [ADR 0026](0026-ai-task-state-and-agent-recovery-surface.md) — Backlog as current-state layer
+- [ADR 0030](0030-selective-gsd-strategy.md) — Selective GSD strategy
+- [ADR 0033](0033-workflow-toolkit-comparative-scan.md) — Toolkit scan (BMAD, Aider)
+- [ADR 0034](0034-module-and-skill-invocation-model.md) — Invocation model
+- [ARCHITECTURE_PROPOSAL.md](../missions/2026/task-068/ARCHITECTURE_PROPOSAL.md) §6 — Harness-first analysis
+- [FOLLOW_UP_MISSIONS.md](../missions/2026/task-068/FOLLOW_UP_MISSIONS.md) — F0 implements this ADR
+- GSD architecture: `/tmp/gsd-harness/docs/ARCHITECTURE.md` (cloned 2026-04-06, v1.33.0)

package/docs/adr/0041-integration-pipeline-gates.md

@@ -0,0 +1,165 @@
+# ADR 0041: Integration-time pipeline gates + per-area gate dehallucination
+
+Status: Accepted
+
+## Context
+
+The repo runs integration via `node workflow integrate`, which currently performs only preflight checks and squash-merge operations. There are two active problems:
+
+1. **Missing integration-time gates:** Staging deploy and e2e validation do not run as part of integration. task-1093 recorded that "I have not been running the full e2e web tests flows as part of the mission integration, as a result of this the store tests have been failing." This creates a gap where integration can land code that breaks staging.
+
+2. **Hallucinated per-area web gate:** `scripts/verify-local.sh:41` (inside `gate_web()`) invokes `web-client/scripts/run-playwright-stage.sh` against `https://staging.wrgroceries.com` on every `./scripts/verify-local.sh web` call. The help banner at `scripts/verify-local.sh:196` says `web` covers only "lint + tsc + jest + coverage (85% gate) + Next.js build" — implementation and documentation disagree. Since staging is not redeployed on every agent edit, this gate silently validates the agent's local diff against a stale, unrelated environment, producing **green false positives when the diff is broken** and noise when stage is sick for unrelated reasons.
+
+ADR 0028 (line 58) explicitly noted "the current CI lane currently proves wiring and review visibility more than full clean-checkout confidence; broader PR-time gates remain a follow-up tradeoff decision." This ADR addresses that follow-up.
+
+Task-1063 is extracting `workflow/` as a standalone product. Any integration pipeline must therefore read visualBoard-specific paths from a **repo-side config file**, not hardcode them into `workflow/lib/*.js`.
+
+## Options Evaluated
+
+| Option | Local-first fit | Config seam | Credentials burden | Visibility | Abort-before-merge | Reusability |
+|--------|-----------------|-------------|-------------------|------------|-------------------|-------------|
+| **A. CLI preflight (in `node workflow integrate`)** | High | Repo config | None (workstation) | CLI output | Yes | Single path |
+| **B. Forgejo Actions / runner-side** | Medium | Repo config | Runner: docker push + kustomize | PR UI | Yes | PR-time + manual |
+| **C. Hybrid via new `integrate` area in `verify-local.sh`** | High | Repo config | None (workstation) | CLI output | Yes | Both `integrate` CLI and future Actions |
+
+### Option A: CLI preflight (in `node workflow integrate`)
+
+Extend `buildIntegrationContext` / `printIntegrationPreflight` (`workflow/lib/integrate.js:400`) to read a repo-side config and dispatch area gates before the dry-merge step.
+
+**Pros:**
+- Same process as the squash; easy abort before merge
+- No new runner credentials needed
+- No new services to maintain
+
+**Cons:**
+- Long-running build/deploy becomes part of a CLI command on the workstation
+- Progress/visibility limited to terminal output
+
+### Option B: Forgejo Actions / runner-side
+
+Create new `.forgejo/workflows/integrate.yml` triggered on `mission/**` branch updates or PR open.
+
+**Pros:**
+- Visible in PR UI
+- Reproducible runner environment
+- Matches ADR 0028's broader-PR-gate trigger
+
+**Cons:**
+- Requires runner to hold docker push + kustomize credentials
+- Longer feedback loop (runner availability, queue time)
+- Grows ops surface (runner lifecycle, secrets management)
+
+### Option C: Hybrid via a new `integrate` area in `scripts/verify-local.sh`
+
+Add an `integrate` area to `scripts/verify-local.sh` (today's areas: `docs|workflow|web|server|auth|android|k8s|deps|all` per `scripts/verify-local.sh:172-189`) that performs change-detection + per-area dispatch. Both `node workflow integrate` and a future Forgejo workflow file invoke it.
+
+**Pros:**
+- One dispatch surface, no duplication
+- `workflow/lib/*` stays generic (config in repo)
+- Reusable by both CLI and future runner-based CI
+
+**Cons:**
+- Still requires gating `node workflow integrate` to require it
+- Needs an executable spec for the area-key\u21a6command map
+
+## Decision
+
+**Choose Option C: Hybrid via new `integrate` area in `scripts/verify-local.sh`**, with `node workflow integrate` invoking it as a preflight step.
+
+**Rationale:**
+
+- **Local-first preservation:** Option C keeps execution on the workstation without introducing new credentials or services. Option B would require docker push + kustomize credentials on the runner, which is a material ops burden not justified by current signal.
+- **Workflow-product boundary:** The area-key\u21a6command map lives in a repo-side config file (`config/integration-pipelines.json`). This preserves the task-1063 workflow-product boundary — no visualBoard-specific paths appear in `workflow/lib/*.js`.
+- **Future extensibility:** Once Option C is proven locally, a Forgejo Actions workflow can invoke the same `integrate` area. This defers the runner credential question until we have evidence that the local workstation cannot handle the load.
+- **Abort-before-merge invariant:** The dispatch runs as part of `printIntegrationPreflight` (before the squash-merge at `workflow/lib/integrate.js:319`), so any gate failure aborts before the merge lands.
+
+### Follow-up trigger
+
+Revisit Option B (Forgejo Actions) when the median `pr_fix_rounds` across a trailing 20-mission window exceeds 2, **or** when the local workstation proves unable to complete integration gates within 30 minutes wall-time for a typical single-area mission. This trigger is grounded in the available `workflow/data/stats.csv` signal.
+
+## Data and Evidence
+
+### 1. Originating incident
+
+> task-1093 (`backlog/completed/task-1093 - The-end-to-end-tests-are-broken.md:18`, closed 2026-05-16):
+> > "I have not been running the full e2e web tests flows as part of the mission integration, as a result of this the store tests have been failing."
+
+This mission (task-1094) was filed 9 minutes later (`backlog/tasks/task-1094 ...md:6`, `2026-05-16 17:45`). The incident directly links missing integration-time e2e execution to production failures.
+
+### 2. Help/implementation drift
+
+The `gate_web` function at `scripts/verify-local.sh:36-42` includes:
+```bash
+run_gate "web:e2e"      sh -c "cd web-client && ./scripts/run-playwright-stage.sh"
+```
+
+The help banner at `scripts/verify-local.sh:196` states:
+```
+web      — lint + tsc + jest + coverage (85% gate) + Next.js build
+```
+
+The help text **excludes** e2e. This is evidence that the stage-e2e line (line 41) is unintentional drift, not a designed gate.
+
+### 3. Per-area gate audit
+
+Inspection of all other `gate_*` functions (`scripts/verify-local.sh:145-170`) found **no** equivalent network-dependent hallucination:
+
+- `gate_server` (lines 145-148): checkstyle, spotbugs, compile, test — all local
+- `gate_auth` (lines 150-153): checkstyle, spotbugs, compile, test — all local
+- `gate_android` (lines 155-157): detekt, unit-jacoco — all local
+- `gate_k8s` (lines 159-160): validate-k8s.sh — local dry-run validation
+- `gate_deps` (lines 162-163): dependency-vuln-gate.sh — local scanning
+
+**Result:** The hallucination is isolated to `gate_web:web:e2e`.
+
+### 4. Available rate signal from `workflow/data/stats.csv`
+
+The stats file contains 54 rows as of 2026-05-22 with columns: `date,mission,classification,implementer,pr_fix_rounds`.
+
+For the last 20 missions (rows 35-54):
+- `pr_fix_rounds` sorted: `[0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 2, 4, 8]`
+- **Median:** 1.0
+- **Max:** 8
+- **Count with `pr_fix_rounds >= 3`:** 2 (missions with 4 and 8 rounds)
+
+**Interpretation:** The current median of 1.0 suggests most missions do not require multiple fix rounds. However, the presence of outliers (max=8) indicates that some missions do benefit from earlier detection. This is an imperfect proxy for "would integration-time gates have caught the regression earlier" because it measures review rounds, not integration failures. The limitation is acknowledged.
+
+### 5. Reasoning chain
+
+Option B (Forgejo Actions) would require runner credentials for docker push and kustomize. The only data point that would justify that ops cost is **sustained `pr_fix_rounds >= N` after Option C lands**, demonstrating that local-first execution is insufficient. We adopt **Option C now** — which needs no new credentials and preserves the local-first model — and set the follow-up trigger at `pr_fix_rounds median >= 2 over a trailing 20-mission window`. This threshold is above the current median (1.0) and would be crossed if integration-time gates become systematically necessary.
+
+## Consequences
+
+### Positive
+
+- Integration-time staging deploys and e2e run **before** the squash-merge lands, catching regressions earlier
+- Per-area `web` gate becomes deterministic against local source (no false positives from stale staging)
+- Workflow-product boundary preserved: visualBoard-specific paths live in repo config, not in `workflow/lib/*`
+- One dispatch surface (`integrate` area) reusable by CLI and future CI
+
+### Negative
+
+- Integration (`node workflow integrate`) wall-time increases by minutes for missions touching multiple areas
+- New config file (`config/integration-pipelines.json`) requires maintenance
+- Agents must learn a new area (`integrate`) and its opt-out flag (`--no-integration-gates`)
+
+## Deliverables
+
+1. **Repo-side config:** `config/integration-pipelines.json` with entries for `server`, `auth-server`, `web-client`, `web-e2e`; `web-e2e` carries `run_last: true`
+2. **Change detection:** Compute the set of top-level dirs touched by `mission/<slug>` vs the primary branch
+3. **Dispatch in `scripts/verify-local.sh`:** New `gate_integrate()` function and `integrate` area in the case statement
+4. **`node workflow integrate` preflight:** Calls the new `integrate` area as part of `printIntegrationPreflight`
+5. **`--no-integration-gates` flag:** Explicit opt-out for emergencies (Hard Rule #2 preserved)
+6. **`--dry-run` enhancement:** Prints the resolved gate plan (ordered list) and exits without executing
+7. **`gate_web()` fix:** Remove the `web:e2e` line (scripts/verify-local.sh:41)
+8. **Tests:** Unit tests in `scripts/test/` for change-detection, ordering, missing/empty config, command failure abort, dry-run
+9. **ADR update:** This document, added to `docs/adr/index.md`
+10. **Docs:** Update `AGENTS.md` Section 2 and `workflow/README.md`
+
+## See Also
+
+- ADR 0028: Integration review surface and CI posture
+- ADR 0039: Draft phase discipline and requirements language
+- task-1063: Workflow product extraction
+- task-1093: Originating incident (e2e tests broken)
+- `workflow/data/stats.csv`: Mission stats with `pr_fix_rounds`