forge-workflow 0.0.10 → 0.1.0-beta.3

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Project Workflow Instructions
 
-## 7-Stage TDD-First Workflow
+## Default TDD-First Workflow Template
 
-This project enforces a **strict TDD-first development workflow** with 7 stages:
+This project ships a **default TDD-first workflow template** with 6 workflow stages plus a composable **research** skill (a phase of `/plan` and usable standalone). In v3, these stages are one configurable composition over Forge runtime building blocks, not a product-wide mandatory ladder. Commands may be invoked as full stages or as smaller skill fragments when the active plan permits it. Pre-merge is an embedded gate in `/ship` and `/review` (not a numbered stage); `/status` and `/shepherd` are utilities (not stages).
 
 | Stage | Command     | Purpose                                                   | Required For |
 |-------|-------------|-----------------------------------------------------------|--------------|
@@ -11,24 +11,27 @@ This project enforces a **strict TDD-first development workflow** with 7 stages:
 | 3     | `/validate`    | Validate + 4-phase debug mode on failure                    | All types    |
 | 4     | `/ship`     | Create PR with documentation                             | All types    |
 | 5     | `/review`   | Address ALL PR feedback                                  | Critical, Standard |
-| 6     | `/premerge` | Complete docs on feature branch, hand off PR             | All types    |
-| 7     | `/verify`   | Post-merge health check (CI, deployments)                | All types    |
+| 6     | `/verify`   | Post-merge health check (CI, deployments)                | All types    |
+
+**Pre-merge gate (not a numbered stage)**: Completing docs on the feature branch and handing off the PR for merge is a **task-type gate and checkpoint**, not a standalone workflow stage. The gate runs for Critical, Standard, and Refactor work and is embedded in the `/ship` and `/review` stages — finish the doc updates, confirm CI is green, then hand off the PR. Simple, Hotfix, and Docs work skip the gate.
 
 **Utility**: `/status` — Context check before starting work (not a numbered stage)
 
+**Utility**: `/shepherd <pr>` — Monitor-driven PR shepherd: one bounded pass that reads CI and check state, re-runs a flaky required check (Tier-A), or escalates, then hands off. It is a utility command, **not** a workflow stage, and does not sit between `/review` and the handoff. It **never merges** (the human merges in the GitHub UI) and **never resolves review threads** (that stays with `/review`). `--auto-rebase` is opt-in and default OFF. See [docs/reference/shepherd.md](docs/reference/shepherd.md).
+
 ## Automatic Change Classification
 
 When the user requests work, **you MUST automatically classify** the change type:
 
-### Critical (Full 7-stage workflow)
+### Critical (Full default workflow template)
 **Triggers:** Security, authentication, payments, breaking changes, new architecture, data migrations
 **Example:** "Add OAuth login", "Migrate database schema", "Implement payment gateway"
-**Workflow:** plan → dev → validate → ship → review → premerge → verify
+**Workflow:** plan → dev → validate → ship → review → verify (pre-merge gate before merge)
 
-### Standard (6-stage workflow)
+### Standard (default workflow without post-merge verify)
 **Triggers:** Normal features, enhancements, new components
 **Example:** "Add user profile page", "Create notification system"
-**Workflow:** plan → dev → validate → ship → review → premerge
+**Workflow:** plan → dev → validate → ship → review (pre-merge gate before merge)
 
 ### Simple (3-stage workflow, skip plan)
 **Triggers:** Bug fixes, UI tweaks, small changes, minor refactors
@@ -48,7 +51,7 @@ When the user requests work, **you MUST automatically classify** the change type
 ### Refactor (5-stage workflow for safe cleanup)
 **Triggers:** Code cleanup, performance optimization, technical debt reduction
 **Example:** "Refactor auth service", "Extract utility functions"
-**Workflow:** plan → dev → validate → ship → premerge
+**Workflow:** plan → dev → validate → ship (pre-merge gate before merge)
 
 ## Enforcement Philosophy
 
@@ -66,7 +69,7 @@ When the user requests work, **you MUST automatically classify** the change type
 
 "Skipping tests creates technical debt. I'll:
  ✓ Allow this commit
- ✓ Create follow-up Beads issue for tests
+ ✓ Create follow-up issue for tests
  ✓ Document in commit message as [tech-debt]
 
  Proceed?"
@@ -75,11 +78,11 @@ When the user requests work, **you MUST automatically classify** the change type
 
 Command files (`.claude/commands/*.md` and agent equivalents) must never hardcode example output when a script generates that output dynamically. Reference the script and describe what it does — don't duplicate its output with fake data that becomes stale.
 
-## TDD Development (Stage 2: /dev)
+## TDD Development (`/dev` Command)
 
 **Subagent-driven per-task implementation loop:**
 
-1. **Read task list** → Pre-made task list from `/plan` Phase 3 at `docs/plans/YYYY-MM-DD-<slug>-tasks.md`
+1. **Read task list** → Pre-made task list from `/plan` Phase 3 at `docs/work/YYYY-MM-DD-<slug>/tasks.md`
 2. **Dispatch implementer subagent per task** → Fresh context, complete task text, relevant design doc sections
 3. **TDD inside implementer** → RED-GREEN-REFACTOR enforced by HARD-GATE:
    - RED: Write failing test first (must run test and show failing output)
@@ -92,8 +95,8 @@ Command files (`.claude/commands/*.md` and agent equivalents) must never hardcod
 **Example execution:**
 ```
 /dev starts:
-  ✓ Read task list: docs/plans/2026-02-26-stripe-billing-tasks.md (8 tasks)
-  ✓ Created decisions log: docs/plans/2026-02-26-stripe-billing-decisions.md
+  ✓ Read task list: docs/work/2026-02-26-stripe-billing/tasks.md (8 tasks)
+  ✓ Created decisions log: docs/work/2026-02-26-stripe-billing/decisions.md
 
 Task 1: Types and interfaces
   ✓ Implementer: test written → failing → implementation → passing → committed
@@ -112,13 +115,13 @@ Task 2: Validation logic
 
 ## State Management (Single Source of Truth)
 
-> GitHub issue lifecycle may sync to Beads via CI -- see [docs/BEADS_GITHUB_SYNC.md](docs/BEADS_GITHUB_SYNC.md).
+> GitHub issue lifecycle may sync to Beads via CI -- see [docs/guides/BEADS_GITHUB_SYNC.md](docs/guides/BEADS_GITHUB_SYNC.md).
 
-**All workflow state stored in Beads metadata** (survives compaction):
+**Current implementation**: The Forge Kernel is the default issue-state authority; issue commands read and write the kernel store unless Beads is explicitly selected (`--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, or `issueBackend: beads` in `.forge/config.yaml`), where it serves as an import/export/projection compatibility layer. **Direction (D44)**: continue consolidating issue/workflow/run authority in the Kernel with Beads remaining a compatibility projection. New authority work must follow [docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md](docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md) and [docs/reference/FORGE_KERNEL_STORAGE_MODEL.md](docs/reference/FORGE_KERNEL_STORAGE_MODEL.md).
 
 ```json
 {
-  "id": "bd-x7y2",
+  "id": "9f2c41d7-3a8e-4b6f-9c21-5e7d0a184c3b",
   "type": "critical",
   "currentStage": "dev",
   "completedStages": ["plan"],
@@ -139,38 +142,98 @@ Task 2: Validation logic
 }
 ```
 
-## Git Hooks (Automatic Enforcement)
+## Git Hooks & Push Workflow (Automatic Enforcement)
+
+This project uses the **Professional Git Workflow** with Lefthook for automated quality gates.
 
 **Pre-commit hook enforces TDD:**
 - Blocks commits if source code modified without test files
 - Offers guided recovery (add tests now, skip with tech debt tracking, emergency override)
 - No AI decision required - automatic validation
+- **Strong default, not a hard floor.** The TDD gate is the default-ON `rail.tdd_intent` rail; turn it off with `forge gate disable rail.tdd_intent` (the `minimal` adoption profile ships it off). The installed hooks read the resolved config at run time, so a disabled rail makes them genuinely inert — enforcement honestly follows your config.
 
 **Pre-push hook validates tests:**
+- Branch protection: blocks direct push to `main`/`master`
+- ESLint: blocks on errors and warnings (strict mode, `--max-warnings 0`)
 - All tests must pass before push
 - Can skip for hotfixes with documentation
 
+**Pull Request workflow:**
+- PR template auto-fills with a standardized format; the self-review checklist catches most bugs before review
+- Reference the issue id in the PR body (e.g. the Forge Kernel issue id); **all review comments must be resolved** before merge
+- Squash-only merging for a clean, linear history
+
+**⚠️ AI agents must NEVER use `LEFTHOOK=0`, `--no-verify`, or any hook bypass.** If a hook fails, fix the underlying issue. Only humans may bypass hooks in emergencies, documented in the PR description.
+
+**Preferred push workflow (AI agents and humans):**
+
+```bash
+forge push                    # Branch protection + lint + tests, then push
+forge push --quick            # Review-cycle: lint-only push (CI runs full suite)
+forge worktree create <slug>  # Create a worktree
+forge test                    # Run tests with correct timeouts
+forge sync                    # Sync issue data
+forge clean                   # Remove merged worktrees
+```
+
+## Build, Shell, and MCP
+
+**Package manager**: Bun (preferred for performance).
+
+```bash
+bun install      # Install dependencies
+bun run dev      # Start development
+bun run build    # Production build
+bun test         # Run tests
+```
+
+**GitHub CLI**: `gh auth login` for the PR workflow.
+
+### Shell Model
+
+| Platform | Shell used by Forge commands and scripts |
+| --- | --- |
+| Windows | Git Bash for helper-backed Forge stage flows |
+| macOS/Linux | Default login shell |
+
+On Windows, Forge runtime health enforces Git Bash for helper-backed stage flows. Native PowerShell is still used by some bootstrap paths, and WSL may be useful for adjacent development tasks. See [docs/reference/TOOLCHAIN.md](docs/reference/TOOLCHAIN.md#shell-model).
+
+### MCP Servers (Optional)
+
+If your agent supports MCP, these enhance research:
+
+- **Context7** - up-to-date library documentation and API reference
+- **grep.app** - search 1M+ GitHub repos for real-world code examples
+
+See [.mcp.json.example](.mcp.json.example) for configuration (Claude Code: copy it to `.mcp.json`) and [docs/reference/TOOLCHAIN.md](docs/reference/TOOLCHAIN.md) for detailed setup.
+
 ## Documentation Index (Context Pointers)
 
-**Detailed command instructions** are located in:
-- [.claude/commands/status.md](.claude/commands/status.md) - How to check current context (utility)
-- [.claude/commands/plan.md](.claude/commands/plan.md) - How to plan features (3 phases: design intent + research + branch/worktree/tasks)
-- [.claude/commands/dev.md](.claude/commands/dev.md) - How to implement with subagent-driven TDD and decision gate
-- [.claude/commands/validate.md](.claude/commands/validate.md) - How to run validation (with HARD-GATE exit)
-- [.claude/commands/ship.md](.claude/commands/ship.md) - How to create PRs
-- [.claude/commands/review.md](.claude/commands/review.md) - How to address PR feedback (with HARD-GATE exit)
-- [.claude/commands/premerge.md](.claude/commands/premerge.md) - How to complete docs and hand off PR for merge
-- [.claude/commands/verify.md](.claude/commands/verify.md) - How to verify post-merge health
+**Detailed stage skill instructions** are located in:
+- [skills/status/SKILL.md](skills/status/SKILL.md) - How to check current context (utility)
+- [skills/plan/SKILL.md](skills/plan/SKILL.md) - How to plan features (3 phases: design intent + research + branch/worktree/tasks)
+- [skills/dev/SKILL.md](skills/dev/SKILL.md) - How to implement with subagent-driven TDD and decision gate
+- [skills/validate/SKILL.md](skills/validate/SKILL.md) - How to run validation (with HARD-GATE exit)
+- [skills/ship/SKILL.md](skills/ship/SKILL.md) - How to create PRs
+- [skills/review/SKILL.md](skills/review/SKILL.md) - How to address PR feedback (with HARD-GATE exit)
+- [skills/shepherd/SKILL.md](skills/shepherd/SKILL.md) - How to run a bounded PR monitor pass (utility; never merges, never resolves threads)
+- [skills/verify/SKILL.md](skills/verify/SKILL.md) - How to verify post-merge health
 
 **Planning documents** (created by `/plan`, consumed by `/dev`):
-- `docs/plans/YYYY-MM-DD-<slug>-design.md` - Design intent + technical research
-- `docs/plans/YYYY-MM-DD-<slug>-tasks.md` - Task list with TDD steps
-- `docs/plans/YYYY-MM-DD-<slug>-decisions.md` - Decisions log from /dev
+- `docs/work/YYYY-MM-DD-<slug>/plan.md` - Design intent + technical research
+- `docs/work/YYYY-MM-DD-<slug>/tasks.md` - Task list with TDD steps
+- `docs/work/YYYY-MM-DD-<slug>/decisions.md` - Decisions log from /dev
 
 **Comprehensive workflow guide:**
 - This file (AGENTS.md) is the single source of truth for the complete workflow
-- [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) - Tool setup and configuration
-- [docs/VALIDATION.md](docs/VALIDATION.md) - Enforcement and validation details
+- [docs/reference/TOOLCHAIN.md](docs/reference/TOOLCHAIN.md) - Tool setup and configuration
+- [docs/reference/VALIDATION.md](docs/reference/VALIDATION.md) - Enforcement and validation details
+
+**Forge v3 / Kernel Plan (active design):**
+- [docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md](docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md) — canonical Forge Kernel authority reset plan for issue authority, local broker, team authority, adapters, storage, and gates
+- [docs/work/2026-04-28-skeleton-pivot/locked-decisions.md](docs/work/2026-04-28-skeleton-pivot/locked-decisions.md) — D1–D44 decisions ledger with rationale + tradeoffs + anti-decisions; D44 supersedes Beads-only authority portions of earlier decisions
+- [docs/work/2026-04-28-skeleton-pivot/v3-redesign-strategy.md](docs/work/2026-04-28-skeleton-pivot/v3-redesign-strategy.md) — historical v3 strategy and background; do not use its legacy default-substrate language over D44
+- See [docs/INDEX.md](docs/INDEX.md) for the full reading order across the v3 design folder
 
 **Load these files when you need detailed instructions for a specific stage.**
 
@@ -187,47 +250,40 @@ Every stage transition should carry structured context so the next stage (or a n
 | /validate  | All checks pass/fail summary | Failures diagnosed | Scripts/commands run | Ship readiness |
 | /ship      | PR created, checks pending | Template sections filled | PR URL, branch name | Review focus areas |
 | /review    | All feedback addressed | Comment resolutions | Fixed files, commit SHAs | Doc update needs |
-| /premerge  | Docs updated, CI green | N/A | Updated doc files | Merge instructions |
+| pre-merge gate | Docs updated, CI green | N/A | Updated doc files | Merge instructions |
 
-### Validation Command
+### Recording Stage Context
 
-Run at each stage exit to check for missing context:
+Record the stage-exit context as a kernel issue comment so the next stage (or a
+fresh session) can resume from the issue record itself:
 
 ```bash
-bash scripts/beads-context.sh validate <beads-issue-id>
+forge issue comment <issue-id> "stage: dev -> validate
+summary: All 5 tasks done, 1 decision gate fired
+decisions: Used streaming parser over DOM for memory efficiency
+artifacts: lib/parser.js test/parser.test.js
+next: Run lint first — streaming approach may trigger no-await rule"
 ```
 
-This checks: (1) issue has a description, (2) at least one stage transition exists, (3) most recent transition has a summary, (4) design metadata is set if past the plan stage. Exits 0 when context checks run (even if warnings are found); exits 1 only if the issue cannot be retrieved.
+Check-after-write verification (`gate.issue_verify`, default-on) confirms the
+comment actually landed. Read context back with `forge show <issue-id>` (or
+`forge recap <issue-id>` for the bounded orientation envelope).
 
 ### Field Definitions
 
 - **Summary**: 1-2 sentence recap of what was accomplished in this stage. Example: `--summary "All 5 tasks done, 1 decision gate fired"`
 - **Decisions**: Key choices made during this stage that affect downstream work. Example: `--decisions "Used streaming parser over DOM for memory efficiency"`
-- **Artifacts**: File paths or URLs produced by this stage. Example: `--artifacts "lib/parser.js test/parser.test.js docs/plans/2026-03-26-parser-design.md"`
+- **Artifacts**: File paths or URLs produced by this stage. Example: `--artifacts "lib/parser.js test/parser.test.js docs/work/2026-03-26-parser/plan.md"`
 - **Next**: Guidance for the next stage on what to focus on. Example: `--next "Run lint first — streaming approach may trigger no-await rule"`
 
-### Usage in Stage Transitions
-
-```bash
-# Basic (backward compatible)
-bash scripts/beads-context.sh stage-transition <id> dev validate
-
-# With context fields (recommended)
-bash scripts/beads-context.sh stage-transition <id> dev validate \
-  --summary "All 5 tasks done, 0 gates fired" \
-  --decisions "Used approach A per design doc" \
-  --artifacts "lib/foo.js test/foo.test.js" \
-  --next "Run type check and lint"
-```
-
 ### Enforcement Level
 
-This convention is **advisory only**. The `validate` subcommand prints warnings but always exits 0. It does not block any stage transition. The goal is to build good habits, not to create friction.
+This convention is **advisory only** — missing fields never block a stage
+transition. The goal is to build good habits, not to create friction.
 
-<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
-## Beads Issue Tracker
+## Forge Issue Tracker
 
-This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+This project uses the **Forge Kernel** for issue tracking. Run `forge prime` to see full workflow context and commands.
 
 ### Quick Reference
 
@@ -238,11 +294,46 @@ forge claim <id>      # Claim work
 forge close <id>      # Complete work
 ```
 
+**More commands worth knowing** (run `forge <command> --help` for full usage):
+
+```bash
+forge remember <note>          # Persist a project-memory note to a file-backed store
+forge recall [query]           # Retrieve project-memory notes back (the read half of remember)
+forge insights                 # Detect recurring evidence patterns, suggest conservative follow-ups
+forge upgrade                  # Preview and self-heal safe Forge upgrade readiness
+forge gate <verb> <gate-id>    # Toggle a workflow gate, or record/query human-gate approval events
+forge role <role> --use <skill> # Bind a role to a skill/ideology in .forge/config.yaml
+forge merge --auto <pr>        # Opt-in conditional auto-merge — merges only when configured rules pass (OFF by default)
+```
+
 ### Rules
 
-- Use `forge` as the routine command surface for bd-backed issue tracking and sync workflows — do NOT use TodoWrite, TaskCreate, or markdown TODO lists. Exception: `/plan` Phase 3 generates task lists at `docs/plans/YYYY-MM-DD-<slug>-tasks.md` — these are approved artifacts consumed by `/dev`, but Beads (`bd`) remains the source of truth for issue state and IDs. Use `bd` directly only for operations Forge does not wrap yet, such as `bd init`, `bd comments`, `bd dep`, and `bd dolt *`. GitHub issues may be used for external/public tracking; CI may sync GitHub issue lifecycle to Beads (see `docs/BEADS_GITHUB_SYNC.md`).
-- Run `bd prime` for detailed command reference and session close protocol
-- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+- Use `forge` as the routine command surface for issue tracking and sync workflows — do NOT use TodoWrite, TaskCreate, or markdown TODO lists. Exception: `/plan` Phase 3 generates task lists at `docs/work/YYYY-MM-DD-<slug>/tasks.md` — these are approved artifacts consumed by `/dev`. New issue-authority work routes through the Forge Kernel design. Use `forge issue` subcommands (e.g. `forge issue dep`, `forge issue comment`) for operations beyond the shortcuts above. GitHub issues may be used for external/public tracking; CI may sync GitHub issue lifecycle to the issue store.
+- Run `forge prime` for detailed command reference and session close protocol
+- Use `forge remember` for persistent knowledge and `forge recall` to retrieve it back — do NOT use MEMORY.md files
+
+### Kernel Tracking (nothing discussed goes missing)
+
+**NON-NEGOTIABLE, default-on.** Anything raised in a session — a bug, an idea, a
+design decision, a follow-up, a TODO, a risk noticed in passing — MUST become a
+Forge Kernel issue **immediately** via `forge issue create`, before it can be
+forgotten. Triage it (set a type, link its epic/parent) so it is discoverable.
+When you defer scope, file the follow-up issue and reference it — never leave
+work unfiled. The Kernel is the single source of truth; do NOT substitute
+TodoWrite, markdown TODO lists, or memory notes for a filed issue.
+
+This policy is canonicalized in `rules/kernel-tracking.md` (rendered to every
+port: `.cursor/rules/kernel-tracking.mdc` for Cursor, this projection for
+Claude/Codex/Hermes) and governed by the default-on `rail.kernel_tracking`
+runtime rail. Turn it off only deliberately: `forge gate disable rail.kernel_tracking`.
+
+## Project Learnings
+
+- **Scope discipline**: Do ONLY what was explicitly asked. Answer a question → stop. Check something → stop. Never auto-continue to next steps or pending work unless told to.
+- **Stage names**: The validation stage command is `/validate` — renamed in PR #50; do not use the old name.
+- **Unused params**: Prefix with `_` (e.g., `_searchTerm`) — ESLint `no-unused-vars` enforced with `--max-warnings 0`.
+- **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state. Fix the root cause — never use `LEFTHOOK=0`.
+- **Skill sync**: Canonical skills live in `skills/<name>/SKILL.md`; per-agent copies are generated from them. `.agents/skills` (Codex's repo-local discovery path) is committed so a fresh clone gets discovery without `forge setup` — a pre-commit hook keeps it byte-identical to `skills/` and the drift gate enforces it. The other mirrors (`.claude/skills`, `.codex/skills`, `.cursor/skills`, `.hermes/skills`) are gitignored and regenerated at `forge setup`. Never hand-edit a generated mirror — edit the canonical `skills/` source.
 
 ## Session Completion
 
@@ -256,7 +347,7 @@ forge close <id>      # Complete work
 4. **PUSH TO REMOTE** - This is MANDATORY:
    ```bash
     git pull --rebase
-    forge sync     # wraps the supported Beads sync flow when Beads is configured
+    forge sync     # wraps the supported issue-store sync flow when the issue store is configured
     git push
     git status  # MUST show "up to date with origin"
    ```
@@ -270,4 +361,3 @@ forge close <id>      # Complete work
 - NEVER say "ready to push when you are" - YOU must push
 - If push fails, resolve and retry until it succeeds
 - After fixing review feedback, always push the changes and resolve the related GitHub review threads via the GraphQL API before considering the work complete
-<!-- END BEADS INTEGRATION -->