forge-workflow 0.0.10 → 0.1.0-beta.2

package/docs/reference/RESEARCH_TEMPLATE.md

@@ -0,0 +1,292 @@
+# Research: [Feature Name]
+
+**Date**: YYYY-MM-DD
+**Researcher**: Claude AI
+
+## Objective
+[What we're trying to achieve - clear problem statement and goals]
+
+## Codebase Analysis
+
+### Existing Patterns
+- **File**: `path/to/file.ts`
+- **Pattern**: [Description of existing implementation]
+- **Reusability**: [Yes/No + reasoning]
+- **Lessons learned**: [What worked, what didn't]
+
+### Affected Modules
+- **Module**: [name]
+- **Changes needed**: [Description]
+- **Impact**: [Low/Medium/High]
+- **Dependencies**: [List any dependencies]
+
+### Test Infrastructure
+- **Existing tests**: `path/to/tests/`
+- **Test utilities**: [Available testing tools/helpers]
+- **Coverage**: [Current state - percentage, gaps]
+- **Test patterns**: [What patterns are used - unit, integration, E2E]
+
+## Web Research
+
+### Best Practices (parallel-web-search)
+1. **Source**: [URL]
+   - **Key insight**: [Summary of best practice]
+   - **Applicability**: [How it applies to our project]
+   - **Decision impact**: [What decision this influences]
+   - **Implementation notes**: [How to apply]
+
+2. **Source**: [URL]
+   - [...]
+
+### Known Issues (parallel-web-search)
+1. **Issue**: [Description]
+   - **Source**: [GitHub/SO/Blog URL]
+   - **Mitigation**: [How to avoid]
+   - **Decision impact**: [Changes to approach]
+   - **Frequency**: [How common is this issue]
+
+2. **Issue**: [...]
+
+### Library Documentation (Context7)
+1. **Library**: [name and version]
+   - **API**: [Relevant methods/patterns]
+   - **Compatibility**: [Version requirements, breaking changes]
+   - **Decision impact**: [Implementation details]
+   - **Example usage**: [Code snippet]
+
+2. **Library**: [...]
+
+### Case Studies
+1. **Source**: [URL]
+   - **Company/Project**: [Who implemented this]
+   - **Scale**: [Production scale, users, data volume]
+   - **Lessons**: [What they learned]
+   - **Applicability**: [How it relates to our use case]
+
+2. **Source**: [...]
+
+## Key Decisions & Reasoning
+
+### Decision 1: [Decision Title]
+- **Decision**: [What we decided]
+- **Reasoning**: [Why we chose this approach]
+- **Evidence**: [Research that supports this - links to sources]
+- **Alternatives considered**:
+  1. [Alternative 1]: [Why rejected]
+  2. [Alternative 2]: [Why rejected]
+- **Trade-offs**: [What we're giving up, what we're gaining]
+- **Risk**: [Low/Medium/High] - [Risk description]
+
+### Decision 2: [Decision Title]
+- [...]
+
+## TDD Test Scenarios (Identified Upfront)
+
+### Unit Tests
+1. **Test**: [Scenario description]
+   - **File**: `test/path/test.ts`
+   - **Function under test**: `functionName()`
+   - **Assertions**: [What to verify]
+   - **Test data**: [Required test data/mocks]
+   - **Edge cases**: [List edge cases to cover]
+
+2. **Test**: [...]
+
+### Integration Tests
+1. **Test**: [Scenario description]
+   - **File**: `test/integration/test.ts`
+   - **Components**: [What components are being tested together]
+   - **Assertions**: [What to verify]
+   - **Test data**: [Database fixtures, API mocks]
+
+2. **Test**: [...]
+
+### E2E Tests
+1. **Test**: [User flow scenario]
+   - **File**: `test/e2e/test.ts`
+   - **User flow**: [Step-by-step user actions]
+   - **Assertions**: [What user should see/experience]
+   - **Test data**: [Complete test environment setup]
+
+2. **Test**: [...]
+
+## Security Analysis (OWASP Top 10 + Feature-Specific)
+
+### OWASP Top 10 Applicability
+
+#### A01: Broken Access Control
+- **Risk**: [High/Medium/Low]
+- **Applicable**: [Yes/No]
+- **Mitigation**: [How addressed - RLS policies, permission checks]
+- **Tests**: [Security test scenarios]
+- **Evidence**: [Links to security research]
+
+#### A02: Cryptographic Failures
+- **Risk**: [High/Medium/Low]
+- **Applicable**: [Yes/No]
+- **Mitigation**: [Encryption at rest/transit, key management]
+- **Tests**: [Encryption tests]
+- **Compliance**: [Data protection requirements]
+
+#### A03: Injection
+- **Risk**: [High/Medium/Low]
+- **Applicable**: [Yes/No]
+- **Mitigation**: [Parameterized queries, input validation, sanitization]
+- **Tests**: [SQL injection tests, XSS tests, command injection tests]
+- **Libraries**: [What libraries help prevent injection]
+
+#### A04: Insecure Design
+- **Risk**: [High/Medium/Low]
+- **Threat model**: [Key threats identified]
+- **Secure design patterns**: [Patterns used - zero trust, defense in depth]
+- **Architecture review**: [Security considerations in design]
+- **Tests**: [Security design validation]
+
+#### A05: Security Misconfiguration
+- **Risk**: [High/Medium/Low]
+- **Configuration reviewed**: [Yes/No]
+- **Security headers**: [CSP, HSTS, X-Frame-Options, etc.]
+- **Error handling**: [No sensitive info in errors]
+- **Default accounts**: [No default/test credentials]
+- **Tests**: [Configuration security tests]
+
+#### A06: Vulnerable Components
+- **Risk**: [High/Medium/Low]
+- **Dependencies scanned**: [Yes/No - tool used]
+- **Known CVEs**: [Count and severity from scan]
+- **Update plan**: [If vulnerabilities found]
+- **Monitoring**: [Dependabot, Snyk, etc.]
+- **Tests**: [Dependency security checks]
+
+#### A07: Identification and Authentication Failures
+- **Risk**: [High/Medium/Low]
+- **Auth mechanism**: [OAuth2/JWT/Session/etc.]
+- **Session management**: [Secure/reviewed - timeout, rotation]
+- **Password policy**: [Requirements if applicable]
+- **MFA**: [Required/Optional/Not applicable]
+- **Brute force protection**: [Rate limiting, account lockout]
+- **Tests**: [Authentication tests, session tests]
+
+#### A08: Software and Data Integrity Failures
+- **Risk**: [High/Medium/Low]
+- **Integrity checks**: [Where implemented - signatures, checksums]
+- **Code signing**: [Yes/No]
+- **CI/CD security**: [Pipeline reviewed, secrets management]
+- **Supply chain**: [Trusted sources, verification]
+- **Tests**: [Integrity validation tests]
+
+#### A09: Security Logging and Monitoring Failures
+- **Risk**: [High/Medium/Low]
+- **Security events logged**: [List what's tracked]
+- **Audit trail**: [What's tracked for compliance]
+- **No sensitive data**: [Verified - no passwords/tokens in logs]
+- **Alerting**: [Security alerts configured]
+- **Log retention**: [Duration and compliance]
+- **Tests**: [Logging tests, no sensitive data tests]
+
+#### A10: Server-Side Request Forgery (SSRF)
+- **Risk**: [High/Medium/Low]
+- **External requests**: [Where made in code]
+- **URL validation**: [Whitelist/validation rules]
+- **Network restrictions**: [Firewall rules, VPC]
+- **Input sanitization**: [User-controlled URLs]
+- **Tests**: [SSRF prevention tests]
+
+### Feature-Specific Security Risks
+
+1. **Risk**: [Specific risk for this feature]
+   - **Likelihood**: High/Medium/Low
+   - **Impact**: High/Medium/Low
+   - **Attack vector**: [How this could be exploited]
+   - **Mitigation**: [Specific solution]
+   - **Evidence**: [Research source showing this risk]
+   - **Tests**: [Security test scenarios]
+   - **Monitoring**: [How to detect attacks]
+
+2. **Risk**: [Next risk]
+   - [...]
+
+### Security Test Scenarios (TDD)
+
+1. **Test**: Unauthorized access attempt should fail
+   - **File**: `test/security/access-control.test.ts`
+   - **Scenario**: User tries to access another team's data
+   - **Expected**: 403 Forbidden, no data leak
+
+2. **Test**: SQL injection attempt should be blocked
+   - **File**: `test/security/injection.test.ts`
+   - **Scenario**: Malicious input in query parameter
+   - **Expected**: Input sanitized, no SQL execution, error logged
+
+3. **Test**: XSS attempt should be sanitized
+   - **File**: `test/security/xss.test.ts`
+   - **Scenario**: Script tag in user input
+   - **Expected**: HTML escaped, no script execution
+
+4. **Test**: [Additional security tests]
+   - [...]
+
+## Scope Assessment
+
+- **Type**: Tactical / Strategic
+  - **Rationale**: [Why this classification]
+  - **OpenSpec needed**: Yes / No
+
+- **Complexity**: Low / Medium / High
+  - **Rationale**: [Number of files, systems involved, dependencies]
+  - **Estimated effort**: [Without time, describe scope]
+
+- **Parallel opportunity**: Yes / No
+  - **Rationale**: [Independent tracks available?]
+  - **Tracks**: [If yes, list potential parallel tracks]
+
+- **Estimated files**: [Count]
+  - **New files**: [List]
+  - **Modified files**: [List]
+
+- **Dependencies**:
+  - **Internal**: [Other features/modules]
+  - **External**: [Third-party libraries]
+  - **Blockers**: [Any blocking dependencies]
+
+- **Security risk level**: Low / Medium / High / Critical
+  - **Rationale**: [Based on OWASP analysis]
+  - **Mitigation priority**: [When to address]
+
+## Next Steps
+
+1. **If Strategic**: Create OpenSpec proposal
+   - `openspec proposal create <feature-slug>`
+   - Write proposal.md, tasks.md, plan.md
+   - Reference this research doc for evidence
+
+2. **Create Beads issue**:
+   - `bd create "<feature-name>"`
+   - Link to this research doc
+   - Link to OpenSpec if strategic
+
+3. **Create branch**:
+   - `git checkout -b feat/<feature-slug>`
+
+4. **Proceed to /plan**:
+   - Read this research doc
+   - Create formal implementation plan
+   - Wait for OpenSpec approval if strategic
+
+## Research Checklist
+
+- [ ] Codebase exploration complete
+- [ ] parallel-web-search web research complete (multiple sources)
+- [ ] Context7 library documentation reviewed
+- [ ] Case studies analyzed
+- [ ] All key decisions documented with evidence
+- [ ] TDD test scenarios identified upfront
+- [ ] OWASP Top 10 analysis complete
+- [ ] Feature-specific security risks identified
+- [ ] Security test scenarios defined
+- [ ] Scope assessment complete
+- [ ] Next steps clear
+
+---
+
+**Note**: This research document serves as the single source of truth for all architectural and implementation decisions. Reference it throughout the development lifecycle (in OpenSpec proposals, PR descriptions, code reviews, and documentation).

package/docs/{ROADMAP.md → reference/ROADMAP.md}

@@ -1,6 +1,9 @@
 # Forge Enhancement Roadmap
 
-**Comprehensive implementation plan for transforming Forge into a fully automated, orchestrated workflow system.**
+> Historical design artifact. Do not use this page for current package release planning, command availability, or public positioning. Current public release guidance lives in [Release Reference](RELEASE.md), [CHANGELOG](../../CHANGELOG.md), [Workflow templates](../guides/WORKFLOW_TEMPLATES.md), and [Skills and command projections](SKILLS.md).
+> Historical snapshot: this roadmap is preserved for context only. Current public release guidance lives in [Release Reference](RELEASE.md), [CHANGELOG](../../CHANGELOG.md), and the runtime building-block work under `docs/work/2026-04-28-skeleton-pivot/`. References to `v3`, `/research`, or old PR sequences are historical/internal labels, not current package release instructions.
+
+**Historical implementation plan for an earlier automation-heavy Forge direction.**
 
 **Plan Created**: 2026-02-10
 **Status**: Phase 2 complete. PRs 0-6 merged, PR7-PR8 pending.
@@ -22,7 +25,7 @@
 
 ## Overview
 
-Transform Forge from a documentation-driven workflow into a fully automated, orchestrated workflow system with:
+Historical goal from this snapshot:
 
 - ✅ **Enhanced Multi-Agent Support**: Universal AGENTS.md + 8 supported agents (Claude Code, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)
 - ✅ **Comprehensive Testing**: 80%+ code coverage, E2E tests, mutation testing
@@ -175,7 +178,7 @@ PR0 (Simplification) → PR1 (Fixes) → PR2 (Security) → PR3 (Test Infra)
 
 ### **PR5: Advanced Testing Expansion** 🔬
 **Beads Issue**: `forge-01p`
-**Research**: [docs/research/advanced-testing.md](docs/research/advanced-testing.md) (PR #36)
+**Research**: historical `docs/research/advanced-testing.md` (PR #36)
 **Status**: Research complete, ready for `/plan`
 **Timeline**: 2-3 days
 **Impact**: Medium
@@ -204,7 +207,7 @@ PR0 (Simplification) → PR1 (Fixes) → PR2 (Security) → PR3 (Test Infra)
 
 ### **PR6: Plugin Architecture & Smart Recommendations** 🔌
 **Beads Issue**: `forge-a7n`
-**Research**: [docs/research/plugin-architecture.md](docs/research/plugin-architecture.md) (PR #37)
+**Research**: historical `docs/research/plugin-architecture.md` (PR #37)
 **Status**: Research complete, ready for `/plan`
 **Timeline**: 4-5 days
 **Impact**: High (flagship feature)
@@ -310,7 +313,7 @@ Each PR follows the Forge workflow:
 
 - **Master Plan**: `docs/plans/*.md` (global, tracked by Claude Code)
 - **Roadmap**: `docs/ROADMAP.md` (repository, git-tracked)
-- **Beads Tracking**: `.beads/issues.jsonl` (git-tracked)
+- **Beads Tracking**: `.beads/` local runtime state; shared tracking must use sync/server authority or explicit projection/import artifacts.
 
 ---
 
@@ -336,8 +339,8 @@ Each PR is self-contained and can be rolled back independently:
 1. ✅ **PR4 Completed** — CLI command automation merged (PR #33)
 
 2. ✅ **Research complete** for PR5 and PR6:
-   - PR5 research: [docs/research/advanced-testing.md](docs/research/advanced-testing.md) (PR #36)
-   - PR6 research: [docs/research/plugin-architecture.md](docs/research/plugin-architecture.md) (PR #37)
+   - PR5 research: historical `docs/research/advanced-testing.md` (PR #36)
+   - PR6 research: historical `docs/research/plugin-architecture.md` (PR #37)
    - PR6 scope expanded: smart plugin recommendations, CLI-first, pricing transparency
    - forge-mlm absorbed into PR5.5 + PR6 + PR8
 
@@ -349,8 +352,8 @@ Each PR is self-contained and can be rolled back independently:
 
 - **Master Plan**: `docs/plans/*.md`
 - **Beads Issues**: `forge list` or `forge show <issue-id>`
-- **Workflow Guide**: [AGENTS.md](../AGENTS.md)
-- **Architecture Docs**: Coming in PR0 - [ARCHITECTURE.md](./ARCHITECTURE.md)
+- **Workflow Guide**: [AGENTS.md](../../AGENTS.md)
+- **Architecture Docs**: historical PR0 placeholder, superseded by [Docs Index](../INDEX.md)
 
 ---
 

package/docs/reference/SKILLS.md

@@ -0,0 +1,35 @@
+# Skills And Command Projections
+
+Forge uses both skills and command files today. They are related, but they are not the same surface.
+
+## Current v0.0.11 Reality
+
+- Codex stage workflows are packaged as `.codex/skills/<stage>/SKILL.md`.
+- Claude Code and Cursor receive command projections. Forge currently supports Claude Code, Codex, and Cursor; Hermes support is planned.
+- `scripts/check-agents.js` currently treats Codex as the exception where command capability is satisfied through `.codex/skills/`.
+- `test/agent-gaps.test.js` still asserts `.claude/commands/` as the current canonical sync source for command projection checks.
+
+That means `docs/reference/COMMANDS.md` should remain the CLI command reference. It should not be renamed into a skills reference until the source, sync script, tests, and package contents move together.
+
+## Product Direction
+
+The intended direction is skills-first agent packaging:
+
+- Stage behavior becomes portable `SKILL.md` packages.
+- Command files become harness-specific projections or compatibility aliases.
+- `skills sync` and Forge setup project the same stage behavior into each supported harness.
+- Extension manifests can contribute stages, substages, evaluator regions, adapters, hooks, and evidence collectors.
+
+This direction is documented as roadmap material until the implementation and tests make it current behavior.
+
+## Documentation Rule
+
+Use these names consistently:
+
+- Command reference: current `forge` CLI commands and package binaries.
+- Workflow templates: default stage paths and customization rules.
+- Skills: agent-facing stage packages and future portable extension units.
+- Harness projections: generated command, prompt, workflow, or skill files for a specific agent.
+
+Do not claim that commands have fully moved to skills until source, tests, generated files, and package contents prove that migration.
+

package/docs/reference/STATUS_BOARD.md

@@ -0,0 +1,80 @@
+# Status And Board
+
+`forge status` is a local personal focus surface. With no arguments it reads git context plus local Beads runtime files and shows active assigned work, ready work, blocked work, stale work, recent completions, and workflow state when available.
+
+`forge board` is a local team runtime board. It consumes the same snapshot as `forge status` and groups all local issues into active, ready, blocked, stale, and recent completion columns.
+
+## JSON Mode
+
+Both commands support `--json`.
+
+```bash
+forge status --json
+forge board --json
+```
+
+The JSON shape mirrors each command's human sections:
+
+- `forge status --json` returns `context`, `personal`, `workflow` when detected, and `limits`.
+- `forge board --json` returns `context`, `board`, and `limits`.
+- `personal` contains the status-focused issue groups for the current developer.
+- `board` contains the team issue groups over the same local snapshot.
+
+## Sample Output
+
+```text
+Context
+  Branch: codex/0.0.18-team-status
+  Worktree: linked
+  Working tree: clean
+
+Active Issues
+  forge-sxg2 0.0.18 forge status command for personal work focus [in_progress]
+
+Ready
+  forge-next Follow-up issue
+
+Blocked
+  forge-11ds 0.0.18 team runtime board [open]
+
+Stale
+  none
+
+Recent Completions
+  forge-besw.12 0.0.17 insights and recap
+
+Workflow
+  Development (dev)
+  Run now: /dev
+  Next after this: /validate
+```
+
+```text
+Team Runtime Board
+Source: local Beads runtime state
+Branch: codex/0.0.18-team-status
+Working tree: clean
+
+Active
+  forge-sxg2 0.0.18 forge status command for personal work focus [in_progress]
+
+Ready
+  none
+
+Blocked
+  forge-11ds 0.0.18 team runtime board [open]
+
+Stale
+  none
+
+Recent Completions
+  forge-besw.12 0.0.17 insights and recap
+```
+
+## Limits
+
+These commands are read-only and local. They do not create orchestration, mutate issue state, query GitHub, inspect review providers, infer CI health, or sync remote project fields. The data is only as current as `.beads/issues.jsonl` in the current checkout.
+
+## Non-Scope
+
+This surface does not implement ReviewAdapter, IssueAdapter, GitHub sync, GitHub Projects v2, sprint velocity, or remote review-response detection.

package/docs/reference/TEMPLATES.md

@@ -0,0 +1,106 @@
+# Adoption Templates
+
+Forge templates are adoption scaffolds over runtime graph primitives. They are not the product surface: the generated `.forge/config.yaml` stays inspectable with `forge options`.
+
+## Entry Point
+
+```bash
+forge init
+forge init --yes
+forge init --profile minimal --classification standard --harness codex --yes
+```
+
+`forge init` is the day-one entry door for fresh repositories. It creates the local `.forge/` skeleton without assuming a prior v2 install or running the `forge new` onboarding wizard.
+
+Generated files:
+
+- `.forge/config.yaml` records the adoption profile, default classification, Layer 1 rail confirmation, and harness targets.
+- `.forge/patch.md` is an empty patch-intent placeholder for future local overrides.
+- `.forge/protected-paths.yaml` records the protected path manifest scaffold. Currently, only the manifest structure is generated; protected-state enforcement is not yet implemented.
+
+When run interactively, `forge init` asks for:
+
+- default classification: `critical`, `standard`, or `refactor`.
+- Layer 1 rail confirmation.
+- harness targets: `claude`, `cursor`, and/or `codex`.
+
+Harness defaults are detected from filesystem markers where supported:
+
+- `.claude` selects `claude`.
+- `.cursor` selects `cursor`.
+- `.codex` selects `codex`.
+
+`forge init --yes` is deterministic for automation: it uses the `standard` profile, `standard` classification, confirms Layer 1 rails, and selects detected harness targets or `codex` when none are detected.
+
+`forge init` does not overwrite existing generated files. Re-run with `--force` only when replacing `.forge/config.yaml`, `.forge/patch.md`, and `.forge/protected-paths.yaml` is intentional.
+
+Profile shortcuts remain available:
+
+```bash
+forge init --minimal
+forge init --standard
+forge init --full
+```
+
+`forge setup --minimal` remains a separate shortcut for repositories that want setup behavior rather than only the day-one `.forge/` skeleton.
+
+Stage commands such as `/review` and `/verify` are agent workflow stages. Do not present them as standalone `forge review` or `forge verify` CLI commands unless those commands exist in the current CLI registry. Pre-merge is not a stage or a `/premerge` command — it is a documentation-and-handoff gate embedded in `/ship` and `/review`.
+
+## Planning Template
+
+`/plan` is represented as a configurable planning template in the runtime graph. The default template runs the full planning loop:
+
+- `plan.intent_capture`
+- `plan.parallel_research`
+- `plan.parallel_critics`
+- `plan.synthesis`
+- `plan.final_lock`
+
+Projects can tune planning depth in `.forge/config.yaml` without introducing another planner-specific config file:
+
+```yaml
+planning:
+  template:
+    mode: partial
+    convergenceThreshold: 0.8
+    criticSet:
+      - spec
+      - security
+    partialInvocation:
+      only:
+        - plan.parallel_critics
+      skip:
+        - plan.parallel_research
+```
+
+Inspect the resolved behavior with:
+
+```bash
+forge options why plan.parallel_critics
+forge options diff
+forge options lint
+```
+
+Invalid planning modes, thresholds outside `0..1`, blank critics, and unknown planning sub-skills fail through `forge options lint`.
+
+## Profiles
+
+| Profile | Purpose | Output |
+|---------|---------|--------|
+| `minimal` | Smallest adoption skeleton for a clean repository. | Writes the day-one `.forge/` files with workflow gates and issue adapters disabled unless selected later. |
+| `standard` | Default Forge command flow metadata. | Writes the day-one `.forge/` files with default gates enabled and Beads/GitHub issue adapter metadata. |
+| `full` | Explicit full scaffold. | Writes the day-one `.forge/` files with rails, gates, adapters, and protected paths made explicit. |
+
+## Inspect The Result
+
+```bash
+forge options lint
+forge options diff
+forge options stages --json
+```
+
+The generated config includes `template.kind`, `template.version`, `template.profile`, and `template.ancestry` so users can see which scaffold produced the current defaults.
+
+## Non-Scope
+
+This flow does not implement harness translation, adapter marketplace installation, upgrade or rollback, guaranteed protected-state enforcement in every repository, `forge new`, or patch intent execution.