@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/docs/GETTING_STARTED.md

@@ -0,0 +1,348 @@
+# Getting Started with ForgeLoop
+
+This guide walks through your first complete task with ForgeLoop from initialization to validator-backed completion.
+
+---
+
+## 1. What is ForgeLoop?
+
+ForgeLoop is a portable, vendor-neutral engineering protocol for AI-assisted coding and automated workflows. It turns a task outcome into:
+
+- **A structured contract** (`.forgeloop/task-state/<taskKey>/contract.json`);
+- **Deterministic guide routing** based on declared work type, surfaces, and risks;
+- **Resumable work state** across different tools, IDEs, and AI harnesses;
+- **Observed verification evidence** linked to ForgeLoop-attested command execution;
+- **Diagnostic recovery loops** when tests or checks fail;
+- **Validator-backed completion** validated by protocol algorithms rather than agent claims.
+
+ForgeLoop is **not** an LLM runtime, agent framework, or graph orchestrator. It is a deterministic protocol and CLI that guides execution environments safely.
+
+Core mental model:
+
+- `work-state = lifecycle truth`
+- `continuity = operational handoff context`
+- `checkout = implementation truth`
+- `execution artifacts = process provenance`
+- `checks = verification truth`
+- `receipt = completion/publication record`
+
+---
+
+## 2. Prerequisites
+
+- **Node.js**: version 20 or higher (`node -v`)
+- **npm**: standard npm toolchain
+
+---
+
+## 3. Installation & Initialization
+
+In your project repository:
+
+```bash
+# Initialize ForgeLoop kit and discovery shims
+npx @cassiomc1/forgeloop init
+
+# Check target project health
+npx @cassiomc1/forgeloop doctor
+```
+
+What `init` does:
+
+- Installs the canonical instruction kit under `.forgeloop/kit/`;
+- Places native discovery shims at the project root (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md`);
+- Creates `.forgeloop/` for project configuration and `.forgeloop/task-state/` for isolated task execution.
+
+---
+
+## 4. End-to-End Walkthrough
+
+Here is a typical end-to-end task: *"Implement a contact form with input validation and tests."*
+
+```text
+User Request
+     │
+     ▼
+Create Task Namespace
+     │
+     ▼
+Define Task Contract
+     │
+     ▼
+Route Guides
+     │
+     ▼
+Preflight & Gate Validation
+     │
+     ▼
+Plan & Implement
+     │
+     ▼
+Execute & Verify Checks ─── failure ───► Diagnose & Correct
+     │                                         │
+     ▼                                         ▼
+Review Evidence ◄──────────────────────────────┘
+     │
+     ▼
+Complete Validation (VALID)
+```
+
+---
+
+### Step 1 — Create the Task Namespace and Contract
+
+First, create the task namespace with explicit write claims covering the files this task will touch:
+
+```bash
+forgeloop task-create \
+  --task task-contact-form-001 \
+  --claim src/components \
+  --claim tests \
+  --json
+```
+
+Discover the deterministic task state path using `task-show`:
+
+```bash
+forgeloop task-show --task task-contact-form-001 --json
+```
+
+Then write the task contract to `.forgeloop/task-state/<taskKey>/contract.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "protocolVersion": 1,
+  "taskId": "task-contact-form-001",
+  "objective": "Add a validated contact form with unit and visual tests",
+  "assumptions": [
+    {
+      "value": "Form submits via fetch POST to /api/contact",
+      "reason": "Backend endpoint already supports JSON payload",
+      "scope": "contact-form",
+      "reversible": true,
+      "source": "agent-default"
+    }
+  ],
+  "deliverables": [
+    "src/components/ContactForm.jsx",
+    "tests/contact-form.test.js"
+  ],
+  "constraints": [
+    "No external form libraries",
+    "WCAG AA contrast compliant"
+  ],
+  "risks": [
+    "untrusted-input"
+  ],
+  "verification": [
+    { "id": "unit-tests", "text": "npm test passes for contact form", "type": "VERIFICATION" },
+    { "id": "lint", "text": "npm run lint passes", "type": "VERIFICATION" }
+  ],
+  "successCriteria": [
+    "Form validates required fields client-side",
+    "All unit tests pass"
+  ],
+  "stopConditions": [
+    "Unresolved API specification change required"
+  ],
+  "unresolvedDecisions": [],
+  "sourceRefs": []
+}
+```
+
+---
+
+### Step 2 — Route Guides Deterministically
+
+Ask ForgeLoop which engineering guides apply to your work:
+
+```bash
+forgeloop route \
+  --task task-contact-form-001 \
+  --work complete-website \
+  --surface ui \
+  --surface forms \
+  --risk untrusted-input \
+  --json
+```
+
+This writes `.forgeloop/task-state/<taskKey>/routing-result.json` referencing selected guides (e.g. `clean`, `test`, `security`, `design`, `accessibility`).
+
+---
+
+### Step 3 — Run Preflight
+
+Before writing code, validate readiness and establish the canonical resumable work state:
+
+```bash
+forgeloop preflight --task task-contact-form-001 --json
+```
+
+Output:
+
+```json
+{
+  "status": "READY",
+  "taskId": "task-contact-form-001",
+  "errors": []
+}
+```
+
+When preflight returns `READY`, ForgeLoop synchronizes resumable work state (`.forgeloop/task-state/<taskKey>/work-state.json`) and preflight status (`.forgeloop/task-state/<taskKey>/preflight.json`). If preflight reports `BLOCKED`, inspect the required gates in the output and satisfy them first.
+
+---
+
+### Step 4 — Activate Session and Plan
+
+Create a session activation marker and transition to `PLANNED`:
+
+```bash
+forgeloop activate --task task-contact-form-001
+forgeloop advance --task task-contact-form-001 --to PLANNED
+```
+
+---
+
+### Step 5 — Implement
+
+Advance to `EXECUTING` and make your code changes:
+
+```bash
+forgeloop advance --task task-contact-form-001 --to EXECUTING
+```
+
+Implement your components, styles, and test files according to the activated guides.
+
+---
+
+### Step 6 — Verify with Observed Evidence
+
+Advance to `VERIFYING` and prepare completion receipt:
+
+```bash
+forgeloop advance --task task-contact-form-001 --to VERIFYING
+forgeloop prepare-completion --task task-contact-form-001 --json
+```
+
+Execute your verification checks through ForgeLoop so provenance is recorded:
+
+```bash
+# Run unit tests and record evidence
+forgeloop run-check --task task-contact-form-001 --id unit-tests --requirement "npm test passes for contact form" -- npm test
+
+# Run linter and record evidence
+forgeloop run-check --task task-contact-form-001 --id lint --requirement "npm run lint passes" -- npm run lint
+```
+
+If a check fails:
+
+1. Do not repeat the failed check blindly.
+2. Formulate a diagnostic hypothesis.
+3. Apply the correction.
+4. Re-run `forgeloop run-check`.
+
+---
+
+### Step 7 — Review Evidence
+
+Advance to `REVIEWING` and perform a read-only audit:
+
+```bash
+forgeloop advance --task task-contact-form-001 --to REVIEWING
+forgeloop audit --task task-contact-form-001 --json
+```
+
+Output checks contract coverage, ledger integrity, and fingerprint freshness.
+
+---
+
+### Step 8 — Validate Completion
+
+Run `forgeloop complete` to validate completion:
+
+```bash
+forgeloop complete --task task-contact-form-001 --json
+```
+
+Output:
+
+```json
+{
+  "status": "VALID",
+  "taskStatus": "COMPLETE",
+  "verificationStatus": "valid"
+}
+```
+
+Finally, query ForgeLoop for the next action:
+
+```bash
+forgeloop next --task task-contact-form-001 --json
+```
+
+When `terminal: true` and `nextAction: "NONE"` are returned, your task is protocol-verified as complete.
+
+---
+
+## 5. Multi-Task Concurrency
+
+ForgeLoop supports multiple parallel tasks in the same project without collision:
+
+```bash
+# Create an isolated task with explicit write claims
+forgeloop task-create --task auth-feature --claim src/auth --claim tests/auth --json
+
+# Run all commands against that specific task
+forgeloop route --task auth-feature --work clean-code --surface backend
+forgeloop preflight --task auth-feature --json
+forgeloop advance --task auth-feature --to EXECUTING
+forgeloop complete --task auth-feature --json
+
+# Inspect active tasks
+forgeloop task-list --json
+```
+
+---
+
+## 6. What ForgeLoop Creates
+
+Under `.forgeloop/task-state/<taskKey>/`:
+
+- `task.json`: task descriptor and write claims;
+- `contract.json`: task intent, deliverables, and success criteria;
+- `routing-result.json`: deterministic guide selections;
+- `preflight.json`: pre-implementation authorization checkpoint;
+- `work-state.json`: lifecycle phase and resumption checkpoint;
+- `events.ndjson`: hash-chained append-only event ledger;
+- `executions/*.json`: provenance records for executed verification commands;
+- `execution-receipt.json`: completion evidence and coverage mapping.
+
+Shared repository artifacts (`sources.json`, `config.json`) remain at `.forgeloop/`.
+
+---
+
+## 7. Migrating ForgeLoop 1.0 Singleton State
+
+<!-- BEGIN FORGELOOP LEGACY LAYOUT EXAMPLE -->
+
+Legacy ForgeLoop 1.0 releases stored task artifacts directly under `.forgeloop/`, including `.forgeloop/current-contract.json`, `.forgeloop/work-state.json`, `.forgeloop/routing-result.json`, `.forgeloop/preflight.json`, `.forgeloop/execution-receipt.json`, `.forgeloop/events.ndjson`, `.forgeloop/gates/`, and `.forgeloop/executions/`.
+
+<!-- END FORGELOOP LEGACY LAYOUT EXAMPLE -->
+
+To safely migrate legacy singleton state into the modern namespaced layout:
+
+```bash
+forgeloop task-migrate --dry-run --json
+forgeloop task-migrate --json
+```
+
+---
+
+## 8. Next Steps
+
+- Continue a task across different AI harnesses: [`docs/CROSS_HARNESS_CONTINUITY.md`](./CROSS_HARNESS_CONTINUITY.md)
+- Complete command reference: [`docs/CLI_REFERENCE.md`](./CLI_REFERENCE.md)
+- Artifact and schema reference: [`docs/ARTIFACT_REFERENCE.md`](./ARTIFACT_REFERENCE.md)
+- Common symptoms and recovery: [`docs/TROUBLESHOOTING.md`](./TROUBLESHOOTING.md)
+- Real-world operational recipes: [`docs/RECIPES.md`](./RECIPES.md)

package/docs/RECIPES.md

@@ -0,0 +1,250 @@
+# ForgeLoop Operational Recipes
+
+Concise, copy-paste friendly recipes for common ForgeLoop tasks.
+
+---
+
+## Recipe Index
+
+1. [Start a New Task](#recipe-1--start-a-new-task)
+2. [Resume an Active Task in a New Session](#recipe-2--resume-an-active-task-in-a-new-session)
+3. [Switch to Another AI Harness or IDE](#recipe-3--switch-to-another-ai-harness-or-ide)
+4. [Recover and Continue After a Failed Test](#recipe-4--recover-and-continue-after-a-failed-test)
+5. [Record Manual Review Evidence](#recipe-5--record-manual-review-evidence)
+6. [Run Automated Checks with Attested Provenance](#recipe-6--run-automated-checks-with-attested-provenance)
+7. [Fix Stale State or Stale Receipt](#recipe-7--fix-stale-state-or-stale-receipt)
+8. [Inspect Why Completion is Blocked](#recipe-8--inspect-why-completion-is-blocked)
+9. [Export a Portable Task Bundle](#recipe-9--export-a-portable-task-bundle)
+10. [Final Verification Before Pull Request](#recipe-10--final-verification-before-pull-request)
+11. [Run Multi-Task Workflows Concurrently](#recipe-11--run-multi-task-workflows-concurrently)
+12. [Migrate Legacy 1.0 Single-Task Layout](#recipe-12--migrate-legacy-10-single-task-layout)
+
+---
+
+### Recipe 1 — Start a New Task
+
+```bash
+# 1. Create a task with explicit claims
+forgeloop task-create --task task-001 --claim src --claim tests --json
+
+# 2. Discover task state path and author contract under .forgeloop/task-state/<taskKey>/contract.json
+forgeloop task-show --task task-001 --json
+
+# 3. Route engineering guides
+forgeloop route --task task-001 --work code --surface api --risk untrusted-input --json
+
+# 4. Verify preflight
+forgeloop preflight --task task-001 --json
+
+# 5. Activate session and plan
+forgeloop activate --task task-001
+forgeloop advance --task task-001 --to PLANNED
+forgeloop advance --task task-001 --to EXECUTING
+```
+
+---
+
+### Recipe 2 — Resume an Active Task in a New Session
+
+```bash
+export FORGELOOP_TASK="task-001"
+
+# 1. Discover task state
+forgeloop status --json
+
+# 2. Reconcile continuity notes
+forgeloop reconcile-continuity --json
+
+# 3. Check modified files
+forgeloop inspect --json
+
+# 4. Get next action from ForgeLoop
+forgeloop next --json
+```
+
+---
+
+### Recipe 3 — Switch to Another AI Harness or IDE
+
+In Harness A (before stopping):
+
+```bash
+forgeloop record-continuity \
+  --task task-001 \
+  --focus-id api-endpoints \
+  --focus-summary "Finished GET /users, working on POST /users" \
+  --remaining "tests:Add validation test for POST /users" \
+  --inspect-first src/api/users.js \
+  --resume-note "Endpoint logic is in src/api/users.js. Next step is validation."
+```
+
+In Harness B (after starting):
+
+```bash
+forgeloop status --task task-001 --json
+forgeloop continuity --task task-001 --json
+forgeloop reconcile-continuity --task task-001 --json
+forgeloop next --task task-001 --json
+```
+
+---
+
+### Recipe 4 — Recover and Continue After a Failed Test
+
+```bash
+export FORGELOOP_TASK="task-001"
+
+# 1. Test failed in run-check
+forgeloop run-check --id unit-tests --requirement "All tests pass" -- npm test
+# Output: status = failed
+
+# 2. Query next action (directs to DIAGNOSE)
+forgeloop next --json
+
+# 3. Formulate diagnosis and apply code fix in checkout
+
+# 4. Re-run verification check
+forgeloop run-check --id unit-tests --requirement "All tests pass" -- npm test
+
+# 5. Check audit
+forgeloop audit --json
+```
+
+---
+
+### Recipe 5 — Record Manual Review Evidence
+
+```bash
+# For non-automated criteria (design review, UX inspection, security review)
+forgeloop record-check \
+  --task task-001 \
+  --id manual-contrast-review \
+  --requirement "WCAG AA contrast compliant" \
+  --status passed \
+  --kind manual-review \
+  --evidence-kind OBSERVED \
+  --result "Manually tested light and dark modes; text contrast >= 4.5:1."
+```
+
+---
+
+### Recipe 6 — Run Automated Checks with Attested Provenance
+
+```bash
+export FORGELOOP_TASK="task-001"
+
+# Prepare receipt slots in VERIFYING phase
+forgeloop advance --to VERIFYING
+forgeloop prepare-completion --json
+
+# Run checks via forgeloop to record cryptographic execution provenance
+forgeloop run-check --id unit-tests --requirement "Unit tests" -- npm test
+forgeloop run-check --id linter --requirement "Linting" -- npm run lint
+forgeloop run-check --id typecheck --requirement "Typecheck" -- npm run typecheck
+```
+
+---
+
+### Recipe 7 — Fix Stale State or Stale Receipt
+
+```bash
+export FORGELOOP_TASK="task-001"
+
+# If contract or files were modified out of band:
+forgeloop route --work clean-code --json
+forgeloop preflight --json
+forgeloop prepare-completion --json
+forgeloop validate-protocol --json
+```
+
+---
+
+### Recipe 8 — Inspect Why Completion is Blocked
+
+```bash
+# Run read-only audit to inspect unsatisfied coverage
+forgeloop audit --task task-001 --json
+
+# Inspect protocol next guidance
+forgeloop next --task task-001 --json
+```
+
+---
+
+### Recipe 9 — Export a Portable Task Bundle
+
+```bash
+# Bundles contract, route, state, receipt, executions, and ledger into a single archive
+forgeloop bundle --task task-001 --json
+```
+
+---
+
+### Recipe 10 — Final Verification Before Pull Request
+
+```bash
+export FORGELOOP_TASK="task-001"
+
+# 1. Ensure all checks passed in VERIFYING
+# 2. Advance to REVIEWING
+forgeloop advance --to REVIEWING
+
+# 3. Run audit
+forgeloop audit --json
+
+# 4. Authorize completion
+forgeloop complete --json
+
+# 5. Confirm terminal state
+forgeloop next --json
+# Expected: "terminal": true, "nextAction": "NONE"
+```
+
+---
+
+### Recipe 11 — Run Multi-Task Workflows Concurrently
+
+```bash
+# 1. Create task-1 claiming auth directory
+forgeloop task-create --task auth-feature --claim src/auth --claim tests/auth --json
+
+# 2. Create task-2 claiming billing directory
+forgeloop task-create --task billing-feature --claim src/billing --claim tests/billing --json
+
+# 3. List active tasks
+forgeloop task-list --json
+
+# 4. Work on task-1
+forgeloop route --task auth-feature --work clean-code --surface backend
+forgeloop preflight --task auth-feature --json
+forgeloop advance --task auth-feature --to EXECUTING
+forgeloop advance --task auth-feature --to VERIFYING
+forgeloop run-check --task auth-feature --id auth-tests --requirement tests -- npm test -- tests/auth
+forgeloop advance --task auth-feature --to REVIEWING
+forgeloop complete --task auth-feature --json
+
+# 5. Release any dead locks if needed
+forgeloop task-unlock --task auth-feature --force --json
+```
+
+---
+
+### Recipe 12 — Migrate Legacy 1.0 Single-Task Layout
+
+<!-- BEGIN FORGELOOP LEGACY LAYOUT EXAMPLE -->
+
+Legacy ForgeLoop 1.0 projects stored mutable artifacts directly under `.forgeloop/` (e.g. `.forgeloop/current-contract.json`, `.forgeloop/work-state.json`, `.forgeloop/gates/`, `.forgeloop/executions/`).
+
+<!-- END FORGELOOP LEGACY LAYOUT EXAMPLE -->
+
+```bash
+# 1. Perform dry-run migration check
+forgeloop task-migrate --dry-run --json
+
+# 2. Execute migration to .forgeloop/task-state/<taskKey>/
+forgeloop task-migrate --json
+
+# 3. Verify migrated task state
+forgeloop task-list --json
+forgeloop status --json
+```