@magnusekdahl/parallix 1.0.0

package/docs/adr/0045-parallax-branch-model.md

@@ -0,0 +1,182 @@
+# ADR 0045: parallix branch model and integration modes
+
+Status: Proposed
+Date: 2026-06-14
+
+## Context
+
+The parallix workflow manages mission branches (`mission/<slug>`) that agents create, develop on, and integrate back into a target branch. This branching model is implicit across multiple command handlers (`forgejo.js`, `draft.js`, `integrate.js`, `mission-start.js`, `mission-utils.js`, `rebase.js`) with no single authoritative reference. ADR 0043 established that local primary branches are the ancestry authority for workflow operations, but did not document the full branch lifecycle (draft → push → review → integrate → cleanup).
+
+Two distinct integration modes coexist in the codebase:
+1. Trunk-based: the mission branch integrates back into the repository's primary branch (`main` or `master`).
+2. Feature-branch: the mission branch integrates back into a recorded feature branch, with the base branch detected and persisted at draft time.
+
+Forgejo serves as a PR viewer and publication surface. The workflow does not require Forgejo to be configured as an upstream remote — all local branch operations (rebase, merge-base, integration) run against local branches. A dedicated `review` remote provides the push/fetch target for Forgejo synchronization.
+
+## Decision
+
+### Branch naming convention
+
+Mission branches use the prefix `mission/` followed by the task slug:
+
+```
+mission/<slug>   (e.g., mission/task-1280)
+```
+
+The prefix is configurable via the `missions.branchPrefix` adapter setting, defaulting to `mission/`. The naming is produced by `missionBranchName(slug)` and referenced throughout the workflow as the canonical mission branch identifier.
+
+Evidence: `parallix/lib/core/mission-utils.js:49-51`.
+
+### Base worktree naming convention
+
+Base feature-branch worktrees use a conventional path derived from the same `worktreePattern` used for mission worktrees. The base branch name is slug-sanitised (`/` → `-`) and prefixed with `base-`:
+
+```
+../<repo>-base-<sanitized-branch>
+```
+
+This ensures base worktrees are discoverable and removable with existing worktree tooling, and never collide with mission worktrees.
+
+Evidence: `parallix/lib/core/mission-utils.js:190-193`.
+
+### Integration mode 1: Trunk-based
+
+In trunk-based mode, the mission branch integrates back into the repository's primary branch (`main` or `master`). This is the default mode and covers every pre-existing mission.
+
+Lifecycle:
+
+1. **Draft**: `mission/<slug>` is created from the primary branch (`main`/`master`). No `Base-Branch:` line is written to MISSION.md because the base equals the primary.
+2. **Development**: Agents work on the mission branch in the mission worktree.
+3. **Rebase**: The mission branch is rebased onto the local primary branch (ADR 0043 local-first rule). The workflow may fetch `review/<primary>` for remote visibility but the rebase target is the local primary ref.
+4. **Integration**: The mission branch is squash-merged into the primary worktree on `main`/`master`. The integration runs Variant A (PR already merged on Forgejo, fast-path closeout) or Variant B (local squash-merge).
+
+Branch flow:
+
+```
+main ──────■──────────────────■── main (after squash-merge)
+           \                /
+            ■── mission/<slug> ─■
+```
+
+Evidence: `parallix/lib/core/mission-utils.js:318-325` (trunk delegation), `parallix/lib/commands/integrate.js:679-685` (integration resolution), `parallix/lib/commands/integrate.js:521-580` (squash-merge in primary worktree).
+
+### Integration mode 2: Feature-branch
+
+In feature-branch mode, the mission branch integrates back into a recorded feature branch. The base branch is detected at draft time, persisted in MISSION.md, and used throughout the mission lifecycle.
+
+Lifecycle:
+
+1. **Detect**: At draft time, `detectLaunchBaseBranch()` reads `git branch --show-current` to determine which branch HEAD is on. It refuses to nest missions on a `mission/*` branch and returns `null` when HEAD is detached (falling back to primary).
+2. **Record**: `ensureMissionBaseBranchRecorded()` writes a single `Base-Branch: <branch>` line into MISSION.md. This line is idempotent — a no-op when the base equals the primary, and re-asserted after the draft agent runs.
+3. **Create**: The mission branch `mission/<slug>` is created from the recorded base branch as its start point.
+4. **Development**: Agents work on the mission branch in the mission worktree.
+5. **Resolve**: `resolveMissionBaseBranch()` returns the recorded `Base-Branch:` value. `resolveBaseWorktree()` resolves or auto-creates the base worktree on the recorded branch.
+6. **Integration**: The mission branch is squash-merged into the **base worktree** on the recorded base branch (not the primary worktree). The integration runs Variant A or Variant B as with trunk mode.
+
+Branch flow:
+
+```
+feature ─■────────────────■── feature (after squash-merge)
+         \              /
+          ■── mission/<slug> ─■
+```
+
+Detection and recording evidence: `parallix/lib/core/mission-utils.js:207-223` (`detectLaunchBaseBranch`), `parallix/lib/commands/draft.js:327-352` (`ensureMissionBaseBranchRecorded`), `parallix/lib/commands/draft.js:316` (branch creation from base).
+
+Resolution evidence: `parallix/lib/core/mission-utils.js:239-287` (`readRecordedBaseBranch`, `resolveMissionBaseBranch`), `parallix/lib/core/mission-utils.js:318-350` (`resolveBaseWorktree`).
+
+Integration evidence: `parallix/lib/commands/integrate.js:679-685` (integration into base worktree), `parallix/lib/commands/integrate.js:521-580` (squash-merge in base worktree).
+
+Preflight guard evidence: `parallix/lib/commands/mission-start.js:158-188` (verifies base branch exists locally at mission start).
+
+### Forgejo role: PR viewer, not branch authority
+
+Forgejo is strictly a PR viewer and publication surface. The workflow does not require Forgejo to be configured as `origin` or any upstream remote.
+
+Key behaviors:
+
+- **`syncPrimaryBaseline()`**: Before PR creation, the workflow pushes the local primary branch to Forgejo's copy of `main`/`master` via an authenticated URL. This keeps the Forgejo review surface current.
+- **PR creation**: `createPr()` resolves the PR base (recorded feature base, else primary), syncs the primary baseline, pushes the mission branch via an authenticated one-off URL, and POSTs the PR with the resolved base.
+- **Bypassable**: When `isForgejoReviewEnabled` is `false`, all Forgejo sync paths in `integrate` and `rebase` are skipped. The workflow operates entirely on local branches and worktrees.
+
+Evidence: `parallix/lib/tools/forgejo.js:379-491` (`createPr`), `parallix/lib/tools/forgejo.js:696-717` (`syncPrimaryBaseline`), `parallix/lib/commands/integrate.js:537-549` and `:619-629` (Forgejo skip paths), `parallix/lib/core/product-config.js:434-436` (provider gate).
+
+### The `review` remote
+
+The `review` remote is a named git remote that serves as the push/fetch target for Forgejo synchronization. It is configured via `workflow.config.json` → `adapters.review.remote` (value `"review"` by default).
+
+Operations:
+
+- **Push**: `pushReviewRef()` executes `git push review <src>:<dst>` to push refs to the Forgejo-hosted repo.
+- **Fetch**: `fetchReviewBranch()` executes `git fetch review +refs/heads/<branch>:refs/remotes/review/<branch>`, or uses an authenticated URL when a token is supplied.
+- **Delete**: `deleteReviewRef()` removes refs from the review remote.
+- **Setup**: `setup-review.js` creates or updates the remote via `git remote add/set-url <remote> <url>`.
+
+The remote name is resolved from `adapters.review.remote || 'review'` via `resolveReviewAdapter()`.
+
+Evidence: `workflow.config.json:16`, `parallix/lib/core/product-config.js:423-430` (`resolveReviewAdapter`), `parallix/lib/tools/forgejo.js:719-741` (push/fetch), `:803-810` (delete), `parallix/lib/tools/setup-review.js:386-392`, `:215`, `:781`.
+
+### Rebase target (ADR 0043 invariant)
+
+The `rebase` command fetches `review/<primary>` for remote visibility updates but rebases the mission branch onto the **local** primary branch. This is the ADR 0043 local-first invariant, ensuring rebase and integrate use the same ancestry target.
+
+Evidence: `parallix/lib/commands/rebase.js:93-117`.
+
+## Decision matrix
+
+| Aspect | Trunk-based mode | Feature-branch mode |
+|--------|------------------|---------------------|
+| Mission branch | `mission/<slug>` | `mission/<slug>` |
+| Integration target | Primary `main`/`master` | Recorded `Base-Branch` |
+| Integration worktree | Primary worktree | Base worktree (`<repo>-base-<branch>`) |
+| Base detection | Implicit (primary) | Explicit (`detectLaunchBaseBranch`) |
+| Base persistence | No `Base-Branch:` line | `Base-Branch:` line in MISSION.md |
+| Default mode | Yes (all pre-existing missions) | No (opt-in via draft context) |
+| Preflight check | N/A | Verifies base branch exists locally |
+| Code path overlap | 80%+ (same integrate/rebase commands) | Branch resolution differs at `resolveMissionBaseBranch` |
+
+## Consequences
+
+### Positive
+
+- **Single source of truth**: The branch model is now documented with explicit file:line references, eliminating the need to trace through multiple command handlers to understand branch behavior.
+- **Forgejo is not a hard dependency**: The workflow can operate entirely offline (local rebase, local squash-merge) when Forgejo is unavailable or disabled.
+- **Feature-branch mode is explicit**: The documented flow clarifies how missions on feature branches integrate back, including the auto-creation of base worktrees.
+- **Backward compatible**: Every pre-existing mission follows the trunk-based path byte-identically, since `resolveMissionBaseBranch` falls back to `getPrimaryBranch()` when no `Base-Branch:` line exists.
+- **Preflight safety**: Mission-start verifies the base branch exists locally, preventing late integration failures.
+
+### Negative
+
+- **Base worktree management**: Feature-branch mode introduces a second worktree per mission (mission worktree + base worktree), increasing storage and checkout overhead.
+- **Stale base risk**: If the base branch is deleted or the base worktree becomes stale, `resolveBaseWorktree` throws an error rather than recovering gracefully.
+- **Documentation coupling**: Future code changes to branch resolution logic must update this ADR to stay accurate.
+
+### Open questions
+
+- What happens when the base worktree is removed externally (e.g., manual `git worktree remove`)? The current code auto-recreates it on the next integration attempt.
+- Does the workflow need a cleanup command for base worktrees, analogous to mission worktree removal?
+- Should `Base-Branch:` be cleared when a mission transitions from feature-branch to trunk-based mode?
+
+## Alternatives considered
+
+| Alternative | Description | Why rejected |
+|-------------|-------------|--------------|
+| Forgejo as upstream | Configure Forgejo as `origin` and derive all branch operations from it | Adds unnecessary network dependency; local-first model is simpler and more resilient |
+| Single integration mode | Support only trunk-based integration | Feature-branch mode is actively used and works correctly in code; documenting it prevents future confusion |
+| Remote-tracking as authority | Use `review/<primary>` as the rebase/integrate target | Causes split-brain between rebase and integrate (ADR 0043); stale remote refs produce incorrect ancestry |
+| Separate workflow for feature branches | Maintain a distinct workflow path for feature-branch missions | 80%+ code overlap; a unified flow with conditional base resolution is simpler and more maintainable |
+| Forgejo as PR author | Have Forgejo create PRs programmatically | Forgejo is sufficient as a viewer; PR creation via authenticated push + API POST achieves the same outcome without platform dependency |
+
+## Links
+
+- `parallix/lib/core/mission-utils.js` — branch naming, base detection/recording/resolution, worktree management
+- `parallix/lib/commands/draft.js` — mission branch creation, base branch recording
+- `parallix/lib/commands/integrate.js` — integration merge, variant selection, Forgejo sync
+- `parallix/lib/commands/rebase.js` — rebase target resolution, Forgejo visibility fetch
+- `parallix/lib/commands/mission-start.js` — preflight base-branch verification
+- `parallix/lib/tools/forgejo.js` — PR creation, primary baseline sync, review remote push/fetch/delete
+- `parallix/lib/tools/setup-review.js` — review remote setup
+- `parallix/lib/core/product-config.js` — review adapter resolution, provider gate
+- `parallix/lib/core/git.js` — low-level git CLI wrappers
+- `docs/adr/0043-git-target-resolution-strategy.md` — ADR 0043: local-first git target resolution
+- `parallix/config/workflow.config.schema.json` — workflow runtime configuration schema

package/docs/adr/0046-npm-publish-process-and-security.md

@@ -0,0 +1,138 @@
+# ADR 0046: parallix npm Registry Publication Process and Security Posture
+
+Status: Proposed | Accepted
+Date: 2026-06-23
+
+Related: ADR 0044 (Workflow Distribution Model), task-1340 (make parallix publishable)
+
+## Context
+
+ADR 0044 established the distribution stance as "local npm tarball, globally installed `px` CLI" and deferred concrete npm registry publication. parallix was pushed to public GitHub on 2026-06-22 (task-1322). The repo is now public and the operator wants a credible, secure, single-command install path before inviting external use.
+
+The package has zero runtime npm dependencies (Node.js builtins only), is distributed under AGPL-3.0-or-later, and uses `access: public` in `publishConfig`. The operator publishes manually — no CI/release automation is in scope. This ADR documents the decision to adopt public npm registry publication, the security posture that enables it, the authentication requirements, and the pre-publish verification process.
+
+The `@magnusekdahl` scope was verified available on the npm registry (task-1340 CP-0). `@magnusekdahl/parallix` returns 404, confirming the scoped name is unclaimed.
+
+## Decision
+
+**Adopt public npm registry publication for parallix as `@magnusekdahl/parallix`, alongside the existing local tarball install path.**
+
+The operator performs `npm publish` manually from a verified local checkout. The decision is bounded: no CI/release automation, no dist-tag management beyond the `latest` tag. The publish process is manual, repeatable, and documented here. Packages published to the public npm registry are automatically signed with ECDSA registry signatures — no publisher action required.
+
+### Authentication requirement
+
+Publishing scoped public packages to npm requires one of the following:
+
+- **Two-factor authentication (2FA)** enabled on the npm account, or
+- **A granular access token (GAT) with bypass 2FA enabled**
+
+Both options are documented in the npm docs for scoped public packages. The operator uses 2FA on their npm account for interactive publishing (`npm publish --access public`), which triggers an OTP prompt. This is the default and recommended approach for manual publishing.
+
+An alternative is staged publishing (`npm stage publish` followed by `npm stage approve`), which allows a CI workflow to submit a package to staging without 2FA, then requires 2FA only for the manual approval step. Since parallix has no CI automation, direct publishing is simpler and sufficient.
+
+### Security posture enabling this decision
+
+- **Zero runtime dependencies:** All functionality uses Node.js built-in modules (`fs`, `path`, `child_process`, `os`, `crypto`, `util`, `events`, `stream`, `buffer`, `assert`). This eliminates supply-chain attack surface from third-party packages.
+- **Explicit `files` allowlist:** `package.json` uses an explicit `files` array as an allowlist, not a blacklist. Test suites, coverage reports, knowledge graph output, session data, workflow caches, and Forgejo local state are all excluded.
+- **Defense-in-depth:** `.npmignore` provides a secondary exclusion layer. The combination ensures operator secrets (`*.local.json`), test fixtures, and development artifacts cannot reach the published tarball.
+- **`access: public` in `publishConfig`:** The package is declared public in the manifest. The `--access public` flag is also passed at publish time for explicitness.
+- **AGPL-3.0-or-later license:** The license ensures users can freely use, modify, and distribute parallix while triggering copyleft obligations on modifications to parallix itself.
+- **ECDSA registry signatures:** Every package published to the public npm registry is automatically signed with ECDSA signatures by the registry. This protects against tampering at registry mirrors or proxies. Consumers can verify with `npm audit signatures` (requires npm CLI ≥8.15.0). Signed packages are the npm industry standard — all major packages have them.
+
+### Operational procedures (derived from this decision)
+
+The following procedures are consequences of this decision, not decisions themselves:
+
+1. **Pre-publish verification:** `npm pack --dry-run` inspects the file listing before each publish. The operator verifies all exclusion patterns are absent.
+2. **Manual publish sequence:** Clean working tree → version check → `npm pack --dry-run` → `npm publish --access public` → verify → git tag.
+3. **Token security:** npm tokens are stored in `~/.npmrc` only, never committed. Fine-grained tokens with minimal permissions are used.
+4. **Content audit:** An automated grep script checks `npm pack --dry-run` output against known exclusion patterns.
+
+These procedures are operational guidance. They are subject to change as the operator gains experience with the publish process. They are not architectural decisions.
+
+## Decision matrix
+
+| Option | Summary | Benefits | Risks / Costs | Fit to constraints | Decision |
+|--------|---------|----------|---------------|--------------------|----------|
+| A: Public npm registry | One command: `npm install -g @magnusekdahl/parallix` | Shortest install; matches public repo expectations | Operator token risk managed by 2FA; npm permanence | Matches ADR 0044's zero-dependency stance; public repo warrants public install path | **Accept** |
+| B: Private npm scope first, then public | Same install after switch | Initial publish is invisible; allows verification | Two publish cycles; potential version confusion | No concrete security concern justifies extra step | Defer — only if a concrete security concern emerges |
+| C: Continue tarball-only | Two commands: `npm pack && npm install -g ./magnus-parallix-*.tgz` | Maximum operator control; no registry involvement | Higher friction; does not meet credibility bar for public repo | Consistent with ADR 0044 but inferior UX for public tool | Reject as primary — tarball remains a valid secondary path |
+| D: CI/CD automated publish | Fully automated pipeline | Repeatable; can include automated checks | CI credential risk; infrastructure to maintain; out of scope | Operator explicitly requested manual publish | Reject for now — revisit when cadence justifies automation |
+
+## Consequences
+
+### Positive consequences
+
+- **Credible public install path:** Users can install with `npm install -g @magnusekdahl/parallix` — the shortest possible install, matching expectations for a public Node tool.
+- **Tarball path preserved:** Local tarball install (`npm pack && npm install -g ./magnus-parallix-*.tgz`) remains valid and documented. Operators who prefer it can continue using it.
+- **Supply-chain transparency:** Zero dependencies means `npm audit --production` reports zero vulnerabilities. No hidden third-party code to vet.
+- **Manual publish discipline:** The operator's hands-on publish process is a feature, not a bug — it forces a deliberate verification step before every release.
+- **Rollback awareness:** The ADR documents npm's unpublish constraints (72-hour window for unpublishing; deprecation for older versions) and provides mitigation strategies (conservative semver, version bumping).
+
+### Negative consequences
+
+- **npm permanence:** Once published, a version cannot be unpublished if >72 hours old or if it has more than 3 dependents. Beyond that window, deprecation is the only option. Prevention (careful `npm pack --dry-run`) is the only reliable rollback.
+- **Operator token responsibility:** The operator manages npm tokens, 2FA, rotation, and scope. This is a single point of operational risk.
+- **Namespace reservation:** The `@magnusekdahl` scope is now associated with a published package. If the operator abandons parallix, the scope becomes orphaned on npm.
+- **Scope creep risk:** Documenting the publish process here invites future requests to add CI automation, npm provenance (Sigstore), or dist-tag management. These are separate decisions that require their own ADRs.
+- **No version pinning guarantee:** Users installing with `npm install -g @magnusekdahl/parallix` get `latest`. Without a lockfile or version specifier, they may receive unexpected updates.
+
+## Alternatives considered
+
+### Private registry publication first (Option B in matrix)
+
+Positive: Initial publish is invisible to the public; allows verification of the package without exposing it to accidental installs.
+
+Negative: Requires two publish cycles (restricted → public). Adds confusion about which version is "the" published version. No concrete security concern justifies the extra step.
+
+Assessment: Defer until a specific threat scenario emerges that makes a private-first publish worthwhile.
+
+### Continue tarball-only distribution (Option C in matrix)
+
+Positive: Maximum operator control. No registry involvement. Consistent with ADR 0044's current stance.
+
+Negative: Does not meet the credibility bar for a public repo. Two-command install is friction compared to one-command expectation. External contributors cannot easily test the published package.
+
+Assessment: Tarball remains a valid secondary install path for operators who prefer it, but should not be the primary documented path for a public tool.
+
+### CI/CD automated publish (Option D in matrix)
+
+Positive: Eliminates manual steps. Consistent publish process. Can include automated checks (audit, pack verification) in the pipeline.
+
+Negative: Introduces CI credential management. Adds infrastructure to maintain. Out of scope for the operator's stated preference for manual publish.
+
+Assessment: Revisit when publication cadence justifies automation (e.g., frequent patch releases, multiple maintainers).
+
+### Staged publishing
+
+Positive: Allows CI workflows to submit packages to staging without 2FA; requires 2FA only for manual approval. Provides an intermediate review step.
+
+Negative: Adds complexity for a solo-maintainer project with no CI. The operator's manual publish sequence already includes a verification step (`npm pack --dry-run`).
+
+Assessment: Not needed for current workflow. Can be adopted later if CI is introduced or if the operator wants an extra review gate.
+
+### Scoped package name alternatives
+
+Positive: Alternative scopes (`@parallix/parallix`, `@px-cli/parallix`) would decouple the package from the operator's personal npm identity.
+
+Negative: `@magnusekdahl` scope is confirmed available and unclaimed. The operator is the sole maintainer. An organizational scope would require creating a new npm org, which is unnecessary overhead.
+
+Assessment: `@magnusekdahl/parallix` is the correct scope for a solo-maintainer package. Revisit if a team or organization assumes maintenance.
+
+## Links
+
+- ADR 0044: Workflow Distribution Model — established the local npm tarball / global `px` install stance; deferred registry publication
+- ADR 0037: AI Workflow Coordination Architecture — established the `workflow/` directory as the coordination CLI
+- task-1340: make parallix publishable — this ADR's originating task
+- task-1340 CP-0: npm scope availability verified
+- `package.json` — package metadata, `files` allowlist, `publishConfig.access`
+- `parallix/.npmignore` — secondary exclusion layer
+- npm docs: Creating and publishing scoped public packages — https://docs.npmjs.com/creating-and-publishing-scoped-public-packages
+- npm docs: Unpublishing packages from the registry — https://docs.npmjs.com/unpublishing-packages-from-the-registry
+- npm docs: Requiring 2FA for package publishing — https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification
+- npm docs: Staged publishing — https://docs.npmjs.com/staged-publishing
+- npm docs: About ECDSA registry signatures — https://docs.npmjs.com/about-registry-signatures
+- npm docs: Verifying ECDSA registry signatures — https://docs.npmjs.com/verifying-registry-signatures
+- npm docs: Threats and Mitigations — https://docs.npmjs.com/threats-and-mitigations
+
+(End of file - total 130 lines)

package/docs/adr/index.md

@@ -0,0 +1,20 @@
+# Architecture Decision Records (ADRs)
+
+This repository carries the parallix-owned ADRs migrated out of WrGroceries.
+ADR 0023 remains in WrGroceries and is cross-referenced here instead of copied.
+
+## Index
+- `docs/adr/0031-ai-agent-instruction-boundary-and-command-floor.md` — Workflow-security decision: classify authoritative instruction sources explicitly and accept a bounded autonomy tradeoff for broader Claude local scripting
+- `docs/adr/0032-mission-refinement-state-and-usage-budget-signals.md` — Add `refined` as the pre-activation mission state and keep `% usage limit` selection signals in `MISSION.md`
+- `docs/adr/0034-module-and-skill-invocation-model.md` — Module/skill invocation model: phase-bound baseline, explicit rule-based self-invocation, and mandatory validation-module loading
+- `docs/adr/0036-mission-sizing-and-dependency-wave-heuristics.md` — Mission sizing tracks, "Too Large" thresholds, and dependency-wave heuristics
+- `docs/adr/0037-ai-workflow-coordination-architecture.md` — Node.js `workflow/` package as repo-adapted coordination CLI for startup, checkpoint, and session handoff; replaces agent-followed documented procedures
+- `docs/adr/0041-integration-pipeline-gates.md` — Integration-time pipeline gates + per-area gate dehallucination: add staging-deploy + e2e gates before squash-merge, driven by repo-side config; remove hallucinated stage-e2e from `gate_web`
+- `docs/adr/0042-workflow-cli-color-rendering-approach.md` — Replace hand-rolled ANSI palette and buggy `useColor()` with Node.js built-in `util.styleText`; zero-dep color detection that handles NO_COLOR/FORCE_COLOR/TERM/TTY correctly
+- `docs/adr/0043-git-target-resolution-strategy.md` — Local-first git target resolution for workflow branch ancestry, with explicit invariants that keep rebase and integrate aligned
+- `docs/adr/0044-workflow-distribution-model.md` — parallix productization path with `px` naming, runtime/target-state boundary, and a 5-alternative decision matrix; Accepted (2026-06-22, task-1331) on the near-term local npm tarball / global `px` install stance
+- `docs/adr/0045-parallax-branch-model.md` — Two integration modes (trunk-based and feature-branch), Forgejo as PR viewer only, `review` remote wiring, and branch naming conventions
+- `docs/adr/0046-npm-publish-process-and-security.md` — Adopt public npm registry publication for `@magnusekdahl/parallix` alongside the local tarball path; zero-dependency security posture, manual publish process, and rollback considerations
+
+## Cross-reference
+- `docs/adr/0023-ai-sdlc-configuration.md` remains in WrGroceries at `/home/magnus/code/visualBoard-task-1302/docs/adr/0023-ai-sdlc-configuration.md`.

package/docs/agents.md

@@ -0,0 +1,212 @@
+# parallix Agent Launcher — Supported Matrix and Policy
+
+## Supported Agent Families (this workstation, 2026-04-11)
+
+| Agent   | Launcher |
+|---------|----------|
+| codex   | `codex` |
+| claude  | `claude` |
+| mistral | `vibe` |
+| qwen    | `opencode` |
+
+All four listed launchers are supported on this workstation. Step eligibility for all workflow steps (`draft`, `active`, `conflict-resolution`, `review`) is controlled by `parallix/config/agents.json`. If a launcher is missing from `PATH`, the harness fails loudly with the exact blocker before launching.
+
+## Tool Calling Workaround (qwen/opencode)
+
+Opencode (qwen agent family) may encounter issues with concurrent tool calls or tool call timeouts during long-running workflow sessions. When working with opencode:
+
+- **Prefer sequential tool calls** over parallel calls for dependent operations — if tool B needs output from tool A, call them separately.
+- **Use `workdir` parameter instead of `cd` chains** — avoid `cd <dir> && command` patterns; always use `workdir` for directory changes.
+- **Keep bash commands simple** — prefer separate simple commands over complex one-liners with pipes and conditionals.
+- **If a tool call times out or returns empty**, retry once before escalating.
+
+## Non-interactive invocation shapes
+
+| Agent   | Invocation shape                                                     |
+|---------|----------------------------------------------------------------------|
+| codex   | `codex exec --sandbox danger-full-access --cd <worktree> <prompt>` with a worktree-local `HOME` under `.workflow/codex-home`; resume uses `codex exec resume <session-id-or---last> <prompt>`; the launcher also seeds `.workflow/codex-home/.codex/config.toml` with the repo-standard trusted posture and copies `.codex/auth.json` so headless review commands can start and keep localhost Forgejo access |
+| claude  | `claude --dangerously-skip-permissions --output-format stream-json --verbose --include-partial-messages -p <prompt>` (cwd=worktree) — uses `--output-format stream-json --verbose --include-partial-messages` to stream real-time JSONL events (tool calls, assistant text chunks) to the operator's terminal via the spawn-tee mechanism. `--include-partial-messages` is required: without it, the assistant event contains the full response at once and no intermediate progress is emitted. Session-id extraction parses the `result` event from stream-json output, falling back to the `claude --resume <id>` regex on plain text. |
+| mistral | `vibe --prompt <prompt> --trust --output text` (cwd=worktree) — **Note: NOT resume-capable in current Vibe version**; session management uses internal state in `~/.vibe/logs/session/` but does not emit a parseable resume hint to stdout/stderr. |
+| qwen    | `opencode run --pure --dangerously-skip-permissions <prompt>` (cwd=worktree); resume uses `-s <session>` when a session id is known or `--continue` when only the family marker is known |
+
+## Launch output watchdog
+
+All workflow agent launches use the shared `startAgent` path and tee child stdout/stderr through the parent terminal. If the child process stays running but produces no stdout or stderr, the harness emits a bounded status line after a configurable delay and then once per that interval until output arrives or the process exits.
+
+### Default watchdog timings
+
+| Step | Initial delay |Interval |
+|------|--------------|----------|
+| `draft` | 15 seconds | 30 seconds |
+| All other steps | 60 seconds | 60 seconds |
+
+Draft uses shorter defaults so the operator can distinguish agent startup from a hang more quickly during the mission entrypoint (see `DRAFT_NO_OUTPUT_INITIAL_DELAY_MS` and `DRAFT_NO_OUTPUT_INTERVAL_MS` in `parallix/lib/agents/agents.js:54-55`). Other steps retain the generic 60-second defaults (`DEFAULT_NO_OUTPUT_INITIAL_DELAY_MS` and `DEFAULT_NO_OUTPUT_INTERVAL_MS` at `parallix/lib/agents/agents.js:52-53`).
+
+### Override environment variables
+
+Per-step timing can be overridden via environment variables:
+
+| Variable | Applies to | Default effect |
+|----------|-----------|----------------|
+| `WORKFLOW_AGENT_NO_OUTPUT_INITIAL_MS` / `WORKFLOW_AGENT_NO_OUTPUT_INTERVAL_MS` | All steps | Fallback generic watchdog |
+| `WORKFLOW_DRAFT_AGENT_NO_OUTPUT_INITIAL_MS` / `WORKFLOW_DRAFT_AGENT_NO_OUTPUT_INTERVAL_MS` | `draft` step only | Overrides the 15s/30s draft defaults |
+
+Set `WORKFLOW_AGENT_NO_OUTPUT_WATCHDOG=0` to disable the watchdog entirely for a single command when investigating output interleaving.
+
+Passing explicit `noOutputWatchdog: { initialDelayMs, intervalMs }` to `startAgent` bypasses both the env vars and the step defaults.
+
+### Watchdog message format
+
+When the watchdog fires, the harness emits:
+
+```text
+[INFO] No output yet from <agent> for step "<step>" after <elapsed> (pid <pid>, agent <stage>). Launcher is still running; stdout/stderr have not produced visible output.
+```
+
+The `<stage>` field is `"starting up"` when fewer than the step-specific initial delay have elapsed, and `"running"` once that threshold is crossed (`agents.js:736-738`). For draft, the threshold is 15 seconds; for all other steps it is 60 seconds.
+
+This means the launcher process is alive but silent. It is not a launch failure by itself. A launch failure is still reported separately when the process cannot start, exits non-zero, is killed by a signal, or produces a detected usage-limit transcript that triggers fallback.
+
+## Per-step eligibility policy
+
+Eligibility is controlled by `parallix/config/agents.json`. The default config controls which agents are eligible for each step:
+
+```json
+{
+  "steps": {
+    "draft": { "eligible": ["codex", "qwen", "mistral"], "selection": "random" },
+    "active": { "eligible": ["codex", "claude", "qwen", "mistral"], "selection": "random" },
+    "conflict-resolution": { "eligible": ["claude", "codex", "mistral"], "selection": "random" },
+    "review": { "eligible": ["codex", "claude", "qwen", "mistral"], "selection": "random" }
+  }
+}
+```
+
+Note: these examples match the actual `parallix/config/agents.json` that controls eligibility at runtime. The executable config is the source of truth; any mismatch between the docs and the config is a bug.
+
+To restrict a step to a specific agent, edit the `eligible` array. To force a specific agent for the current command invocation, use the CLI flags:
+
+```sh
+px draft task-XXX --agent codex
+px active task-XXX --implementer claude
+```
+
+CLI flags (`--agent`, `--implementer`) take precedence over both the config and random selection. They are the preferred mechanism for operator override. As a fallback, the `WORKFLOW_AGENT` environment variable is also supported:
+
+```sh
+WORKFLOW_AGENT=codex px draft task-XXX
+WORKFLOW_AGENT=claude px active task-XXX
+```
+
+## Local blocklist overrides
+
+Temporary local blocking uses the operator-owned
+`<PARALLIX_HOME>/agents.local.json`. `PARALLIX_HOME` is the highest-priority
+whole-root override. Platform defaults are `~/.local/state/parallix` on Linux,
+`~/Library/Application Support/parallix` on macOS, and `%LOCALAPPDATA%\parallix`
+on Windows, with `~/.parallix` as the fallback.
+
+On first use, if the effective file is absent, parallix migrates these legacy
+locations in order, with later values taking precedence:
+
+1. `parallix/config/agents.local.json`
+2. repo-root `agents.local.json`
+3. main-worktree `agents.local.json`
+
+Migration never deletes a legacy file. Conflicting values are logged with the
+selected and previous source/value. Malformed legacy files are reported and
+skipped; malformed effective JSON is a hard failure and is left byte-unchanged.
+
+Supported shape:
+
+```json
+{
+  "blocklist": {
+    "claude": { "until": "2026-05-02 09" },
+    "codex": { "blocked": false }
+  }
+}
+```
+
+Per-agent values:
+- `true` or `{ "blocked": true }`: permanently blocked
+- `false` or `{ "blocked": false }`: explicitly unblocked
+- `{ "until": "YYYY-MM-DD HH" }`: blocked until that local-machine hour passes
+
+Malformed workflow or local agent JSON is a hard failure with the file path and parse error. Blocked agents are removed before launcher probing and random selection.
+
+## Usage-limit handling — automatic fallback (TASK-1013)
+
+The workflow detects limit-hit messages in agent stdout/stderr and automatically reroutes to another eligible agent.
+
+### Detection
+
+`parallix/lib/limit-hit.js` ships a regex catalog per agent family (`claude`, `codex`, `qwen`, `mistral`) covering the common shapes:
+- explicit phrases like `Claude usage limit reached`, `weekly limit`, `Quota exceeded`, `RESOURCE_EXHAUSTED`
+- HTTP signals (`429 Too Many Requests`, `rate_limit_exceeded`, `Retry-After: ...`)
+
+When a pattern matches, the parser also tries to extract a reset timestamp from the surrounding context:
+1. ISO 8601 (`2026-05-01T15:30:00+00:00`)
+2. 12-hour clock (`5pm`, `5:30 PM`) projected onto today/tomorrow
+3. 24-hour clock (`17:00`)
+4. Relative (`in 3 hours`)
+5. `Retry-After: <n>` seconds/minutes
+
+If extraction fails, the harness falls back to a 1-hour block. The result is rounded **up** to the next full hour and written as `YYYY-MM-DD HH` (the format `agents.local.json` already understands).
+
+### Persistence
+
+`updateAgentBlock(agent, until)` writes the timed entry to
+`<PARALLIX_HOME>/agents.local.json`. Automatically persisted usage-limit blocks
+therefore apply across every target repository driven by the same parallix
+installation. Parent directories and a valid `{"blocklist": {}}` shape are
+created on first write.
+
+If the target file is already malformed (invalid JSON or a non-object root), `updateAgentBlock` raises a `WORKFLOW_AGENT_CONFIG_INVALID` error with the file path and original parse error and leaves the file untouched, matching the read-path contract. A limit hit must never silently overwrite a corrupted blocklist.
+
+### Retry loop
+
+`startAgent(step, opts)` is now async. It:
+1. Picks an agent (honoring `WORKFLOW_AGENT`, the eligibility config, and the existing blocklist).
+2. Spawns the launcher with a tee — output is mirrored to the user's terminal **and** captured to a bounded in-memory tail buffer (`DEFAULT_MAX_TAIL_BYTES`, currently 64 KiB per stream). Long-running, noisy agents cannot turn the harness into an `O(total output)` memory hog.
+3. Runs `detectLimitHit` on the captured tail **only when the launcher actually failed** (non-zero exit, signal, or spawn error). A successful child run is never treated as a limit hit, even if the transcript happens to quote a phrase like "rate limit reached" — that path is the false-positive case where an agent reviews code, tests, or logs containing those strings.
+4. On a hit, persists the block, records the agent as tried, and reselects from the remaining eligible+supported pool.
+5. If every eligible agent hits a limit, the harness throws a clear "all eligible agents exhausted" error rather than silently retrying forever.
+
+When the autonomous review loop rewrites `review-state.json` after a fallback (see `applyAgentFallback` in `parallix/lib/review/review.js`), it preserves the original `roundStartedAt` rather than stamping the rewrite time. Polling for the round's reviewer/disposition outcome uses `roundStartedAt` as the lower bound, so a crash between the fallback rewrite and pollFor* completing must not advance that bound past comments the fallback agent has already posted.
+
+`WORKFLOW_AGENT` overrides survive their first attempt; if the pinned agent itself hits a limit, the retry falls back to normal selection (excluding the blocked one). A `WORKFLOW_AGENT` value that is already hard-blocked in `agents.local.json` (or excluded by step eligibility) is ignored at selection time and the harness falls back to the regular pool — overrides are honored *alongside* the blocklist, never *around* it.
+
+The same rule applies to explicit `agent:` overrides passed into `startAgent({ agent })` — for example, the reviewer/implementer identities the autonomous review loop carries over from `review-state.json`. Before launching, `startAgent` consults the merged blocklist; if the pinned agent is currently blocked, it logs a warning, adds it to the tried-set, and reroutes through `selectAgent` instead of wasting a retry on a known-limited family.
+
+### Active-step Backlog state-ordering contract
+
+`px active` enforces this state order:
+
+```
+selectAgent (blocklist applied) → startAgent (launch) → record Backlog (status=active, assignee)
+```
+
+The Backlog task is moved to `active` with the correct implementer **only after** the launch exits cleanly (status 0, no error). A failed or exhausted launch leaves the task in its prior Backlog state — it does not record a wrong implementer or a misleading `active` status.
+
+When `startAgent` falls back to a different agent family after a limit hit, the Backlog records the fallback family (the agent that actually ran), not the originally preselected one.
+
+### Automatic post-execute handoff repair (TASK-1037)
+
+The workflow harness automatically recovers from routine handoff hygiene issues after a successful execute-agent exit. When `px active <slug>` completes its execution phase, it attempts automated handoff. If handoff fails, the harness runs a repair step and retries exactly once before declaring failure.
+
+#### Repaired conditions:
+1. **Uncommitted mission artifacts**: If the worktree is dirty but only mission-owned files (the configured mission base dir for the repo, `backlog/tasks/<slug> - *`, or `backlog/completed/<slug> - *`) are modified, the harness automatically commits them with a deterministic message: `workflow(<slug>): auto-commit mission artifacts before handoff`.
+2. **Branch behind primary branch (main)**: If the handoff fails because the branch is behind its remote (non-fast-forward), the harness automatically invokes `px rebase <slug>`.
+
+#### Hard blockers:
+Automatic repair is refused and the harness stops if:
+- Dirty files include paths outside the mission-owned set.
+- Rebase requires manual conflict resolution or agent assistance for shared files.
+- Handoff fails for non-hygiene reasons (missing checkpoints, missing `## Goal Check` evidence, failed verification gates).
+
+### Manual override is still supported
+
+- `WORKFLOW_AGENT=<name>` — pin a specific agent for the next run.
+- `parallix/config/agents.json` — restrict step eligibility.
+- Edit `<PARALLIX_HOME>/agents.local.json` by hand to add or clear blocks; format remains `{"blocklist": {"agent": {"until": "YYYY-MM-DD HH"}}}`. Back up `PARALLIX_HOME` separately from target repositories and npm package backups.