forge-workflow 0.0.10 → 0.1.0-beta.2

package/docs/guides/SUPPORT.md

@@ -0,0 +1,185 @@
+# Support And Troubleshooting
+
+Start here when Forge setup, Beads, protected state, GitHub sync, worktrees, validation, or release readiness fails.
+
+## First Checks
+
+```bash
+git status --short --branch
+git remote show origin
+bun --version
+node --version
+bun run check
+```
+
+If the failure involves Beads:
+
+```bash
+bd doctor
+bd dolt status
+forge sync
+```
+
+If `forge` wrappers fail because Beads is unavailable, use direct `git`, `gh`, and `bd` commands only after identifying the source of truth.
+
+For branch-specific checks, resolve the default branch first:
+
+```powershell
+$defaultBranch = git remote show origin | Select-String 'HEAD branch' | ForEach-Object { $_.ToString().Split(':')[-1].Trim() }
+```
+
+## FAQ
+
+### Is DeepWiki the source of truth?
+
+No. DeepWiki is generated from the repository. Fix README, CHANGELOG, quickstart, docs, CLI files, and tests first, then refresh DeepWiki.
+
+### Is Forge only the seven-stage TDD workflow?
+
+No. The default template is TDD-first, but Forge is a runtime control plane with local state, gates, adapters, issue wrappers, validation evidence, and recovery surfaces.
+
+### Are `/review` and `/verify` CLI commands?
+
+They are agent workflow stages. Do not document them as `forge review` or `forge verify` unless those CLI commands exist in the current code.
+
+### Does protected state always block edits?
+
+Only when `scripts/protected-state-check.js` is wired into the active hook or CI path. The model is real, but enforcement depends on configuration.
+
+### Can agents publish releases?
+
+Agents can prepare a release PR and validation evidence. Publishing is out of scope unless the user explicitly requests it.
+
+## Beads And Dolt Recovery
+
+Common errors:
+
+- `Beads is not initialized in this project.`
+- `database "forge" not found on Dolt server`
+- `database locked`
+- stale `.beads/backup` data
+- Windows EPERM or locked files during worktree cleanup
+
+Triage:
+
+```bash
+bd doctor
+bd dolt status
+bd dolt pull
+bd dolt push
+```
+
+If the Dolt server is serving the wrong database or data directory, stop and diagnose before closing or rewriting issue state. Use the root checkout when the feature worktree has an incomplete `.beads` runtime.
+
+Recovery guidance:
+
+- Preserve current state first: copy `.beads/backup` or export a Beads backup if the command is available.
+- Prefer `forge sync` when Beads is configured and healthy.
+- Use `bd close`, `bd comments`, or `bd dep` directly only for operations Forge does not wrap or when wrappers fail.
+- Do not create follow-up PRs just to commit Beads runtime metadata. `.beads/` is local non-versioned state; shared state must flow through the configured sync/server authority or an explicit projection/import path.
+- Do not hand-edit `.beads` live state unless a recovery procedure explicitly requires it.
+- Success proof is concrete: `bd doctor` exits cleanly, `bd dolt status` is understandable, and `forge ready` or `forge show <id>` can read current issue state.
+
+## GitHub Sync
+
+`forge setup --sync` is deprecated and removes old generated GitHub/Beads sync scaffolding. `forge sync` still runs local Beads/Dolt sync operations when configured. Future GitHub issue sync belongs to Forge Kernel/server authority.
+
+Modern sync should use snapshot, backup, server authority, or explicit projection files, not stale examples that edit or commit live `.beads/issues.jsonl` directly.
+
+When sync fails:
+
+```bash
+gh auth status
+bd doctor
+bd dolt status
+```
+
+```powershell
+gh run list --branch $defaultBranch --limit 10
+```
+
+Check whether GitHub owns the field you are trying to update. GitHub owns shared remote issue fields; Forge/Beads owns local workflow context and recovery metadata.
+
+## Worktrees
+
+Create isolated work:
+
+```bash
+forge worktree create <slug> --branch <branch-name>
+```
+
+Remove it:
+
+```bash
+forge worktree remove <slug>
+```
+
+If removal fails on Windows:
+
+1. Stop any active `node`, `bun`, `gh`, or Dolt process using the worktree.
+2. Run `git worktree list`.
+3. Prove the branch is preserved: `git status --short --branch` and `git log --oneline -1`.
+4. Retry `forge worktree remove <slug>`.
+5. If Git already unregistered the worktree but files remain locked, wait for the process to exit before deleting the leftover directory.
+
+Never delete a worktree before verifying that its branch is pushed or intentionally disposable.
+
+## Branch Protection
+
+Branch protection can reject direct pushes to `master` or `main` with `GH006`. That is expected for code changes.
+
+Beads runtime metadata is not a branch-protection exception. If shared state is required, use the configured sync/server authority or an explicit projection/import path; do not open metadata-only PRs for live `.beads/` files.
+
+Recovery:
+
+```bash
+git status --short --branch
+gh pr checks <pr-number>
+```
+
+```powershell
+git fetch origin $defaultBranch
+```
+
+If shared metadata cannot sync, diagnose the sync/server authority path instead of pushing live `.beads/` state to the protected branch.
+
+## Rollback And Recovery Paths
+
+Choose the rollback path by surface:
+
+- Release documentation confusion: revert the release PR or open a corrective docs PR. Do not publish while README, CHANGELOG, Quickstart, package metadata, and release docs disagree.
+- Setup-generated files: rerun `forge setup --dry-run` first, then rerun setup with the intended `--merge` mode. Preserve existing instruction files before replacing them.
+- Beads metadata: prefer `forge sync`, server authority, or explicit projection/import paths. Avoid direct `.beads` edits unless a documented recovery path requires them.
+- Failed GitHub sync commit: inspect the workflow run, preserve the generated backup or snapshot, then replay through the configured sync workflow or a follow-up branch.
+- Worktree cleanup: prove the branch is pushed or disposable before removal, then remove through `forge worktree remove <slug>` or Git's worktree command if Forge is unavailable.
+
+## Protected State
+
+Protected surfaces include `.beads`, `.forge`, generated agent harness files, workflows, lockfiles, extension manifests, secrets, immutable Git internals, and append-only logs.
+
+If a protected-state check blocks a file:
+
+1. Read the repair hint.
+2. Use the owning command or API surface.
+3. For Forge-owned writes, set `FORGE_PROTECTED_STATE_ALLOWED_SURFACES` only for the surfaces that command owns.
+4. For Beads metadata after merge, keep `.beads/` local and diagnose the sync/server authority path when shared state is required.
+
+## Validation Failures
+
+`bun run check` runs:
+
+1. `bun run typecheck`
+2. `bun run lint`
+3. `bun audit`
+4. `node scripts/test.js --validate`
+
+Fix the first failing stage first. Do not hide a validation failure by documenting that it "should pass"; rerun the command and record the fresh result.
+
+## Known Limitations
+
+- Package version remains separate from docs readiness until release/publish occurs.
+- `forge migrate` is dry-run only.
+- Protected-state enforcement depends on hooks/CI wiring.
+- Review adapters currently focus on review adapters and Greptile-shaped scaffolding.
+- DeepWiki can lag after merge until refreshed.
+- Some external services require credentials and branch protection setup outside Forge.

package/docs/guides/WORKFLOW_TEMPLATES.md

@@ -0,0 +1,74 @@
+# Workflow Templates
+
+Forge's workflow is a core product surface, not a side note. The default template gives agents a known path for planning, development, validation, shipping, review, and post-merge verification, with a pre-merge documentation gate that finishes docs and hands off the PR inside the ship and review stages.
+
+## Default Template
+
+The full default template is:
+
+```text
+/plan -> /dev -> /validate -> /ship -> /review -> /verify
+```
+
+Projects can use the full template or smaller profile-specific paths. The important boundary is that these are agent workflow stages, not necessarily standalone `forge <stage>` CLI commands.
+
+## Why It Matters
+
+The template gives AI-assisted work a repeatable operating model:
+
+- `/plan` captures intent, research, branch/worktree setup, and tasks.
+- `/dev` implements through a TDD-oriented loop.
+- `/validate` gathers evidence from project checks.
+- `/ship` prepares a reviewable PR.
+- `/review` handles PR feedback and evaluator findings.
+- `/verify` proves post-merge health when the workflow type requires it.
+
+Before merge, a pre-merge documentation gate finishes documentation and handoff context. It is not a numbered stage or a `/premerge` command; it runs inside the `/ship` and `/review` stages.
+
+The value is not the exact number of stages. The value is recoverable state, known handoff points, validation evidence, and clear ownership while agents work.
+
+## Customization Model
+
+Forge treats the default workflow as a configurable template over runtime building blocks:
+
+- stages can be skipped or shortened by workflow type,
+- project setup can choose different harness targets,
+- `.forge/config.yaml` records adoption profile and harness choices,
+- `forge options lint`, `forge options diff`, and `forge options stages` inspect the resolved config,
+- future work can add or replace stages through skills, adapters, and extension manifests.
+
+Customization should stay explicit. Do not silently remove validation, review, or state handoff steps from high-risk work.
+
+## Workflow Types
+
+Current docs describe these profiles:
+
+| Type | Intended use | Typical path |
+| --- | --- | --- |
+| Critical | Security, auth, payments, migrations, breaking changes | Full template |
+| Standard | Normal features and enhancements | Plan through review |
+| Simple | Small fixes and focused changes | Shorter dev, validate, ship path |
+| Hotfix | Production emergencies | Short path with urgent validation |
+| Docs | Documentation-only changes | Verify and ship |
+| Refactor | Behavior-preserving cleanup | Plan, dev, validate, ship |
+
+Profile docs must be checked against `lib/workflow-profiles.js` and `AGENTS.md` before release because command files, skills, and runtime profiles can drift.
+
+## Skills Direction
+
+Forge is moving toward skills as the portable agent-facing package format. Current v0.0.11 packaging still includes command projections for several agents, and Codex already receives stage workflows as `.codex/skills/<stage>/SKILL.md`.
+
+See [Skills and command projections](../reference/SKILLS.md) for the current source-of-truth boundary.
+
+## Live Feature Rollout
+
+When a planned feature becomes real, update docs in this order:
+
+1. Verify the code, tests, package contents, and CLI output.
+2. Move the feature from roadmap or experimental docs into ready-now docs.
+3. Update README, Quickstart, this guide, and the relevant reference page.
+4. Add migration or support notes if the feature changes setup, state, validation, or workflow behavior.
+5. Refresh DeepWiki after merge and record the generated index date and commit.
+
+Do not document future workflow customization as ready-now until the command, skill, or runtime surface exists and has validation evidence.
+

package/docs/guides/memory-backends.md

@@ -0,0 +1,183 @@
+# Forge Memory
+
+Forge gives agents **durable project memory** through two verbs:
+
+```bash
+forge remember "<note>" [--tag <label>]...   # write a lasting fact
+forge recall  "[query]"  [--limit N]         # read it back
+```
+
+Both route through a small **backend router** (`lib/memory/router.js`). The
+backend is chosen by `memory.backend` in `.forge/config.yaml`:
+
+| Backend | Storage | Needs | When |
+|---|---|---|---|
+| **`local`** (default) | kernel `kernel_memories` table, FTS5-indexed | nothing — offline, instant | always the floor |
+| **`graphiti`** _(experimental)_ | temporal **knowledge graph** over MCP | graph DB + LLM | evolving, relational, temporal recall |
+
+`local` and `graphiti` are the only public `memory.backend` values.
+
+> **The local backend is the default and the guaranteed offline floor.** You do
+> not need to configure anything to use `forge remember` / `forge recall`. The
+> Graphiti backend is strictly **opt-in** and never changes the default path.
+>
+> **`graphiti` is experimental — its runtime emitter is not yet shipped.**
+> Selecting it today still writes the local kernel floor (the graph emit is a
+> best-effort no-op), so `recall` always reads back from the kernel. The config
+> and `forge doctor` reachability checks work; the write-through emit is a
+> fast-follow.
+
+Precedence for selecting the backend:
+`FORGE_MEMORY_BACKEND` env → `memory.backend` in config → `local`.
+
+Check the active backend any time:
+
+```bash
+forge doctor            # reports the memory backend (+ graphiti reachability, non-fatal)
+```
+
+## Local (default) — nothing to set up
+
+Notes persist to the kernel `kernel_memories` table (the per-repo Forge Kernel
+SQLite store under `.git/forge/`), indexed by **FTS5** for token-AND BM25 recall.
+No services, no network, no keys. This is what ships and what most projects
+should use. `recall` with no query returns the newest notes plus a total count;
+a query does full-text BM25 matching (every token must appear, in any order). The
+same kernel table also holds what `forge insights` learns; those records are
+recallable with a query or `--all` (the default no-query listing shows only your
+`remember` notes). (An older flat `.forge/memory/notes.jsonl` is imported once on
+first use, then retired.)
+
+## Opt into Graphiti (knowledge-graph memory)
+
+[Graphiti](https://github.com/getzep/graphiti) (getzep/graphiti) is a Python
+framework that turns notes ("episodes") into a **bi-temporal knowledge graph**:
+an LLM extracts entities and facts, every fact carries two timelines (when it
+was true in the world, and when the system learned it), and superseded facts are
+**invalidated, not deleted** — so you can query "what is true now" or "what was
+true at time T", with a pointer back to the source (provenance). It is served to
+any MCP agent through Graphiti's **MCP server**; Forge only wires it in.
+
+Forge does **not** bundle or reimplement Graphiti. Forge ships the config +
+router seam and documents how to run Graphiti; when `memory.backend` resolves to
+`graphiti` (and the config passes the same validity check `forge doctor` uses),
+**`forge setup` automatically writes the MCP server entry** into `.mcp.json`
+(Claude) and `.cursor/mcp.json` (Cursor) from the descriptor in
+`lib/memory/graphiti-mcp.js`. For other harnesses (e.g. Codex `config.toml`) you
+add the server entry yourself (template below). Design rationale and trade-offs:
+[`docs/work/2026-07-06-graphiti-memory/research.md`](../work/2026-07-06-graphiti-memory/research.md).
+
+### 1. Turn it on (config)
+
+Set the backend in `.forge/config.yaml` — additive and reversible:
+
+```yaml
+memory:
+  backend: graphiti
+  graphiti:
+    # --- active today (validated by the router / forge doctor) ---
+    transport: stdio            # stdio | http
+    mcpServerPath: ./graphiti/mcp_server   # required — path to the Graphiti checkout's mcp_server dir
+    graphDb: falkordb           # falkordb | falkordb-lite | neo4j
+    apiKeyEnv: OPENAI_API_KEY    # referenced by NAME — never store the key here
+    # --- reserved: NO EFFECT yet (the descriptor emits ${VAR} env references, not these values) ---
+    dbUri: redis://localhost:6379
+    llmProvider: openai
+    model: gpt-5.5
+    groupId: <your-project>
+```
+
+Only `mcpServerPath` is required today (it's what `forge doctor` checks and what
+the descriptor threads into the launch args). The keys under "reserved" still
+have no effect — the rendered entry references env vars (`${VAR}`), not these
+literal values — set them now only if you like, they are no-ops until a renderer
+consumes them.
+
+Forge exposes the MCP server as a harness-agnostic **descriptor** (see
+`lib/memory/graphiti-mcp.js`, `buildGraphitiServerDescriptor`) and `forge setup`
+wires it into the right place for Claude (`.mcp.json`) and Cursor
+(`.cursor/mcp.json`), preserving any servers you already have there. Codex
+(`config.toml`) is not auto-wired yet. The descriptor's env values are `${VAR}`
+references only — Forge never writes a secret into any committed config. The
+rendered entry looks like:
+
+```json
+"graphiti-memory": {
+  "transport": "stdio",
+  "command": "uv",
+  "args": ["run","--isolated","--directory","./graphiti/mcp_server",
+           "--project",".","main.py","--transport","stdio"],
+  "env": {
+    "FALKORDB_URI": "${FALKORDB_URI}",
+    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+    "MODEL_NAME": "${MODEL_NAME}",
+    "GROUP_ID": "${GRAPHITI_GROUP_ID}"
+  }
+}
+```
+
+### 2. Run the graph DB + MCP server
+
+Graphiti needs a **graph database** and an **LLM/embedder**. The documented
+default is **FalkorDB** (a light, Redis-based graph DB via Docker) with an
+OpenAI-compatible model. Roughly:
+
+```bash
+# a) graph DB (FalkorDB) — or run the Graphiti combined Docker Compose
+docker run -p 6379:6379 -it --rm falkordb/falkordb:latest
+
+# b) the Graphiti MCP server (from a graphiti checkout)
+git clone https://github.com/getzep/graphiti
+cd graphiti/mcp_server
+export OPENAI_API_KEY=sk-...          # or point at an OpenAI-compatible endpoint
+uv run --isolated --directory . --project . main.py --transport stdio
+```
+
+Set `memory.graphiti.mcpServerPath` in `.forge/config.yaml` to the checkout's
+`mcp_server` directory so `forge doctor` can see it.
+
+**Alternatives** (all documented in the design doc):
+
+- **Graph DB:** FalkorDB (Docker, default) · FalkorDB-lite (embedded, Python
+  3.12+, no server) · Neo4j (production). Set `memory.graphiti.graphDb` +
+  `dbUri` accordingly (Neo4j uses `NEO4J_URI` plus `NEO4J_USER` and
+  `NEO4J_PASSWORD`).
+- **LLM/embedder:** OpenAI (best quality) · any OpenAI-compatible endpoint
+  (OpenRouter, DeepSeek, Together) · **Ollama** for a fully local/offline stack
+  (`ollama pull deepseek-r1:7b` + `ollama pull nomic-embed-text`). Set
+  `memory.graphiti.llmProvider` / `model` / `apiKeyEnv`.
+
+### 3. Use it
+
+Once wired, **agents** call the graph directly over MCP:
+
+- `add_memory` — record a durable fact/decision as an episode (scope with
+  `group_id`). Ingestion is LLM-backed, so treat writes as async.
+- `search_memory_facts` — retrieve facts/edges (with validity windows) before
+  assuming.
+- `search_nodes` — find entities and summaries.
+
+The **`memory` skill** ([`skills/memory/SKILL.md`](../../skills/memory/SKILL.md))
+teaches agents when and how to use these. `forge remember` / `forge recall` keep
+working from the CLI — when the graph backend is selected they still write to the
+local kernel store as a safety floor, so a note is never lost.
+
+## Privacy & cost (read before enabling)
+
+- **Privacy:** with an LLM provider like OpenAI, **every note you add as an
+  episode is sent to that LLM** for entity/fact extraction. For private dev
+  notes this matters — use the Ollama/local path if that is a concern.
+- **Cost + latency:** `add_memory` fires **multiple LLM calls** per episode, so
+  writes are billable and take from sub-second to a couple of seconds. Prefer
+  async ingest; retrieval is cheap.
+- **Ops:** you run and maintain a graph DB + the (experimental) Graphiti MCP
+  server. This is a real jump from "write a note to the local kernel store" —
+  which is exactly why it is opt-in and the local backend stays the default.
+
+## Turning it off
+
+Remove `memory.backend` (and the `memory.graphiti` block) from
+`.forge/config.yaml` — the router falls straight back to `local`. Your local
+kernel notes were never touched. If a `graphiti-memory` entry is in your agent's
+MCP config — whether `forge setup` wrote it when you enabled Graphiti, or you
+added it by hand — delete it too.

package/docs/reference/ADAPTERS.md

@@ -0,0 +1,128 @@
+# Forge Adapters
+
+Forge adapters normalize provider-specific surfaces behind Forge-owned contracts. The bundled adapters are reference implementations; Forge owns the contract and authority rules.
+
+Current public support is narrow: Beads is the reference issue adapter, and review-adapter scaffolding supports review adapters with a Greptile-shaped starter template. Other adapter kinds are roadmap or internal design work until implemented and tested.
+
+## Issue Adapters
+
+Issue adapters expose issue tracking operations without making Beads, GitHub, Linear, Jira, or another provider the Forge API. The bundled reference adapter is `BeadsIssueAdapter`.
+
+### Issue Contract
+
+An issue adapter has `kind: "issue"` and implements these methods:
+
+- `list(args, context)`: list issues from the provider/backend.
+- `read(args, context)`: read a single issue. The Beads adapter maps this to `bd show`.
+- `create(args, context)`: create an issue.
+- `update(args, context)`: update issue fields.
+- `close(args, context)`: close an issue.
+- `comment(args, context)`: add an issue comment. The Beads adapter maps this to `bd comments add`.
+- `mapStatus(status, context)`: map provider status into the requested target state.
+- `decideAuthority(change, context)`: return the Forge authority decision for a field change.
+
+### Issue Authority
+
+GitHub owns shared team-visible fields: GitHub identity, URL, title, body, state, assignees, labels, milestone, and remote update timestamps.
+
+Forge owns workflow and project context: Forge issue id, dependencies, parent/child links, workflow stages, acceptance criteria, progress notes, stage transitions, decisions, memory, outbound projection bookkeeping, and drift diagnostics.
+
+Beads is the local/reference issue adapter and cache backend. Cache fields are derived and may be rebuilt. Unknown field paths are rejected until the authority model explicitly assigns ownership.
+
+### Conflict Behavior
+
+During pull/import, GitHub-owned remote fields overwrite local materialized shared fields and differences are recorded as drift diagnostics. Forge-owned fields are preserved locally and are not overwritten by GitHub import. Cache fields are rebuilt from the authoritative inputs.
+
+### Issue Non-Scope
+
+Issue adapters do not implement team dashboard UI, ReviewAdapter internals, GitHub Projects board automation, or full comment/discussion import. GitHub issue import must use the existing `lib/issue-sync/import-primitives.js` reconciliation path rather than a separate import contract.
+
+## Review Adapters
+
+Forge review adapters normalize provider-specific review feedback into one contract used by review tooling and offline fixture tests.
+
+### Review Contract
+
+A review adapter has `kind: "review"` and implements these methods:
+
+- `fetchThreads(context)`: fetch provider review threads. Live adapters may use GitHub, REST, GraphQL, or a provider SDK.
+- `parse(payload, options)`: normalize provider payloads into review thread objects.
+- `reply(context)`: post a reply to a provider review comment.
+- `resolve(context)`: mark a provider review thread resolved.
+- `score(threads, context)`: score or classify parsed threads, usually by checking local commits or fixture data.
+
+Normalized thread shape:
+
+```js
+{
+  id: 'provider-thread-id',
+  commentId: 123,
+  file: 'lib/example.js',
+  line: 42,
+  body: 'review text',
+  author: 'review-bot',
+  isResolved: false,
+  raw: {}
+}
+```
+
+### Review Lifecycle
+
+1. `fetchThreads` obtains raw provider data for live review runs.
+2. `parse` filters and normalizes the provider data.
+3. `score` decides whether local work appears to address each parsed thread.
+4. `reply` posts the resolution explanation.
+5. `resolve` closes the provider thread after a reply is recorded.
+
+The bundled `GreptileReviewAdapter` is the compatibility reference. Existing Greptile shell commands keep their public command names while the shared matching behavior is routed through the adapter implementation.
+
+### Review Scaffold
+
+Create a local review adapter starter:
+
+```bash
+forge new adapter coderabbit --kind=review --template=greptile
+```
+
+The scaffold is written to:
+
+```text
+.forge/adapters/review/coderabbit.js
+```
+
+Only review adapters and the Greptile-shaped starter template are supported in this foundation PR.
+
+### Review Fixture Replay
+
+Run adapter parsing and scoring offline:
+
+```bash
+forge adapter test greptile --fixture=fixtures/greptile-review.json
+```
+
+Fixture shape:
+
+```json
+{
+  "input": {
+    "data": {
+      "repository": {
+        "pullRequest": {
+          "reviewThreads": {
+            "nodes": []
+          }
+        }
+      }
+    }
+  },
+  "expect": {
+    "threads": 0
+  }
+}
+```
+
+Fixture replay must not make network calls. Live provider calls belong in `fetchThreads`, `reply`, and `resolve`.
+
+### Review Non-Scope
+
+Review adapters do not implement issue tracking, GitHub issue sync, or the full v3 reference adapter template catalog.