forge-workflow 0.0.9 → 0.1.0-beta.2

package/docs/reference/VALIDATION.md

@@ -0,0 +1,82 @@
+# Validation Reference
+
+Forge validation is evidence, not a slogan. Record the command, result, and failure text when validation fails.
+
+## Project Validation
+
+In this repository:
+
+```bash
+bun run check
+```
+
+`bun run check` runs `scripts/validate.js` in this order:
+
+1. `bun run typecheck`
+2. `bun run lint`
+3. `bun audit`
+4. `node scripts/test.js --validate`
+
+Security audit behavior distinguishes blocking high/critical vulnerabilities from lower-severity warnings.
+
+## Supporting Commands
+
+```bash
+bun run typecheck
+bun run lint
+bun test --timeout 15000
+bun run validate:yaml
+npm pack --dry-run
+```
+
+Use `npm pack --dry-run` for package contents and release-readiness checks. It does not publish.
+
+## Agent Stage Validation
+
+`/validate` is an agent workflow stage. It may include rebase/freshness checks, local validation, manual security review, and Beads context updates according to the installed stage instructions.
+
+Do not confuse:
+
+- `/validate` - agent stage workflow
+- `forge-preflight` - prerequisite checker
+- `bun run check` - repository validation script
+
+## Work Artifact Paths
+
+Current planning and validation evidence should point to:
+
+```text
+docs/work/YYYY-MM-DD-<slug>/
+```
+
+Legacy `docs/research/` or `docs/plans/` examples are historical unless a specific tool documents a compatibility fallback.
+
+## Failure Recovery
+
+Fix failures in order:
+
+1. Typecheck
+2. Lint
+3. Security audit
+4. Tests
+5. Packaging
+
+For each failure:
+
+1. Reproduce with the exact command.
+2. Read the first real error.
+3. Fix the root cause.
+4. Rerun the full validation command.
+
+Do not proceed to ship with "should pass" or stale output.
+
+## Documentation Changes
+
+For docs-only changes, still run:
+
+```bash
+bun run check
+npm pack --dry-run
+```
+
+Run a Markdown link check when available. If adding docs tooling would broaden the PR, file follow-up work instead.

package/docs/reference/agent-permissions.md

@@ -0,0 +1,169 @@
+# Research: Per-Agent Permissions Configuration
+
+> Historical research artifact. Do not treat this page as current setup behavior or current permission defaults. Current user-facing setup guidance lives in [Setup Guide](../guides/SETUP.md), and current skills/command packaging boundaries live in [Skills and command projections](SKILLS.md).
+
+**Feature slug**: `agent-permissions`
+**Beads issue**: forge-bo2
+**Date**: 2026-02-24
+
+---
+
+## Objective
+
+Every AI agent supported by Forge has its own permission/auto-approval system for terminal commands and file operations. Currently Forge ships no default permission config for any agent, meaning developers hit approval prompts constantly for safe, routine commands (git status, ls, bun run, bd list, etc.).
+
+**Goal**: Ship project-level permission config files for all supported agents so that safe commands auto-run out of the box, while destructive commands still require explicit approval.
+
+---
+
+## Codebase Analysis
+
+### What already exists
+
+| File | Agent | Status |
+| ---- | ----- | ------ |
+| `AGENTS.md` | Universal | ✅ Exists — workflow instructions only |
+| `docs/SETUP.md` | All agents | ✅ Exists (635 lines) — no permissions section |
+| `lib/agents/*.plugin.json` | 11 agents | ✅ All 11 plugin definitions exist |
+| `.claude/settings.json` | Claude Code | ✅ Exists — project-level permissions present |
+| `opencode.json` | Kilo/OpenCode | ❌ Missing |
+| `.codex/config.toml` | Codex CLI | ❌ Missing |
+| `.cursor/rules/permissions-guidance.mdc` | Cursor | ❌ Missing |
+
+### Affected files
+
+- `docs/SETUP.md` — add permissions section
+- `opencode.json` — new file at project root
+- `.codex/config.toml` — new file (directory must be created)
+- `.cursor/rules/permissions-guidance.mdc` — new file (directory must be created)
+
+### Integration points
+
+- `docs/SETUP.md` has per-agent sections — permissions guidance slots naturally into each agent's section
+- `.cursor/rules/` is referenced in `cursor.plugin.json` — adding a `.mdc` file there fits the existing pattern
+- The `forge setup` command will need to be updated separately to copy these files to new projects (separate issue)
+
+---
+
+## Research Findings
+
+### Agent Permission System Comparison
+
+#### Claude Code — `.claude/settings.json`
+- **Format**: JSON, `permissions.allow` array
+- **Syntax**: `"Bash(git status:*)"` — command prefix with wildcard
+- **Scope**: Project-level (committed) + global (`~/.claude/settings.json`) + local (gitignored)
+- **Granularity**: Per-tool (Bash, Read, Edit, WebFetch, Skill, Task, MCP)
+- **Evaluation**: First match in allow/deny wins
+- **Status**: Already configured in this project's `.claude/settings.json`
+
+#### Kilo Code + OpenCode — `opencode.json` (shared format)
+- **Format**: JSON, `permission` object with nested patterns
+- **Syntax**: `"git status *": "allow"` inside `bash` block
+- **Scope**: Project root (project-level) OR `~/.config/kilo/opencode.json` (global)
+- **Granularity**: bash, edit, external_directory, MCP, browser
+- **Evaluation**: **Last matching rule wins** — put deny rules at the bottom
+- **States**: `"allow"`, `"ask"`, `"deny"`
+- **Sources**: [Kilo Code docs](https://kilo.ai/docs/features/auto-approving-actions), [OpenCode docs](https://opencode.ai/docs/permissions/)
+
+#### OpenAI Codex CLI — `.codex/config.toml`
+- **Format**: TOML
+- **Syntax**: `approval_policy = "on-request"` + `sandbox_mode = "workspace-write"`
+- **Scope**: `.codex/config.toml` (project) OR `~/.codex/config.toml` (global)
+- **Granularity**: Policy-level (untrusted/on-request/never) + sandbox restrictions
+- **States**: `untrusted` (approve all), `on-request` (agent decides), `never` (no prompts)
+- **Best default**: `on-request` — agent uses built-in risk model, only asks when uncertain
+- **Also supports**: `--full-auto` flag and `--yolo` (dangerous bypass)
+- **Sources**: [Codex CLI config reference](https://developers.openai.com/codex/config-reference/)
+
+#### Cursor — IDE Settings (YOLO Mode)
+- **Format**: UI-only — configured in Cursor Settings > Features > Chat & Composer
+- **Syntax**: `Bash(git status *)` in allow/deny lists (same format as Claude Code)
+- **Scope**: IDE-level, not version-controlled — cannot be shipped as project file
+- **Granularity**: Fine-grained per-command allow/deny lists
+- **Approach for Forge**: Document recommended settings in `.cursor/rules/permissions-guidance.mdc`
+- **Sources**: Cursor Settings UI
+
+### Risk-Based Command Classification
+
+| Risk Level | Commands | Default action |
+| ---------- | -------- | -------------- |
+| **Safe (read-only)** | git status/log/diff/branch, ls, cat, grep, find, pwd, which, bd list/show/stats | `allow` |
+| **Safe (local write, reversible)** | git add, git commit, git stash, git checkout, bun/npm run, mkdir, touch, cp, mv | `allow` |
+| **Medium (remote-affecting)** | git push, gh pr create, gh issue create | `allow` (intentional dev action) |
+| **Careful (needs attention)** | git reset --hard, git rebase | `ask` |
+| **Dangerous (destructive)** | rm -rf, git push --force, drop database | `deny` |
+
+### Key Design Decisions
+
+**Decision 1: Include `git push:*` in allow list**
+- Reasoning: Developers push intentionally, constant prompting breaks flow
+- Evidence: Volleyball project already allows it in settings.local.json
+- Alternative: Keep as `ask` (rejected — too much friction for normal PRs)
+
+**Decision 2: `on-request` not `never` for Codex CLI**
+- Reasoning: `never` skips ALL prompts including network access and external edits; `on-request` lets the agent's risk model handle edge cases
+- Evidence: Codex docs recommend `on-request` for interactive development
+- Alternative: `never` for power users (can be documented as option)
+
+**Decision 3: Documentation-only for Cursor**
+- Reasoning: Cursor permissions are IDE-level settings, not project files — nothing to commit
+- Evidence: No `settings.json`-like project file exists for Cursor
+- Alternative: None — this is a platform limitation
+
+---
+
+## TDD Test Scenarios
+
+Since these are config files (not code), traditional unit tests don't apply. Verification is manual:
+
+1. **opencode.json validity** — JSON parses without errors; `git status` and `bd list` run without prompt in Kilo Code or OpenCode
+2. **.codex/config.toml validity** — TOML parses correctly; Codex CLI reads file at startup
+3. **.cursor/rules/ presence** — File appears in Cursor's Rules panel; content is accurate
+4. **docs/SETUP.md section** — Section is readable, links work, global config snippet is copy-pasteable and correct
+
+---
+
+## Security Analysis
+
+### OWASP Top 10 Relevance
+
+| Risk | Relevance | Mitigation |
+| ---- | --------- | ---------- |
+| **A01 Broken Access Control** | Medium — overly broad allow lists could let agents run unintended commands | Explicit deny rules for `rm -rf`, `git push --force`, `git reset --hard` |
+| **A05 Security Misconfiguration** | Medium — shipping overly permissive defaults would be misconfigured | Conservative defaults: `approval_policy = "on-request"` |
+| **A09 Security Logging** | Low — agent commands aren't logged by these configs | Mitigated by git history and Beads tracking |
+
+### Agent-Specific Security Notes
+
+- **opencode.json**: Deny rules must be at the bottom (last match wins) — putting them first would be ineffective
+- **Codex CLI**: `sandbox_mode = "workspace-write"` prevents file access outside project root — keep this
+- **Never ship**: `--dangerously-bypass-approvals-and-sandbox` (Codex) or global `"*": "allow"` (opencode.json)
+
+---
+
+## Scope Assessment
+
+**Type**: Tactical (config files + docs update, no business logic)
+**Complexity**: Low — all config formats researched, no code changes needed
+**Parallelization**: All 3 config files can be created simultaneously; docs/SETUP.md update is sequential after
+**Estimated files**: 4 new files, 1 modified
+
+**Branch**: `feat/agent-permissions`
+
+---
+
+## Sources
+
+- [Kilo Code - Auto-Approving Actions](https://kilo.ai/docs/features/auto-approving-actions)
+- [OpenCode - Permissions](https://opencode.ai/docs/permissions/)
+- [Codex CLI - Config Reference](https://developers.openai.com/codex/config-reference/)
+- Forge project codebase analysis (2026-02-24)
+
+---
+
+## Next Step
+
+```bash
+/plan agent-permissions
+```

package/docs/reference/beads-to-kernel-migration-ux.md

@@ -0,0 +1,61 @@
+# Beads To Kernel Migration UX
+
+**Status**: 0.0.20 migration reference for Forge Kernel authority rollout.
+
+**Related work**:
+
+- PR A / `forge-2agy.2.1`: Kernel schema, migrations, and storage classifier.
+- PR B / `forge-2agy.2.2`: Local SQLite WAL broker and command API contract.
+- PR C / `forge-2agy.2.3`: Beads import/export adapter and fidelity report.
+- PR D / `forge-2agy.2.4`: Conflict quarantine, idempotency, and evaluator fixtures.
+- PR E / `forge-2agy.2.5`: Documentation and migration UX.
+
+## User-Facing Position
+
+Forge Kernel is the target issue authority. Beads remains compatibility input/output during the migration window so existing repositories can inspect, import, export, and recover issue state without treating `.beads` files as the new source of truth.
+
+The migration UX should make three boundaries visible:
+
+1. Import reads Beads state and creates Kernel-shaped records.
+2. Export projects Kernel records back to Beads-compatible JSONL.
+3. Projection failure does not invalidate Kernel authority.
+
+## Current Compatibility
+
+The Beads compatibility adapter is import/export only. It preserves issue IDs, statuses, priorities, parent-child dependencies, blockers, comments, close reasons, available timestamps, and fidelity counts where the current Beads projection exposes them.
+
+Known compatibility gaps are explicit. Kernel schema v1 does not directly preserve every Beads field as first-class issue columns, so unsupported or non-authoritative fields must appear in the fidelity report rather than silently becoming Kernel authority.
+
+## Recommended Operator Flow
+
+1. Snapshot or back up the current Beads projection before migration.
+2. Run import and review the fidelity report.
+3. Keep export in dry-run mode until record counts, dependency edges, comments, close metadata, and unsupported-field gaps are understood.
+4. If export writes are enabled, capture rollback snapshots for the Beads projection files before writing.
+5. Treat any conflict or stale projection warning as a stop point until the quarantine report is reviewed.
+
+## Rollback Boundaries
+
+Import rollback is discard-only when import has not committed authoritative Kernel mutations. Discard the imported Kernel-shaped records and keep the original Beads projection unchanged.
+
+Export rollback restores the previous Beads-compatible projection files captured before the export write. This rollback affects files such as `issues.jsonl`, `comments.jsonl`, and `dependencies.jsonl`; it does not roll back Kernel authority.
+
+After Kernel command routing is active, a committed Kernel mutation must be reversed through a Kernel operation or a documented Kernel migration rollback. Do not use Beads export rollback as an authority rollback.
+
+## Conflict Quarantine Boundary
+
+Conflict quarantine is defined by the landed evaluator contract in [Kernel Conflict Evaluators](kernel-conflict-evaluators.md). Migration UX should reference that contract for exact quarantine behavior, evaluator evidence, and release-readiness checks.
+
+The intended UX boundary is stable:
+
+- stale revisions, duplicate writes, dependency cycles, and projection drift are detected before external projection;
+- conflicting records are quarantined instead of projected as normal output;
+- the operator gets enough detail to decide whether to repair source input, retry projection, or wait for a resolver path.
+
+## Release Readiness Checklist
+
+- Beads import fidelity report reviewed.
+- Export dry-run reviewed before any write.
+- Rollback snapshot path documented for write-enabled export.
+- Projection failure behavior documented as non-authoritative rollback.
+- Conflict quarantine behavior cross-checked against [Kernel Conflict Evaluators](kernel-conflict-evaluators.md).

package/docs/reference/control-plane-guarantees.md

@@ -0,0 +1,125 @@
+# Control-plane guarantees — what each control state actually does
+
+Status: beta (B6). Issues: `7dc59af2` (controls config + `forge control`),
+`724356ea` (all-surface read + enforcement-locus badges). Epic: `363954dd`.
+
+This document is the **contract** the cockpit badges and the `forge control`
+command read from. It states, honestly and per surface, what a control state
+*actually* does today — so the UI never sells enforcement Forge cannot deliver.
+
+## Headline — the honest state of enforcement (as of 2026-07-15)
+
+**The configurable gate/rail registry is NOT yet consumed by any runtime deny.**
+An adversarial grep of every consumer of the resolved runtime graph found none
+that refuses on `workflow.gates.<id>.enabled`. So setting a gate or rail to
+`mandatory` vs `optional` today changes the **declared registry**, not runtime
+behavior.
+
+Real enforcement in Forge today lives **elsewhere, independent of these flags**:
+
+- the **B3 lefthook TDD pre-commit hook** (blocks a commit that changes source
+  without tests),
+- **B2 fail-closed `validate` / `preflight`** (these fail closed on their own
+  logic, *not* on `workflow.gates.<id>.enabled`),
+- **`enforce-stage.js`** (blocks a stage on kernel-recorded stage **order +
+  completion**, again independent of these flags).
+
+Because of this, **`ENFORCED` is reserved strictly for a wired runtime deny —
+and that set is EMPTY for these flags today.** The badges below never say
+`ENFORCED`; they say what is actually true (`DECLARED`, `DENY-ON-CHECK`,
+`VERIFY (warn-only)`, `PRESENT (advisory)`). Wiring the registry to real
+enforcement points is filed as separate post-beta work.
+
+## The two axes
+
+- **State** (author intent, written to config): `mandatory` · `optional` · `permission`.
+- **Enforcement-locus** (what actually happens today, and *where*):
+  - `registry — declared, not yet enforced` — the flag is stored and reflected in
+    the resolved graph, but **no runtime code consumes it to deny**. (stage-exit
+    gates, rails)
+  - `run-time verify (warn-only, never denies)` — consumed at run time, but only
+    **warns**; never overturns the operation. (`gate.issue_verify`)
+  - `deny-on-check (no chokepoint yet)` — a real, deny-**capable** primitive
+    (`forge gate check`), but **no chokepoint auto-invokes it**, so nothing denies
+    on it yet. (human gates)
+  - `render-time presence-only` — written into harness config / discovered by
+    precedence; nothing denies at run time. **Advisory.** (mcp / rules / skills)
+
+## The matrix — state × surface × what it actually does today
+
+| Surface | Example ids | Controllable by `forge control`? | State it takes | Enforcement-locus | What it actually does today |
+|---|---|---|---|---|---|
+| **Stage gate** | `gate.plan-exit`, `gate.dev-exit`, `gate.validate-exit`, `gate.ship-entry` | **Yes** | `mandatory` / `optional` | `registry — declared, not yet enforced` | Writes the declared value into the resolved graph. **No runtime consumer reads it** — `enforce-stage.js` blocks on stage order + kernel completion, which is independent of this flag. Setting mandatory/optional changes nothing at run time (yet). Badge: `DECLARED (no runtime consumer yet)`. |
+| **Issue-verify gate** | `gate.issue_verify` | **Yes** | `mandatory` / `optional` | `run-time verify (warn-only, never denies)` | Consumed by `lib/commands/_issue.js`: after a kernel write it re-reads and emits `verified` + `mismatches`, but **warn-only** — a mismatch prints a warning and never overturns the write's `ok`. `optional` skips the read-back. Badge: `VERIFY (warn-only)`. |
+| **Human gate** | `gate.intent`, `gate.plan-approval`, `gate.merge` | **Yes** | `permission` / `optional` | `deny-on-check (no chokepoint yet)` | The `forge gate approve` / `forge gate check` primitives are real and deny-**capable**: with the gate active, `forge gate check <issue> <id>` exits non-zero until a durable `gate.approved` event exists (`lib/gate-events.js`). But **no chokepoint auto-invokes `forge gate check`**, so nothing denies on it unless a skill/CI explicitly calls it. Badge: `DENY-ON-CHECK`. |
+| **L1 rail** | `rail.kernel_tracking` (unlocked); other rails (locked) | **Yes** (unlocked only) | `mandatory` / `optional` | `registry — declared, not yet enforced` | Writes the declared value; the resolved graph reflects it. **No runtime refusal exists** — the flag is read only by `gate.js` id-maps, not by an enforcement chokepoint. Locked rails cannot be lowered. Badge: `DECLARED (no runtime consumer yet)`. |
+| **MCP server** | `mcp.*` | **No — refused** | — | `render-time presence-only` | Rendered into harness MCP config. Presence advises the agent a tool exists; Forge does **not** deny at run time. Not enforceable. Badge: `PRESENT (advisory)`. |
+| **Rule** | `rule.*` (`rules/*.md`) | **No — refused** | — | `render-time presence-only` | Injected as agent guidance. No run-time deny. Advisory. Badge: `PRESENT (advisory)`. |
+| **Skill** | `skill.*` | **No — refused** | — | `render-time presence-only` | Discovered by precedence (`.skills/` > `skills/` > packaged). Presence, not enforcement. Advisory. Badge: `PRESENT (advisory)`. |
+
+## How the tri-state maps onto Forge's real config (single source of truth)
+
+The one config field `forge control` writes is **`workflow.gates.<id>.enabled`**
+in `.forge/config.yaml` — the field the resolver (`applyEnabledConfig` in
+`lib/core/runtime-graph.js`) consumes into the resolved graph, shared by gates
+and unlocked rails (`gate.*` / `rail.*` namespaces are disjoint). `forge control`
+reuses exactly this field — it does **not** add a parallel `controls:` key,
+because a key nothing reads would be doubly-fake. The tri-state is the
+*vocabulary*; `enabled` is the stored *truth*; state is **derived**, never stored
+twice.
+
+**Important:** writing this field changes the **declared registry** the read view
+and `forge options` reflect. It does **not**, today, change what any runtime
+chokepoint does (see the headline). The mapping:
+
+| State | Config written | Applies to | Effect today |
+|---|---|---|---|
+| `mandatory` | `workflow.gates.<id>.enabled = true` | stage gates, rails | declared active in the registry; no runtime consumer denies on it |
+| `optional` | `workflow.gates.<id>.enabled = false` | unlocked gates & rails | declared off; for `gate.issue_verify`, actually skips the warn-only read-back |
+| `permission` | `workflow.gates.<id>.enabled = true` | human gates only | keeps the gate active, so `forge gate check` *can* deny if a chokepoint calls it (none does yet) |
+
+Read-back derives the label from `(enabled, locked, isHumanGate)`:
+- human gate + enabled → `permission`; human gate + disabled → `optional`.
+- non-human gate/rail + enabled → `mandatory`; + disabled → `optional`.
+- `locked` primitives are always `mandatory` and render a `LOCKED` badge (cannot be lowered).
+
+## What `forge control` refuses, and why
+
+- **`permission` on a non-human gate or rail** — refused: the approve/check
+  primitive only applies to the three human gates; elsewhere `permission` has no
+  path at all.
+- **`optional` on a `locked` primitive** — refused: mirrors
+  `Cannot disable locked gate` in `forge gate`.
+- **Any `mcp.*` / `rule.*` / `skill.*` id** — refused with:
+  *"<id> is presence-only, not enforceable — Forge has no run-time deny for this
+  surface. See docs/reference/control-plane-guarantees.md."* These are read-only
+  in the cockpit; their badge is `PRESENT (advisory)`.
+
+## Badge vocabulary (what the read view / dashboard renders)
+
+Driven entirely by the honest enforcement-locus above — never by author intent:
+
+- `DECLARED (no runtime consumer yet)` — `registry — declared, not yet enforced`
+  (stage-exit gates, rails).
+- `VERIFY (warn-only)` — `run-time verify (warn-only, never denies)`
+  (`gate.issue_verify`).
+- `DENY-ON-CHECK` — `deny-on-check (no chokepoint yet)` (human gates).
+- `OFF (optional)` — a controllable flag set to `optional`.
+- `PRESENT (advisory)` — `render-time presence-only` (mcp/rules/skills).
+- `· LOCKED` — appended to a locked primitive that cannot be lowered.
+- `ENFORCED (...)` — **reserved for a wired runtime deny; emitted by NOTHING
+  today** (the set is empty until the registry is wired to enforcement points).
+
+A surface's badge reflects **where and whether** it is actually consumed, so the
+UI can never imply enforcement it lacks.
+
+## Deferred (out of B6 scope, filed separately)
+
+- **Wire the configurable gates/rails to real enforcement points** — the bigger
+  work that would let a `mandatory` gate/rail actually deny at run time. Filed as
+  separate post-beta work; B6 deliberately does *not* attempt it. B6's deliverable
+  is the honest vocabulary + matrix, not new enforcement.
+- **Control for advisory surfaces** (mcp/rules/skills) — no run-time deny path
+  exists; they stay read-only + `PRESENT (advisory)`.
+- **Live/SSE updates** — a separate stubbed issue; the read view is a
+  point-in-time snapshot.