forgedock 1.2.0 → 1.3.0

package/docs/site/configuration.md

@@ -0,0 +1,243 @@
+---
+title: "Configuration Reference — forge.yaml"
+description: "Complete forge.yaml schema reference for ForgeDock. All required and optional sections explained with examples."
+---
+
+# Configuration Reference — forge.yaml
+
+`forge.yaml` lives at your project root and tells ForgeDock commands how to interact with your project. Without it, commands cannot resolve your GitHub repository, paths, or branches.
+
+## Quick Start
+
+```bash
+# Option 1: Autopilot setup (recommended)
+npx forgedock init
+
+# Option 2: Manual setup
+cp forge.yaml.example forge.yaml
+# Edit forge.yaml with your project details
+echo "forge.yaml" >> .gitignore
+```
+
+`npx forgedock init` auto-detects most values from `git remote`, `package.json`, and `gh api`. You review the result on a single annotated screen.
+
+### `init` Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--manual` | Skip AI enrichment — shows detection baseline values only |
+| `--verbose` | Show each field's detection source and confidence rationale |
+
+---
+
+## Schema Overview
+
+| Section | Required | Purpose |
+|---------|----------|---------|
+| [`project`](#project-required) | **Yes** | GitHub identity (owner, repo, name) |
+| [`paths`](#paths-required) | **Yes** | Local filesystem locations |
+| [`branches`](#branches-required) | **Yes** | Branch naming conventions |
+| [`repos`](#repos-optional) | No | Multi-repository routing |
+| [`project_board`](#project_board-optional) | No | GitHub Projects v2 integration |
+| [`services`](#services-optional) | No | External service URLs and IDs |
+| [`review`](#review-optional) | No | Context injected into review agents |
+| [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
+| [`verification`](#verification-optional) | No | Health-check patterns |
+| [`billing`](#billing-optional) | No | Financial integrity audit |
+| [`adaptive_scripts`](#adaptive_scripts-optional) | No | Per-repo script override configuration |
+
+---
+
+## `project` (REQUIRED)
+
+Core identity fields used by every command that calls `gh issue`, `gh pr`, or `gh project`.
+
+```yaml
+project:
+  name: "Acme Platform"
+  owner: "acme-org"
+  repo: "acme-platform"
+  description: "SaaS platform for automated data processing"
+  # forge_repo: "acme-org/acme-forge"  # if pipeline lives in a separate repo
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Human-readable name used in pipeline reports and issue comments |
+| `owner` | string | **Yes** | GitHub org or username |
+| `repo` | string | **Yes** | Repository name. Combined as `owner/repo` = the `GH_REPO` in all commands |
+| `description` | string | No | One-line description used in issue templates |
+| `forge_repo` | string | No | Pipeline repo in `owner/repo` format when pipeline lives separately from the project being developed |
+
+---
+
+## `paths` (REQUIRED)
+
+Local filesystem paths for git worktree operations.
+
+```yaml
+paths:
+  root: "/home/youruser/projects/acme-platform"
+  worktree_base: "/home/youruser/projects/acme-platform/.claude/worktrees"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `root` | string (absolute) | **Yes** | Absolute path to the project root. Base for `git worktree add` |
+| `worktree_base` | string (absolute) | **Yes** | Directory where per-branch worktrees are created |
+
+---
+
+## `branches` (REQUIRED)
+
+Branch naming conventions that control PR targeting and source branch selection.
+
+```yaml
+branches:
+  default: "main"
+  staging: "staging"
+  feature_pattern: "milestone/{slug}"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `default` | string | **Yes** | Default branch (`main` or `master`) |
+| `staging` | string | **Yes** | Staging branch for fast-lane PRs (issues without a milestone) |
+| `feature_pattern` | string | **Yes** | Pattern for feature branches. `{slug}` = milestone title in kebab-case |
+
+**Lane routing**: Issues without a milestone → fast lane → PR targets `branches.staging`. Issues with a milestone → feature lane → PR targets `branches.feature_pattern`.
+
+---
+
+## `repos` (OPTIONAL)
+
+Multi-repository routing for projects that span multiple GitHub repos.
+
+```yaml
+repos:
+  default:
+    repo: "acme-org/acme-platform"
+    staging_branch: "staging"
+
+  satellites:
+    - prefix: "mcp"
+      repo: "acme-org/acme-mcp-server"
+      staging_branch: "main"
+      local_path: "/home/youruser/projects/acme-mcp-server"
+```
+
+Use `<prefix>:<issue_number>` syntax in commands: `mcp:5`, `sdk:12`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `satellites[].prefix` | string | **Yes** | Short prefix for issue routing |
+| `satellites[].repo` | string | **Yes** | Full `owner/repo` of the satellite repository |
+| `satellites[].staging_branch` | string | **Yes** | Target branch for fast-lane PRs |
+| `satellites[].local_path` | string | No | Absolute local path to the satellite repo |
+| `satellites[].billing_enabled` | boolean | No | Enable financial integrity audit for this satellite |
+
+---
+
+## `project_board` (OPTIONAL)
+
+GitHub Projects v2 integration. When configured, ForgeDock automatically adds issues to the board and updates Status, Lane, Component, Priority, and Workflow fields.
+
+```yaml
+project_board:
+  owner: "acme-org"
+  project_number: 1
+  project_id: "PVT_kwHOxxxxxxxxxxxxxxxx"
+
+  field_ids:
+    status: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    lane: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    component: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    priority: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    workflow: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+
+  option_ids:
+    status:
+      todo: "xxxxxxxx"
+      in_progress: "xxxxxxxx"
+      done: "xxxxxxxx"
+    lane:
+      fast: "xxxxxxxx"
+      feature: "xxxxxxxx"
+```
+
+**Finding your IDs**:
+
+```bash
+# List project IDs
+gh project list --owner <owner> --format json | jq '.projects[] | {number, id, title}'
+
+# List field IDs
+gh project field-list <project_number> --owner <owner> --format json | jq '.fields[]'
+
+# List option IDs for a single-select field
+gh project field-list <project_number> --owner <owner> --format json \
+  | jq '.fields[] | select(.name == "Status") | .options[]'
+```
+
+---
+
+## `review` (OPTIONAL)
+
+Context injected into review agent prompts. Helps agents make project-aware decisions.
+
+```yaml
+review:
+  context: |
+    This is a multi-tenant SaaS. Every endpoint must enforce tenant isolation.
+    We use row-level security in PostgreSQL — never bypass it.
+    Financial calculations must use Decimal, never float.
+```
+
+---
+
+## `devdocs` (OPTIONAL)
+
+Path to your project's devdocs knowledge tree. Agents read this for institutional context before making architectural decisions.
+
+```yaml
+devdocs:
+  path: "devdocs/"
+```
+
+The devdocs directory should contain `project/architecture.md` as the primary strategic context file. See [Architecture](./architecture) for details on ForgeDock's own devdocs structure.
+
+---
+
+## `adaptive_scripts` (OPTIONAL)
+
+Per-repo script overrides for deterministic pipeline operations. Allows you to replace prose instructions with executable scripts for project-specific validation.
+
+```yaml
+adaptive_scripts:
+  enabled: true
+  directory: "scripts/forge/"
+```
+
+---
+
+## Full Example
+
+```yaml
+# forge.yaml — minimal required config
+
+project:
+  name: "My Project"
+  owner: "my-org"
+  repo: "my-project"
+
+paths:
+  root: "/home/me/projects/my-project"
+  worktree_base: "/home/me/projects/my-project/.claude/worktrees"
+
+branches:
+  default: "main"
+  staging: "staging"
+  feature_pattern: "milestone/{slug}"
+```
+
+For the full annotated example, see [`forge.yaml.example`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/forge.yaml.example) in the repository.

package/docs/site/for-companies.md

@@ -30,7 +30,7 @@ Use this table to determine which license you need:
 
 Key clarification: ForgeDock is a **development tool**, not a library embedded in your product. Simply using ForgeDock to build and ship your own software does not trigger the copyleft clause — the clause applies when you modify ForgeDock itself and offer it as a service to others.
 
-For the full license text, see [`LICENSE`](../../LICENSE) (AGPL-3.0) and [`COMMERCIAL-LICENSE.md`](../../COMMERCIAL-LICENSE.md).
+For the full license text, see [`LICENSE`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/LICENSE) (AGPL-3.0) and [`COMMERCIAL-LICENSE.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/COMMERCIAL-LICENSE.md).
 
 ---
 
@@ -76,13 +76,13 @@ All pipeline state lives in your GitHub repository: issue comments (FORGE annota
 No. ForgeDock has no server-side component that could receive your code or GitHub data. The `npx forgedock` installer symlinks command files into `~/.claude/commands/` on the developer's machine — it does not phone home.
 
 **How are contributions governed?**
-All contributors sign a Developer Certificate of Origin (DCO) on each commit. ForgeDock does not use a CLA. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the full process.
+All contributors sign a Developer Certificate of Origin (DCO) on each commit. ForgeDock does not use a CLA. See [`CONTRIBUTING.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/CONTRIBUTING.md) for the full process.
 
 **Security policy?**
-See [`SECURITY.md`](../../SECURITY.md) for the vulnerability disclosure policy and contact.
+See [`SECURITY.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/SECURITY.md) for the vulnerability disclosure policy and contact.
 
 **Governance?**
-See [`GOVERNANCE.md`](../../GOVERNANCE.md) for the project's decision-making process and stewardship model.
+See [`GOVERNANCE.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/GOVERNANCE.md) for the project's decision-making process and stewardship model.
 
 ---
 

package/docs/site/forge-annotation-protocol.md

@@ -10,7 +10,7 @@ keywords: ["ai agent context protocol", "ai agent communication", "forge annotat
 >
 > The normative specification for the FORGE Annotation Protocol is now maintained at:
 >
-> **[`docs/spec/forge-protocol-v1.md`](../spec/forge-protocol-v1.md)**
+> **[`docs/spec/forge-protocol-v1.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/spec/forge-protocol-v1.md)**
 >
 > That document is the single source of truth for all FORGE annotation types,
 > syntax rules, the label state machine, conformance requirements, the extension

package/docs/site/github-is-the-memory.md

@@ -36,7 +36,7 @@ affected_files: commands/orchestrate.md, scripts/layer5-query.sh
 
 This is still a GitHub comment — a human reading the thread sees it as a collapsed HTML comment or reads its contents directly. But a downstream agent querying the issue with `gh issue view` gets it as structured text it can parse without guessing at prose intent. The annotation is the contract between stages.
 
-The annotation format is an open standard — the [FORGE Annotation Protocol](../spec/forge-protocol-v1.md). Any agent pipeline can implement it without ForgeDock. The format is documented in full, the vocabulary is fixed, and the license is CC-BY-4.0.
+The annotation format is an open standard — the [FORGE Annotation Protocol](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/spec/forge-protocol-v1.md). Any agent pipeline can implement it without ForgeDock. The format is documented in full, the vocabulary is fixed, and the license is CC-BY-4.0.
 
 ---
 
@@ -106,7 +106,7 @@ Checks your environment, installs the slash commands into Claude Code, and gener
 
 **Adopt the protocol without ForgeDock:**
 
-The annotation format is the independently useful part. The [FORGE Annotation Protocol](../FORGE-PROTOCOL.md) document describes the philosophy and vocabulary. The [protocol spec](../spec/forge-protocol-v1.md) gives the full technical definition — annotation types, required fields, completion markers, and query patterns. The license is CC-BY-4.0. Any agent pipeline can implement structured GitHub annotations using these specs without adopting ForgeDock's command layer. The only requirement is consistency: if annotations are written and read with the same vocabulary, the knowledge graph is coherent across sessions.
+The annotation format is the independently useful part. The [FORGE Annotation Protocol](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/FORGE-PROTOCOL.md) document describes the philosophy and vocabulary. The [protocol spec](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/spec/forge-protocol-v1.md) gives the full technical definition — annotation types, required fields, completion markers, and query patterns. The license is CC-BY-4.0. Any agent pipeline can implement structured GitHub annotations using these specs without adopting ForgeDock's command layer. The only requirement is consistency: if annotations are written and read with the same vocabulary, the knowledge graph is coherent across sessions.
 
 ---
 

package/docs/site/how-it-works.md

@@ -129,7 +129,7 @@ A new agent session running `/work-on 42` should always know what to do next by
 
 GitHub labels track the workflow state of every issue. The pipeline reads these labels to determine what to do next. A human can also manually set a label to nudge the pipeline or override its routing.
 
-> **Label reference**: [`docs/spec/label-state-machine.md`](../spec/label-state-machine.md) — full state table, transition rules, and terminal labels.
+> **Label reference**: [`docs/spec/label-state-machine.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/spec/label-state-machine.md) — full state table, transition rules, and terminal labels.
 
 ---