forge-workflow 0.0.9 → 0.1.0-beta.2

package/docs/architecture/index.md

@@ -0,0 +1,66 @@
+# Architecture Index
+
+**Status:** Architecture record index and scoped navigation entry point.  
+**Update rule:** Any architecture-significant behavior that future implementers need must be captured as a scoped architecture record, ADR, work-folder evidence, or future Kernel/KnowledgeStore proposal.
+
+## Record types
+
+```text
+architecture_note      observed architectural fact, rule, constraint, or behavior
+architecture_decision  accepted direction after tradeoffs
+architecture_question  unresolved ambiguity or decision needed
+architecture_conflict  contradictory records or code/docs disagreement
+architecture_exception deliberate deviation with owner, reason, and review/expiry
+```
+
+## Scope map
+
+Add project scopes here as they become known:
+
+```text
+project
+  domain
+    bounded_context
+      subsystem
+        component
+          API / data model / workflow / operation
+```
+
+## Scoped files
+
+- `subsystems/` — subsystem/component architecture records.
+- `notes/` — individual architecture notes when no better scoped file exists yet.
+- `decisions/` — scoped decision records that are smaller than ADRs or waiting for ADR promotion.
+- `questions/` — open architecture questions.
+- `conflicts/` — active architecture conflicts.
+
+## Mandatory capture rule
+
+If future users or agents would need the information to avoid breaking the system, capture it with source evidence.
+
+Use:
+
+```text
+Observed fact      -> architecture_note
+Accepted direction -> architecture_decision or ADR
+Unclear topic      -> architecture_question
+Contradiction      -> architecture_conflict
+Temporary deviation -> architecture_exception
+```
+
+## Brownfield adoption
+
+For existing products, do not block work waiting for complete documentation. Start with partial records and improve coverage as files are touched.
+
+Each discovered note should include:
+
+```yaml
+id: AN-YYYYMMDD-short-slug
+record_type: architecture_note
+topic: <domain.subsystem.detail>
+scope: <project/domain/subsystem/component>
+status: observed
+confidence: low | medium | high
+source:
+  - path: <file-or-doc>
+```

package/docs/architecture/notes/README.md

@@ -0,0 +1,35 @@
+# Architecture Notes
+
+Use this directory for architecture-significant observations that do not yet belong in a scoped subsystem file.
+
+## Template
+
+```markdown
+# AN-YYYYMMDD-short-slug — Title
+
+```yaml
+id: AN-YYYYMMDD-short-slug
+record_type: architecture_note
+topic: domain.subsystem.detail
+scope: subsystem-or-component
+status: observed | reviewed | accepted | stale | superseded | conflict
+confidence: low | medium | high
+source:
+  - path: path/to/source
+    lines: 1-20
+supersedes: []
+conflicts_with: []
+```
+
+## Statement
+
+What architectural fact, rule, behavior, or constraint was discovered?
+
+## Evidence
+
+- Source links, code paths, tests, docs, issues, PRs, sessions.
+
+## Implications
+
+What should future humans/agents know before changing this area?
+```

package/docs/architecture/subsystems/README.md

@@ -0,0 +1,46 @@
+# Subsystem Architecture Records
+
+Use this directory for scoped architecture maps and records by subsystem/component.
+
+Recommended file names:
+
+```text
+cart.md
+pricing.md
+checkout.md
+identity.md
+kernel.md
+knowledge.md
+```
+
+Each subsystem file should stay readable and link to detailed notes, ADRs, work folders, tests, and source files.
+
+## Subsystem file template
+
+```markdown
+# <Subsystem> Architecture
+
+## Current summary
+
+Short current-state overview.
+
+## Active records
+
+- `<ID>` — short statement and link.
+
+## Data model / contracts
+
+Important entities, invariants, APIs, events, and ownership rules.
+
+## Operational behavior
+
+Runtime flows, failure behavior, retries, consistency model, queues, projections.
+
+## Open questions and conflicts
+
+- `<AQ/AC ID>` — link and short summary.
+
+## Source evidence
+
+- Code/docs/tests/work-folder links.
+```

package/docs/{TOOLCHAIN.md → forge/TOOLCHAIN.md}

@@ -4,34 +4,23 @@ Complete reference for all tools integrated with the Forge workflow.
 
 ## Overview
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        FORGE TOOLCHAIN                          │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  ┌─────────────┐   ┌─────────────────────┐                     │
-│  │   BEADS     │   │  EXTERNAL SERVICES  │                     │
-│  │   (bd)      │   │                     │                     │
-│  │             │   │  Parallel AI        │                     │
-│  │ Git-backed  │   │  Greptile           │                     │
-│  │ Issue       │   │  SonarCloud         │                     │
-│  │ Tracking    │   │  GitHub CLI         │                     │
-│  └─────────────┘   └─────────────────────┘                     │
-│        │                     │                                 │
-│        └─────────────────────┘                                 │
-│                          │                                      │
-│                    ┌─────▼─────┐                                │
-│                    │   FORGE   │                                │
-│                    │  7-Stage  │                                │
-│                    │  Workflow │                                │
-│                    └───────────┘                                │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
+Forge is a local runtime control plane that coordinates several tool surfaces:
+
+```text
+Forge runtime control plane
+  - workflow templates and stage skills
+  - local project state and protected surfaces
+  - kernel-backed issue wrappers and sync (Beads is an opt-out backend)
+  - validation, packaging, and release evidence
+  - review adapters and external service hooks
+  - harness projections for agent-specific commands, prompts, workflows, and skills
 ```
 
+The default TDD-first workflow is a core template shipped by Forge. It is not the only runtime primitive. Toolchain docs should describe tools by the surface they support: setup, state, workflow stages, validation, review, release, sync, and recovery.
+
 ---
 
-## Beads - Git-Backed Issue Tracking
+## Beads - Local Issue Tracking And Sync Projection
 
 **Package**: `@beads/bd`
 **Repository**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
@@ -40,7 +29,7 @@ Complete reference for all tools integrated with the Forge workflow.
 ### Why Beads?
 
 - **Persists across sessions** - Issues survive context clearing, compaction, new chats
-- **Git-backed** - Version controlled, mergeable, team-shareable
+- **Local-first** - Runtime state stays under local `.beads/` and does not dirty normal Git work
 - **Dependency tracking** - Know what blocks what
 - **Ready detection** - `forge ready` finds unblocked work automatically
 - **AI-optimized** - JSON output, semantic compaction, audit trails
@@ -66,9 +55,25 @@ bun add -d @beads/bd
 bunx bd init
 
 # Windows (global) — use PowerShell installer, NOT npm/bun add -g
-irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+#
+# ⚠️  SECURITY WARNING: The one-liner below pipes remote content directly to execution.
+#     If the upstream repo, CDN, or transit is compromised, this runs arbitrary code.
+#     Prefer the "download + inspect" flow below for supply-chain safety.
+#
+# RECOMMENDED (safer — download, inspect, then run):
+$installer = "$env:TEMP\beads-install.ps1"
+irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $installer
+# Open $installer in a text editor and review before running
+# Get-Content $installer | less     # or: notepad $installer
+& $installer                         # execute after inspection
 bd init
 
+# CONVENIENCE (unsafe — reviewed installer only, skip if you don't trust the source):
+# # See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
+# bd init
+
 # Or with bunx (macOS/Linux, no install needed)
 bunx @beads/bd init
 ```
@@ -77,19 +82,19 @@ bunx @beads/bd init
 
 ### File Structure
 
-After `bd init`, creates `.beads/` directory:
+After `bd init`, creates a local `.beads/` directory. Forge keeps this directory out of Git; `forge setup` writes local Git exclude rules under `.git/info/exclude` so downstream repositories do not need metadata-only commits.
 
 ```
 .beads/
-├── issues.jsonl      # Issue data (git-tracked, one JSON per line)
-├── beads.db          # SQLite cache (git-ignored, fast queries)
-├── metadata.json     # Database metadata
-├── config.yaml       # User configuration
-├── interactions.jsonl # Agent audit log
-└── .gitignore        # Ignores beads.db
+├── issues.jsonl       # Local/exported issue data
+├── beads.db           # SQLite cache, when present
+├── metadata.json      # Local database metadata
+├── config.yaml        # Local Beads configuration
+├── interactions.jsonl # Local agent audit log
+└── .gitignore         # Local ignore guard for runtime files
 ```
 
-**Dual-database architecture**: JSONL for git versioning, SQLite for fast local queries. Background daemon keeps them in sync.
+Do not commit live `.beads/` runtime files. Shared team state must use the configured sync/server authority or an explicit projection/import path.
 
 For day-to-day issue workflows, prefer the Forge wrapper commands (`forge ready`,
 `forge create`, `forge update`, `forge close`, `forge sync`). Use `bd` directly
@@ -244,17 +249,12 @@ Context7 provides current documentation that may be more recent than the AI's tr
   "mcpServers": {
     "context7": {
       "command": "bunx",
-      "args": ["--bun", "@upstash/context7-mcp@latest"]
+      "args": ["--bun", "@upstash/context7-mcp@2"]
     }
   }
 }
 ```
 
-**Cline (VSCode)**:
-1. Open VSCode Settings
-2. Search for "Cline MCP"
-3. Add Context7 server configuration
-
 **Cursor**: Check Cursor Settings → MCP Servers for configuration options
 
 **Other agents**: If your agent supports MCP, configure using the JSON format above
@@ -291,7 +291,7 @@ Add to `.mcp.json` in your project root:
   "mcpServers": {
     "context7": {
       "command": "bunx",
-      "args": ["--bun", "@upstash/context7-mcp@latest"]
+      "args": ["--bun", "@upstash/context7-mcp@2"]
     },
     "grep-app": {
       "command": "bunx",
@@ -521,7 +521,7 @@ volumes:
 ### GitHub CLI - PR Workflow
 
 **Installation**: [cli.github.com](https://cli.github.com)
-**Used in**: `/ship`, `/review`, `/premerge` stages
+**Used in**: `/ship` and `/review` stages
 
 ```bash
 # Install
@@ -558,7 +558,9 @@ bd --version
 bun add -g @beads/bd
 
 # Windows — use PowerShell installer (npm has EPERM bug)
-irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+# See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
 ```
 
 > **Why Forge + Beads?** Forge wraps the supported day-to-day issue workflow
@@ -568,7 +570,9 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 
 ---
 
-## Integration with Forge Stages
+## Default Workflow Template Mapping
+
+This table maps tools to the default workflow template. It is not the complete Forge product model and it is not a requirement that every project use every stage.
 
 | Stage | Tools Used |
 |-------|------------|
@@ -579,9 +583,10 @@ irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
 | `/validate` | Type check, lint, tests, SonarCloud |
 | `/ship` | `forge close`, `gh pr create` |
 | `/review` | `gh pr view`, Greptile, SonarCloud |
-| `/premerge` | `forge sync`, doc updates, hand off PR |
 | `/verify` | Documentation cross-check |
 
+Pre-merge is not a stage. Its work (`forge sync`, doc updates, hand off PR) runs inside the `/ship` and `/review` stages as an embedded documentation-and-handoff gate.
+
 ---
 
 ## Quick Reference Card
@@ -622,14 +627,18 @@ bun add -g @beads/bd
 # Or use bunx @beads/bd <command>
 
 # Windows — use PowerShell installer
-irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+# See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
 ```
 
 **Windows EPERM error during `npm install -g @beads/bd`**
 ```bash
 # npm @beads/bd has a known EPERM bug on Windows (Issue #1031)
 # Use the PowerShell installer instead:
-irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+# See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
 ```
 
 **"database locked"**

package/docs/forge/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/{AGENT_INSTALL_PROMPT.md → guides/AGENT_INSTALL_PROMPT.md}

@@ -20,13 +20,13 @@ First, determine which AI agent you are by checking for these directories:
 
 ```bash
 # Check for agent-specific directories
-ls -la | grep -E "\.claude|\.cursor|\.cline"
+ls -la | grep -E "\.claude|\.codex|\.cursor"
 ```
 
 **Agent Detection:**
 - `.claude/` exists → You are **Claude Code**
+- `.codex/` exists → You are **Codex**
 - `.cursor/` exists → You are **Cursor**
-- `.cline/` exists → You are **Cline**
 - None exist → Generic agent
 
 Store this for later: `DETECTED_AGENT=<name>`
@@ -328,8 +328,8 @@ EOF
 
 **This prompt is designed to work with:**
 - Claude Code (via CLI)
+- Codex (via CLI)
 - Cursor (via chat)
-- Cline (via VSCode extension)
 - Any AI coding assistant with file system access
 
 ---

package/docs/guides/BEADS_GITHUB_SYNC.md

@@ -0,0 +1,32 @@
+# Beads/GitHub Sync Deprecation
+
+Beads/GitHub workflow sync is deprecated. Forge no longer ships active `github-to-beads.yml` or `beads-to-github.yml` workflow templates, and `forge setup --sync` must not create new Beads/GitHub sync scaffolding.
+
+## Current Behavior
+
+- `.beads/` is local runtime/export state and is not committed.
+- `forge setup --sync` is retained only as a compatibility cleanup path and removes old generated Beads/GitHub sync files from existing installs when they are present.
+- Plain `forge setup` does not perform Beads/GitHub sync cleanup as a side effect.
+- `forge sync` may still run local Beads/Dolt sync operations while Beads compatibility remains, but it is not GitHub issue lifecycle sync.
+
+## Removed Generated Files
+
+The `forge setup --sync` compatibility cleanup removes the old generated files:
+
+```text
+.github/workflows/github-to-beads.yml
+.github/workflows/beads-to-github.yml
+.github/beads-mapping.json
+.github/beads-sync-config.json
+.github/scripts/beads-sync/*.mjs
+scripts/github-beads-sync.config.json
+scripts/github-beads-sync/*.mjs
+```
+
+Unrelated GitHub workflows are preserved.
+
+## Replacement Direction
+
+Future GitHub issue sync must use Forge Kernel/server authority. Local-only work is durable in local Kernel SQLite. Team or cross-machine issue state is serialized through server authority, then GitHub issues can be updated as a projection from that authority.
+
+Do not commit live `.beads/` files, create metadata-only PRs, or bypass protected branches to update issue tracker state.

package/docs/{ENHANCED_ONBOARDING.md → guides/ENHANCED_ONBOARDING.md}

@@ -1,11 +1,15 @@
 # Enhanced Onboarding Guide
 
+> **Historical — superseded by [Quickstart](../../QUICKSTART.md).** This guide predates the current onboarding flow and still references the old `/premerge` stage and some undocumented flags. Kept for historical reference only; do not follow it for a fresh install.
+
 Intelligent onboarding that adapts to your project and preserves existing content.
 
 ---
 
 ## Key Features
 
+> This guide describes the broader onboarding experience and workflow-profile ideas. For current first-run setup, start with [Quickstart](../../QUICKSTART.md). For the current workflow-template boundary, use [Workflow templates](WORKFLOW_TEMPLATES.md).
+
 ### Key Features
 
 1. **Intelligent File Merging** - Preserves your existing AGENTS.md content
@@ -35,7 +39,7 @@ bunx forge setup --merge=smart
 - Tech stack details
 
 **What gets updated:**
-- Workflow instructions (7-stage TDD process)
+- Workflow instructions (composable TDD process)
 - TDD principles
 - Git conventions
 
@@ -65,7 +69,7 @@ E-commerce platform for selling widgets.
 - 80% test coverage
 
 ## Workflow Configuration
-Use the 7-stage TDD workflow:
+Use the default TDD workflow template:
 1. /plan - Design intent, research, branch + worktree + task list
 2. /dev - Subagent-driven TDD per task
 ...
@@ -165,7 +169,7 @@ Forge adapts its workflow based on the type of work you're doing.
 
 ### Six Change Classifications
 
-#### 1. Critical (7 stages)
+#### 1. Critical (full default template)
 **Use for:** Security, auth, payments, breaking changes
 
 ```bash
@@ -178,11 +182,11 @@ bunx forge setup --type=critical
 /plan -> /dev -> /validate -> /ship -> /review -> /premerge -> /verify
 ```
 
-- Full 7-stage workflow with all gates
+- Full default Forge workflow template with all gates
 - OWASP analysis required
 - Design docs for strategic changes
 
-#### 2. Standard (6 stages)
+#### 2. Standard (6 stages plus `/status` utility)
 **Use for:** Normal features, enhancements
 
 ```bash
@@ -199,7 +203,7 @@ bunx forge setup --type=standard
 - Auto-escalates to **Critical** if keywords detected:
   - auth, security, payment, crypto, password, token, session, migration, breaking
 
-#### 3. Simple (3 stages)
+#### 3. Simple (4 stages)
 **Use for:** Bug fixes, small changes
 
 ```bash
@@ -209,7 +213,7 @@ bunx forge setup --type=simple
 
 **Workflow:**
 ```
-/dev -> /validate -> /ship
+/dev -> /validate -> /ship -> /premerge
 ```
 
 - Streamlined for quick fixes
@@ -232,7 +236,7 @@ bunx forge setup --type=hotfix
 - Skip planning and research
 - TDD to reproduce, then fix
 
-#### 5. Docs (2 stages)
+#### 5. Docs (3 stages)
 **Use for:** Documentation only
 
 ```bash
@@ -242,7 +246,7 @@ bunx forge setup --type=docs
 
 **Workflow:**
 ```
-/verify -> /ship
+/verify -> /ship -> /premerge
 ```
 
 - Minimal workflow for documentation changes
@@ -354,7 +358,7 @@ git checkout -b feat/user-authentication
 bunx forge setup --type=critical
 
 # Uses Critical profile:
-# - Full 7-stage workflow
+# - Full default Forge workflow template
 # - OWASP analysis required
 # - Design docs for strategic changes
 ```
@@ -593,8 +597,8 @@ Share project knowledge with team.
 
 ## Related Documentation
 
-- [Main README](../README.md) - Overview and quick start
-- [Workflow Guide](../AGENTS.md) - Complete 7-stage workflow
+- [Main README](../../README.md) - Overview and quick start
+- [Workflow Guide](../../AGENTS.md) - Complete default Forge workflow template
 - [Setup Guide](SETUP.md) - Agent-specific setup
 - [Agent Install Prompt](AGENT_INSTALL_PROMPT.md) - AI-assisted setup
 

package/docs/guides/GREPTILE_SETUP.md

@@ -0,0 +1,46 @@
+# Greptile Code Review Setup
+
+Greptile is an optional review integration. Do not assume it is installed, required by branch protection, or present on every Forge consumer repository. Verify the current repository's checks before documenting Greptile as a required gate.
+
+## Verify Current Status
+
+```bash
+gh pr checks <pr-number>
+gh api repos/<owner>/<repo>/branches/<branch>/protection
+```
+
+If Greptile appears on PRs and you want it to block merges, add the exact check name reported by GitHub to branch protection. Required check names are repository-specific.
+
+## How Greptile Fits Forge
+
+- Greptile can provide PR review comments through the GitHub App.
+- A repository may add a custom quality-gate workflow.
+- Forge review work should reply to and resolve actionable review threads.
+- The review adapter scaffold currently supports Greptile-shaped review adapters.
+
+## Setup Boundary
+
+Forge does not guarantee that Greptile is installed or enforced. Treat Greptile as repository configuration:
+
+1. Install/configure the Greptile GitHub App.
+2. Confirm it runs on a PR.
+3. Add required checks only after the check name is visible.
+4. Document the configured branch-protection rule in the repository.
+
+## Review Handling
+
+When the repo includes the helper script:
+
+```bash
+bash .claude/scripts/review-resolve.sh list <pr-number> --unresolved
+bash .claude/scripts/review-resolve.sh stats <pr-number>
+```
+
+Reply to each valid, invalid, conflicting, or out-of-scope thread before resolving it.
+
+## Known Limits
+
+- Greptile availability depends on GitHub App installation and repository access.
+- Branch protection may not include Greptile even when Greptile comments on PRs.
+- Required check names can change if workflows or integrations are renamed.
+