# Candidate acceptance

**Verdict:** TODO: PASS, FAIL, RETHINK, READY_FOR_USER, INCONCLUSIVE, or BLOCKED

## Candidate and Setup

- Candidate: TODO
- Passing Build review: TODO
- Retained accepted baseline and approved delta: TODO or `None.`
- Applicable Spec-apply receipt and current result hashes: TODO or `None.`
- Acceptance owner: TODO
- Environment and version: TODO
- Fixtures and permissions: TODO
- Browser, viewport, or runtime: TODO
- Known setup or proof gaps: TODO

## Actual Results

<!-- Include changed or new outcomes, affected unchanged outcomes, and material failure paths. -->

| Scenario or obligation | Action or command | Expected | Observed | Result | Evidence |
| --- | --- | --- | --- | --- | --- |
| TODO | TODO | TODO | TODO | TODO | TODO |

## Preservation Coverage

- Reviewed signals and resulting obligations: TODO
- Changed or new outcomes exercised: TODO
- Affected unchanged outcomes and failure paths exercised: TODO
- Relevant prior evidence reused and reason: TODO or `None.`
- Scope gap: TODO or `None.`

## Visual and Interaction Evidence

<!-- Delete only when no accepted visual or interactive behavior applies. -->

- Accepted visual revision and states: TODO
- Actual browser interactions and viewports: TODO
- Comparison and material deviations: TODO
- Keyboard, focus, and assistive behavior: TODO

## Gaps and Failures

- TODO: Required unavailable proof, failed scenario, or limitation; write `None.` when empty

## Final Basis

TODO: State why the actual evidence supports the verdict. Test source, generated
mocks, document validation, and earlier PASS labels are not current runtime proof.

# Legacy template name

Use the RC1 [Bug template](bug.md). This file remains only so historical links resolve.

# TODO bug outcome

## Context

TODO: State the reported impact, accepted behavior source, affected candidate or
environment, and whether the failure has actually been reproduced.

## Expected and Actual

- Expected: TODO
- Actual: TODO

## Reproduction

1. TODO: Prerequisites and safe fixture
2. TODO: Exact action or command
3. TODO: Observed result and evidence

## Acceptance Criteria

- TODO: Plain observable restored behavior and material boundary

## Plan Notes

| Falsifiable hypothesis | Cheapest distinguishing observation | Result |
| --- | --- | --- |
| TODO | TODO | not run |

## QA and Spec Impact

- Original reproduction before and after: TODO
- Affected regression proof: TODO
- Standing behavior: TODO: restored unchanged, or human-approved delta reference

## Review Surface

TODO: Name the likely shared cause, sibling consumers, and evidence that would
distinguish a root-cause correction from a symptom guard.

## Knowledge and Preservation (optional)

- Affected or corrected domain, data, runtime, process, operations, or interface knowledge: TODO or `None.`
- Preserved standing obligations and original reproduction: TODO
- Signals -> affected obligations -> selected checks -> gaps: TODO

# Build log

<!-- Append candidate sections. Preserve earlier Review and repair history. -->

## Candidate: TODO

### Packet and Ownership

- Selected outcomes: TODO
- Accepted authority: TODO
- Builder: TODO - role name only
- Delegated work and owned boundaries: TODO or none
- Comparison base: TODO
- Candidate identity: TODO
- Retained accepted baseline and approved delta: TODO or `None.`
- Spec-apply receipt and document-only result hashes: TODO or `None.`
- Complete actual code/test/canonical Spec/KB/decision diff: TODO or `None.`

### Build, Integration, and Simplification

- Implemented: TODO
- Integrated: TODO
- Simplification: TODO: changes or justified no-op
- Builder checks: TODO
- Known proof gaps: TODO

### Preservation Scope

- Builder proposal: signals -> affected obligations -> selected checks -> gaps: TODO
- Paths that narrow discovery: TODO or `None.`
- Exported contracts or actual semantics that expand discovery: TODO or `None.`
- Changed or new outcomes, affected unchanged outcomes, and material failures: TODO
- Relevant prior evidence reused and reason: TODO or `None.`

### Independent Review

- Reviewer: TODO - role name only
- Reviewed actual candidate, retained baseline, approved delta, and canonical result: TODO or `None.`
- Lenses and evidence: TODO
- Findings and dispositions: TODO or none
- Verdict: TODO: PASS, REVISE, RETHINK, READY_FOR_USER, or BLOCKED

### Repair or Rethink

<!-- Delete for the first candidate. Append one section for each substantive reassessment. -->

- Failed invariant or common cause: TODO
- Whole-packet correction: TODO
- Preserved commitments: TODO
- Invalidated and reused proof: TODO
- New candidate: TODO
- Reassessment: TODO
- Stop reason or next discriminating proof: TODO

# Legacy template name

Use the optional RC1 [coordination Plan](plan.md). Build tactics and Review history belong in [build-log.md](build-log.md).

# Legacy template name

Use the RC1 [Build log](build-log.md). This file remains only so historical links resolve.

# TODO canonical concept

## Definition

TODO: Define the domain concept in plain language and identify its source.

## Scope

- Optional topic: TODO: Domain, Data, Runtime, Operations, or Shared foundations
- Includes: TODO
- Excludes: TODO

## Relationships

| Related concept or entity | Relationship | Source |
| --- | --- | --- |
| TODO | TODO | TODO |

## Constraints and Examples

- Constraint: TODO
- Representative example: TODO
- Counterexample or ambiguity: TODO

## Provenance

- Authority or source: TODO
- Last verified against: TODO
- Superseded term or record: none

# Human decisions

<!--
Append only decisions issued or explicitly approved by a human. The guarded
decision command records the source and authorization context. Proposals and
routine implementation choices belong in the relevant draft or Build log.
-->

<!-- Preserve prior entries. Canonical decisions use stable Forge identities,
descriptive filenames, and numeric D-number codes in the KB decisions index.
Record a correction or supersession as a new entry. -->

# Legacy template name

Use the RC1 [Design template](design.md) with an identified [visual companion](visual.md).

# Experience and visual intent

## Summary

TODO: State the proposed experience change and why it matters.

## Context

TODO: Name the accepted product intent, current experience, and affected users.

## End State

TODO: Describe the visible result, material states, and interaction boundaries a
reviewer can judge without opening another artifact.

## User Journey

TODO: Describe entry, decisive action, feedback, recovery, and exit for the
accepted user outcome.

## Visual Authority

- Companion record: TODO: identified visual.md path, or `Not granted.` naming
  the assignment that owns it
- Accepted asset or board: TODO
- Accepted revision and represented states: TODO
- Exploratory variants: TODO or none
- Materially locked: TODO
- Builder latitude: TODO

## Study Brief and Codebase Grounding

- Decision the study makes visible: TODO
- Existing surface and source revision (including relevant dirty changes): TODO
- Reused components, tokens, assets, content and behavior sources: TODO: paths and symbols
- Proposed delta and preserved product identity: TODO
- Baseline evidence: TODO: browser capture or labelled source reconstruction
- Study page and inspection evidence: TODO: use the visual companion for frame links

<!-- For a visual study, follow ../references/design-studies.md and customize
design-study.html. Keep product screens project-native. Omit duplicate context
already held in the ticket or visual record. -->

## Material States

| Surface | State | Observable behavior | Responsive and accessibility intent |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |

## Interaction and Content

- TODO: Hierarchy, action, feedback, recovery, or exact accepted language

## Acceptance

- TODO: Actual rendered state, viewport, interaction, or assistive behavior to inspect

## Knowledge and Preservation (optional)

- Design intent or shared foundation to carry into a reviewed KB update: TODO or `None.`
- Affected concepts, interfaces, processes, or design primitives: TODO or `None.`
- Preserved accepted states, scenarios, and accessibility obligations: TODO or `None.`
- Source, accepted revision, and authority: TODO

## References

- TODO: Accepted product intent, project precedent, and design system source

# Current loop state

## Outcome

TODO: State the requested outcome and current boundary in one short paragraph.

## Launch and Status

- Workflow: TODO - Project, Issue, Bug, or Work
- Depth: TODO - Quick or Full
- Control: TODO - Guided or Auto
- Agents: TODO - role names only, never first names; actual host IDs after dispatch
- Boundary: TODO
- Sequence: TODO - performed, reused, and pending phases
- Gates: TODO - pending/satisfied approvals and decisions outside authority
- Workspace: TODO - repository and actual branch/worktree when applicable
- Launch acceptance or Auto grant: TODO - source and scope, not invented artifact approval
- Current step: TODO
- Authority status: TODO
- Accountable owner: TODO
- Current candidate: TODO or none
- Comparison base: TODO or none
- Applied Spec status and receipt: TODO: document-only, not applied, or not applicable

TODO: One short paragraph explaining workflow, depth, and team choices, uncertainty,
who starts next, and what the user can override. For Auto, cite its grant. Keep
selected values above plain; do not add recommendation suffixes or role aliases.

## Pointers

- Human decisions: TODO
- Accepted or proposed Spec: TODO
- Retained accepted baseline and approved change: TODO or none
- Selected Issues or work: TODO
- Build record: TODO
- Acceptance record: TODO
- Canonical Spec or knowledge: TODO or none

## Current Gaps

- TODO: Missing authority, evidence, environment, or decision; write `None.` when empty

## Next

TODO: Name the next action and owner without claiming unperformed work.

# TODO interface

## Purpose and Ownership

- Purpose: TODO
- Optional topic: TODO: Data, Runtime, Operations, or Shared foundations
- Producer or owner: TODO
- Consumers: TODO
- Maintained source of truth: TODO: code, schema, external contract, or document

## Contract

| Operation, event, or field | Input / precondition | Output / effect | Failure behavior |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |

## Invariants and Compatibility

- TODO: Authorization, validation, ordering, idempotency, compatibility, or lifecycle rule

## Verification

- TODO: Current evidence or executable contract check
- Known gap: TODO or none

## Provenance

- Source and revision: TODO
- Human-authorized decision: TODO or none

<!-- Link maintained schemas and code rather than copying details that will drift. -->

# TODO outcome title

## Context

TODO: Explain why this bounded outcome matters, what becomes true, and the
accepted source of its scope. Keep the issue useful on its own; link project
documents only when they exist.

## Acceptance Criteria

- TODO: State a plain, observable result. Describe behavior, not implementation.

## Non-Functional Requirements

<!-- Delete when no material constraint shapes acceptance. -->

- TODO

## QA Plan

TODO: Name the cheapest credible proof of the outcome, material failure or
boundary cases, and affected integration behavior.

## Depth and Assignments

- Effort and complexity: TODO - assessment and material uncertainty; reuse an adequate estimate
- Depth: TODO - Quick or Full; record the user's selection and changed assessment
- Agents: TODO - assigned role names only; never first names

TODO: PM records the Issue first. Engineer records the assessment after that
draft exists. Explain required design then contracts and proof; no separate
estimator. Do not spawn those specialists together.

## Implementation Notes

<!-- Optional. Record helpful source anchors, seams, exclusions, or a short approach. -->

- TODO

## Knowledge and Preservation (optional)

- Domain, API, process, data, runtime, operations, or design intent for a reviewed KB update: TODO or `None.`
- Affected and preserved decisions, concepts, processes, interfaces, or scenarios: TODO or `None.`
- Preservation signals -> selected checks -> gaps: TODO or `None.`

## References

- TODO: Exact accepted authority or verified source anchor

# Dn - TODO durable decision

<!-- Use the next available D-number and a descriptive filename. Keep the stable
Forge identity in managed frontmatter or the reserved-file sidecar. -->

## Decision

TODO: State the accepted choice precisely.

## Scope and Status

- Decision code: Dn: replace with the next available number
- Scope: TODO
- Status: TODO: accepted or superseded
- Effective date: TODO
- Human authority or approved source: TODO
- Supersedes: none

## Context and Rationale

TODO: Record the decision-relevant context and why this choice was accepted.

## Consequences

- TODO: Commitment, tradeoff, or downstream constraint

## References

- TODO: Original decision record, affected Spec, concept, process, or interface

## Index and History

- Numeric decisions index entry: TODO: `docs/knowledge/decisions/index.md`
- Receipt-derived history: TODO: `forge kb history` operation or `None.`

<!-- Preserve history. Supersession creates a new authorized record and updates references; it does not rewrite the source decision. -->

# Knowledge index

<!-- Optional entry point. Create it only when the repository has earned a useful corpus. -->

## Scope

TODO: State the domain or product area this index covers.

## Optional Reading Topics

| Topic | Records present | Suggested open types and templates | Status |
| --- | --- | --- | --- |
| Domain | TODO or `None.` | `Domain Concept`; concept template | TODO |
| Data | TODO or `None.` | `Data Model` or `Persistence Contract`; concept or interface template | TODO |
| Runtime | TODO or `None.` | `Runtime Component` or `Runtime Contract`; concept or interface template | TODO |
| Core processes | TODO or `None.` | `Core Process`; process template | TODO |
| Operations | TODO or `None.` | `Operational Practice` or `Operations Contract`; process or interface template | TODO |
| Shared foundations | TODO or `None.` | `Shared Foundation` or `Foundation Contract`; concept or interface template | TODO |

## Canonical Records

- Decisions index: TODO or `None.`; order canonical `D1`, `D2`, and later codes numerically.
- Standing Specs and accepted scenarios: TODO or `None.`; link them once instead of copying requirements.
- Other earned concepts, processes, and interfaces: TODO or `None.`

## Provenance and Gaps

- Primary source set: TODO
- Receipt-derived history: use `forge kb history`; do not hand-assemble shipped claims from this index
- Contradiction, missing source, or stale record: TODO or none

<!-- Link standing Specs once; do not duplicate their requirements in the knowledge corpus. -->

# Knowledge change log

<!-- Append factual maintenance history. This log records changes; it does not approve them. -->

## TODO — Knowledge change

- Operation: TODO: add, update, remove, merge, or verify
- Records: TODO
- Base and resulting revisions: TODO
- Human authority or request: TODO
- Preserved references and meaning: TODO
- Semantic review and validation: TODO
- Observed gaps or conflicts: TODO or none
- Receipt: TODO: `.forge/memory/<operation_id>.json` or `None.`
- History classification: TODO: Spec change, knowledge or decision maintenance, or evidenced system delivery
- Delivery claim: TODO: state `None.` for document-only, failed, or unaccepted work

<!-- `forge kb history` derives successful operation history from receipts. This optional OKF log records local factual context; it is not approval. -->

# Execution log

<!-- Append material events. State facts and link the direct result; do not restate human authority. -->

## TODO — Event

- Actor: TODO - role name only
- Artifact or candidate: TODO
- Observed: TODO
- Evidence: TODO
- Next: TODO

# Legacy template name

Use the RC1 [Review template](review.md) with the exact Plan artifact as its candidate.

# Coordination plan

<!--
Create this document only when coordination detail has no better home. A clear
Issue with short implementation notes needs no separate Plan.
-->

## Summary

TODO: State the proposed delivery route and why this coordination is needed.

## Context

TODO: Link approved intent and outcome Issues or work artifact; name current
owners, constraints, and dependencies that shape the route.

## End State

TODO: State the complete outcome and material boundaries in this Plan's own words.

## Plan

TODO: List the smallest meaningful steps, integration order, and proof. Keep
reversible file-level tactics with the Builder.

## Dependencies and Shared Seams

| Outcome | Provides or consumes | Coordination reason |
| --- | --- | --- |
| TODO | TODO | TODO |

## Integration and Proof

TODO: State integration order or contention, the whole-outcome proof, and any
proof that must wait for another outcome.

## Proportional Preservation

<!-- Use only when the change can affect existing behavior. Keep the chain short. -->

- Signals: TODO - package/API/events/shared types, data or persistence, shared foundations, removed or renamed files, test expectation changes, or Spec/decision/KB edits
- Affected obligations and preserved outcomes: TODO
- Selected checks: TODO - changed or new outcomes, affected unchanged outcomes, and material failures
- Gaps: TODO or `None.`

## Risks and Open Decisions

- TODO: Material risk, factual gap, or consequential choice and owner

# TODO process

## Purpose and Outcome

TODO: Name the business or operational outcome and the process boundary.

<!-- Use this open OKF concept type for Core processes or Operations when earned. -->

## Actors, Inputs, and Outputs

- Actors: TODO
- Inputs and preconditions: TODO
- Outputs and completion: TODO

## Workflow

1. TODO: Actor action and observable result

## Exceptions and Recovery

- TODO: Material alternate path, failure, ownership, and recovery

## Governing Rules

- TODO: Accepted Spec, decision, policy, or other authority

## Provenance

- Source: TODO
- Last verified against: TODO

# Legacy template name

Use the RC1 [Product template](product.md). This file remains only so historical links resolve.

# Product outcome

## Summary

TODO: State the proposed product change and why it matters in a few sentences.

## Context

TODO: Name the specific user, situation, current pain, and evidence or accepted
human intent behind the work.

## End State

TODO: Describe what the user can do or observe when the smallest coherent change
succeeds, including material boundaries.

## Scope

- In: TODO
- Out: TODO

## Acceptance Criteria

- TODO: Plain, demonstrable user or product outcome

## Material Constraints

<!-- Delete when none are accepted. -->

- TODO: Constraint and authority

## Open Decisions

- TODO: Consequential choice and owner; write `None.` when resolved

## Knowledge and Preservation (optional)

- Domain, process, or design intent to carry into a reviewed KB update: TODO or `None.`
- Affected decisions, concepts, processes, or interfaces: TODO or `None.`
- Preserved obligations and scenarios: TODO or `None.`
- Source and authority: TODO

## References

- TODO: Human decision, research, current behavior, or other authority

# Independent review

**Verdict:** TODO: PASS, REVISE, RETHINK, READY_FOR_USER, or BLOCKED

## Review Boundary

- Candidate: TODO
- Comparison base: TODO
- Reviewer: TODO
- Accepted authority: TODO
- Authority status: TODO: whether that intent carries recorded human approval, or
  is a draft the loop record shows was routed under a standing grant
- Inspected scope: TODO
- Staffing and reason: TODO: Reviewer alone or focused delegated judges
- Known evidence or source gaps: TODO

## Dimension Coverage

| Dimension | Applicability / reason | Selected skill or source | Owner | Evidence / verdict or gap |
| --- | --- | --- | --- | --- |
| Code Review | TODO | TODO | TODO | TODO |
| Design | TODO | TODO | TODO | TODO |
| Quality | TODO | TODO | TODO | TODO |
| Spec | Required | TODO | TODO | TODO |
| Craft | Required | TODO | TODO | TODO |

Disabled or waived coverage: TODO or `None.` Include exact scope, reason, and
human authority for any waiver. Never label omitted coverage PASS.

## Dimension Reports

<!-- For Reviewer-owned dimensions, concise evidence-backed table entries above
can suffice; share the boundary and checks instead of repeating them. Remove this
unused section. When delegating, preserve each original return as a labelled
section or linked managed report beside the Reviewer's disposition. The record
owner persists read-only judges' returns. -->

### TODO: Dimension

- Selected skill/source: TODO
- Candidate, comparison base, dirty state, and path scope: TODO
- Inspected authority: TODO
- Checks and observed evidence, including limits: TODO
- Findings: TODO or `None.` Each needs severity, authority, reachable trigger,
  observed evidence or causal trace, material consequence, and remedy boundary.
- Required proof gaps: TODO or `None.`
- Dimension verdict and basis: TODO: PASS, REVISE, RETHINK, READY_FOR_USER, or BLOCKED

## Integration

- Candidate/authority binding and required coverage: TODO
- Duplicate findings and conflicts, with evidence-backed dispositions: TODO or `None.`
- Accompanying software-record contract: TODO or `Not applicable.`

## Checks and Evidence

| Lens or check | Evidence | Result | Limits |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |

## Preservation Challenge

- Builder's proposed scope: TODO
- Signals confirmed or expanded by the Reviewer: TODO
- Affected obligations and preserved outcomes: TODO
- Selected checks and evidence: TODO
- Gaps or unjustified path-only claims: TODO or `None.`

## Findings

<!--
Use P0 only for a demonstrated accepted-Spec violation or critical correctness,
security, or data-loss failure. Use pragmatic P1 only with a plausible current
trigger, material consequence, and scope-aligned correction. P2 is advisory.
No quota or manufactured nits. Write `None.` when no finding survives admission.
-->

### TODO: Finding title

- Severity: TODO: P0, P1, or P2
- Rubric: TODO
- Authority: TODO
- Observed evidence: TODO
- Trigger and consequence: TODO
- Disposition: open

## Verdict Basis

TODO: Judge the complete candidate, identify blocked or unrun proof, and state
what must be true for reassessment. Label any explicitly human-waived dimension
excluded from a scoped PASS. A changed candidate requires a new verdict.

# Legacy template name

Use the RC1 [loop index](index.md). This file remains only so historical links resolve.

# Ship record

## Closure Basis

- Accepted candidate and comparison base: TODO
- Current candidate and relationship to accepted candidate: TODO
- Passing Build Review: TODO
- Passing Acceptance: TODO
- Retained accepted baseline and approved change: TODO or `None.`
- Applicable Spec-apply receipt and current result hashes: TODO or `None.`
- Freshness check: TODO

## Authorized Operations

| Operation | Exact target | Result | Evidence |
| --- | --- | --- | --- |
| TODO or `None.` | TODO | TODO | TODO |

## Result and Limits

- Closure result: TODO
- Historical verdicts retained under their original candidate: TODO
- Changed input or discrepancy routed to owner: TODO or `None.`
- Remaining limit or ungranted publication action: TODO or `None.`

<!-- Record one concise closure. Do not routinely reapply canonical meaning, request another semantic verdict, relabel historical PASS results, or claim an unperformed publication. -->

# Legacy template name

Record Build-integrated simplification, including a justified no-op, in the RC1 [Build log](build-log.md). Use [work.md](work.md) for a standalone non-delivery simplification request.

# Proposed Spec change

## Authority and Inputs

- Human-approved source and exact scope: TODO
- Accepted baseline file and SHA-256: TODO
- Current write base file and SHA-256: TODO
- Approved change file and SHA-256: TODO
- Related product, design, technical, or Issue sources: TODO

<!-- Keep the accepted baseline and approved change independently readable. The current write base may differ from the accepted baseline. -->

## Proposed Operations

### Added

- TODO: Requirement name and full proposed wording, or `None.`

### Modified

- TODO: Existing requirement and complete replacement wording, or `None.`

### Removed

- TODO: Existing requirement, reason, and authorization, or `None.`

### Renamed

- TODO: Old name, new name, preserved meaning, and authorization, or `None.`

## Requirements and Scenarios

### Requirement: TODO

TODO: Write the complete normative behavior this operation proposes.

#### Scenario: TODO meaningful situation

- GIVEN TODO: concrete context or precondition
- WHEN TODO: user action or system event
- THEN TODO: observable outcome

## Preserved Commitments

- TODO: Preserved requirement or scenario reference and why it remains unchanged

## Knowledge Intent and Preservation Scope

- Loop domain, data, runtime, process, operations, or design intent for the KB: TODO or `None.`
- Affected decisions, concepts, processes, interfaces, or shared foundations: TODO or `None.`
- Signals: TODO - package/API/events/shared types, data or persistence, shared foundations, removed or renamed files, test expectation changes, or Spec/decision/KB edits
- Affected obligations: TODO
- Selected checks: TODO - changed or new outcomes, affected unchanged outcomes, and material failures
- Gaps: TODO or `None.`

## Reconciliation and Proof Gaps

- Approved proposal and authority source: TODO
- Routine application timing: actual work completion through Finish, or an
  explicitly authorized direct Spec apply
- Application receipt and result SHA-256: TODO or `NOT APPLIED`
- Application status: TODO: `NOT APPLIED` during ordinary Spec, or `document-only`
  after an authorized apply
- Candidate implementation and Review: TODO or `NOT RUN`
- Required acceptance evidence: TODO
- Semantic conflict, concurrent change, or unavailable proof: TODO or none

<!-- Spec records the approved proposal without routine canonical writes. Routine apply waits for actual work completion and Finish. An explicitly authorized direct Forge spec apply remains available; it prepares, reviews, and applies the complete result through guarded mechanics. Application does not prove implementation, Review, Acceptance, Ship, or publication. -->

# Legacy template name

Use the RC1 [Review template](review.md) with the exact Spec artifact as its candidate.

# TODO capability

## Purpose and Scope

TODO: Define the current accepted capability, its users or consumers, and its
boundary. This is canonical behavior, not an implementation plan or change log.

## Requirements

### Requirement: TODO

TODO: State one complete binding behavior. Use MUST or SHALL when the obligation
needs normative force.

#### Scenario: TODO meaningful situation

- GIVEN TODO: concrete context or precondition
- WHEN TODO: user action or system event
- THEN TODO: observable outcome

## Non-Behavioral Constraints

<!-- Keep accepted NFRs or invariants that Given/When/Then cannot express well. -->

- TODO: Constraint and authority

## Supporting Knowledge and Decisions (optional)

- Canonical decisions, concepts, processes, or interfaces: TODO or `None.`
- Preserved obligations checked by this change: TODO or `None.`

## References and Provenance

- TODO: Approved Spec change, human decision, design revision, or maintained contract

# Technical end state

<!-- Keep only load-bearing choices that independent work must share. -->

## Summary

TODO: State the proposed technical change and why it matters for the accepted outcome.

## Context

TODO: Name verified current owners, reusable machinery, and the constraint driving change.

## End State

TODO: State the operational result, material invariants, and boundaries independent
work must preserve.

## Target Shape

TODO: Describe the minimum technical shape needed for the accepted outcome and why
the existing owner or simpler route cannot meet any proposed new mechanism's need.

## Contracts and Ownership

| Seam or contract | Producer / owner | Consumers | Required behavior and failure |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |

## Data, Trust, and Lifecycle

- TODO: Material invariant, authorization boundary, migration, recovery, or operating constraint

## Technical Proof

- TODO: Contract, integration, migration, failure, or NFR evidence that can falsify the design

## Builder Latitude

- Locked: TODO
- Reversible implementation choices: TODO

## Open Decisions and Gaps

- TODO: Consequential unresolved choice or missing source fact; write `None.` when empty

## Knowledge and Preservation (optional)

- Data, runtime, API, operations, or shared-foundation intent to carry into a reviewed KB update: TODO or `None.`
- Affected decisions, concepts, processes, or interfaces: TODO or `None.`
- Preserved contracts, lifecycle rules, and scenarios: TODO or `None.`
- Source and authority: TODO

## References

- TODO: Accepted intent, verified source, project harness, or primary external source

# Legacy template name

Use the RC1 [technical template](tech.md). This file remains only so historical links resolve.

# Visual companion

## Identity and Authority

- Design Spec: TODO
- Asset, board, prototype, or external design: TODO
- Exact revision: TODO
- Status: TODO: exploratory, proposed, or accepted
- Human acceptance source: TODO or none
- Local study page and verified preview URL: TODO or not applicable; mark ephemeral URLs
- Source revision and anchors: TODO: relevant dirty changes, paths, symbols, tokens and fixtures

## Represented States

| Frame ID / state | Viewport or context | Purpose / evidence type | Asset location |
| --- | --- | --- | --- |
| TODO | TODO | TODO: capture, source reconstruction, or proposed prototype | TODO: exact revision and frame link |

## Material Commitments

- Locked: TODO: hierarchy, layout, interaction, content, typography, or other accepted intent
- Builder latitude: TODO
- Excluded or exploratory variants: TODO or none

## Acceptance Notes

- Actual candidate states to compare: TODO
- Responsive and accessibility intent: TODO
- Known missing state or revision gap: TODO or none

## Study Inspection (not production Acceptance)

- Inspected revision, viewports, interactions, and actual outcomes: TODO or pending
- Final rendered images: TODO or unavailable
- Recommendation and tradeoff: TODO
- Simulated behavior, disposable shortcuts, and evidence gaps: TODO or none

<!-- Update revision and represented states when the visual changes. Preserve an
accepted revision before proposing another. A recommendation or UI selection is
not human acceptance; a vendor ID alone is not Forge identity. -->

# Legacy template name

RC1 has no Wave artifact. Use the [loop index](index.md) for current state and the [Build log](build-log.md) for selected packets and integrated candidates.

# Legacy template name

Use the RC1 [Work template](work.md). This file remains only so historical links resolve.

# Work outcome

## Summary

TODO: State the proposed deliverable and why it matters.

## Context

TODO: Explain the request, intended reader or user, and boundary. State whether
this work changes software, a document, research, operations, or another artifact.

## End State

TODO: Describe the concrete, inspectable result and where it will exist.

## Acceptance Criteria

- TODO: Observable or inspectable outcome

## Constraints and Non-Goals

- TODO: Authority, source-of-truth, safety, format, or explicit exclusion

## Plan

<!-- Keep only when the work needs sequencing; omit when the route is obvious. -->

TODO: Record the smallest meaningful steps and any useful source anchors.

## Proof

TODO: State how an independent reader or operator will verify the actual result.

## Knowledge and Preservation (optional)

- Intent to carry into a reviewed KB update: TODO or `None.`
- Affected and preserved obligations: TODO or `None.`
- Signals -> selected checks -> gaps: TODO or `None.`

## References

- TODO

# Build

Build produces one integrated candidate and includes independent Review. It may be
invoked directly from an accepted task; a direct Build stops after its Review
result and never claims Acceptance or Ship.

## Accountable Engineer

One Engineer owns the whole accepted outcome, tactical plan, required Worker
delegation, integration, behavior-preserving simplification, internal review,
evidence, and coherent repair. Read the accepted Spec/ticket, Plan, decisions,
applicable repository harness, current candidate/base, shared seams, and proof
contract. Follow [Launch and workflow preparation](workflows.md): a missing or
unready Issue goes to PM first, then Engineer assessment, before Build, even at
Quick depth.
This does not require a Project Spec. Do not bypass Launch, new intent, or
consequential strategy gates because the user requested implementation.

Before entering a new subtree, framework boundary, or standards domain, resolve
its applicable harness and load only newly relevant rules and exemplars. Include
those rules in delegated packets; neither a familiar pattern nor a persona can
override the target repository's authority.

For UI work, use [design direction and craft](design-direction.md) unless the
target selects a replacement. Apply it within the accepted design; it does not
require a new study for an already specified patch.

Trace the current flow and reuse existing sound machinery. Build the smallest
complete path across every necessary layer. For bugs, load [bug
diagnosis](debug.md), establish a red-capable signal, test hypotheses, fix the
root cause, and retain the original reproduction. For general work, choose the
appropriate creator and proof rather than forcing software files or tests.
Check no-change and existing-owner routes before adding a new mechanism. Apply
the [Craft](judges.md#craft-rubric) test to new state, caches, parsers, classes,
and contracts; a present trust, data-loss, accessibility, or recovery boundary can
earn a guard on its first demonstrated failure. An apparently dead code path does
not erase its accepted scenario. If a simpler scope supersedes planned machinery,
drop its dependent side quests and reassess depth and staffing.

Before implementation, the Builder proposes a preservation scope using
[knowledge guidance](knowledge.md): signals, affected accepted obligations,
selected checks, and gaps. Inspect changed and shared package contracts, APIs,
events, data or persistence paths, foundations, removed or renamed files, test
expectation changes, and Spec, decision, or KB edits. Paths narrow discovery;
exported contracts and actual semantics expand it. Keep the proposal proportional
and record it in the Build handoff.

Dispatch Workers under [concrete staffing](workflows.md#concrete-staffing), showing
ownership and sequencing first. Each Worker gets accepted
constraints, seams, source anchors, owned paths, proof, stop conditions, and a
return contract. One writer owns a hot seam; the Builder integrates and tests the
combined result. A Worker return or local green check is not a candidate verdict.

Simplify before independent Review: remove accidental duplication, unused layers,
speculative compatibility, unnecessary configuration, and review-driven
scaffolding while preserving accepted behavior and proof. Clean focused work can
record a justified no-op. Direct “Forge simplify” performs this bounded Build
operation without becoming a lifecycle phase.

Before independent Review, assemble the complete actual candidate diff: code,
tests, any directly applied canonical Spec, earned factual knowledge edits, and decision
references that the outcome changed. Supply the retained accepted baseline and
approved delta separately so canonical working bytes do not become their own
authority. Review and Acceptance bind to this same candidate. A document-only
receipt is provenance for the installed target; it is not Build evidence.

## Independent Review and repair

After internal review and required project checks, pin the exact candidate/base
and invoke [Review](review.md) with a separate Reviewer. Record Build, Review,
findings, dispositions, repairs, exact candidate, and the preservation scope in
[build-log.md](../assets/build-log.md). Keep actual Acceptance evidence under `verify/`.
The Reviewer challenges the Builder's scope and the canonical Spec/KB diff when
the candidate carries intent or factual updates.

Admitted P0s and pragmatic P1s return the whole accepted packet to the Builder.
Group symptoms by state owner, lifecycle, or contract and repair the shared cause.
Reassess the complete outcome and affected proof; a changed candidate needs a new
independent verdict. P2 advice never extends the loop. Use the finite rethink and
stop contract in the main skill.
If repeated repairs to the same mechanism do not converge, revisit its owner and
invariant at the existing RETHINK boundary rather than growing case-by-case guards.

## Completion

Return candidate/base identity, built behavior or deliverable, actual commands and
observations, independent Review verdict, unresolved gaps, and direct-Build
boundary. Review PASS establishes engineering judgment at that candidate, not
runtime acceptance.

# Executable mechanics

The executable `forge` CLI is a thin local helper. It creates and validates
managed documents, initializes loop records, protects decision operations, checks
or applies prepared memory changes, queries the local knowledge corpus, and runs
candidate identity checks. It also serves a selected artifact directory on localhost.
It does not parse a semantic “forge spec” request,
select a phase or persona, approve meaning, judge a candidate, or advance delivery.

After a public install, the binary lives at `~/.local/bin/forge`. From a project
directory, install skills, then initialize a loop:

```bash
forge setup
forge init LOOP_ID --title TITLE
```

`--repo` defaults to `.`. `setup` copies skills into the project from GitHub, or
from `--pack` when you pass a local package directory. `init` creates loop
records. Do not run these from `~/.local/bin`; that directory is not a pack root.

Default `--tools` is `agents` (Cursor, Codex, and Muse Code). Claude Code
users must pass `--tools claude`, or pipe the curl installer into
`FORGE_TOOLS=claude sh` (the assignment goes on the `sh`, not on the `curl`),
and then read `.claude/skills/forge/SKILL.md`. Pass `--tools cursor` or a
comma-separated list when a project uses more than one host. Unknown tools fail.

From the Forge package directory in a source checkout, inspect the live contract before using it:

```bash
bun run build:cli
./dist/forge --help
```

The checked-out contract is:

```text
forge setup [--repo REPO] [--tools LIST] [--pack PATH]
forge init LOOP_ID --repo REPO --title TITLE
forge serve DIRECTORY [--port NUMBER] [--json]
forge docs create KIND PATH --repo REPO --title TITLE [--code CODE] [--body-file FILE]
forge docs update PATH --repo REPO [--body-file FILE] [--set KEY=JSON_OR_STRING]
forge docs validate [PATHS...] --repo REPO
forge docs append PATH --repo REPO --heading HEADING --body-file FILE
forge decision record [LOOP_DECISIONS_PATH] --repo REPO --authorization-file FILE --body-file FILE [--title TITLE] [--supersedes Dn-or-existing-legacy-id]
forge candidate --repo REPO [--path PATH ...] [--expect ID]
forge memory verify|apply MANIFEST --repo REPO
forge kb ask QUERY --repo REPO [--scope SCOPE ...]
forge kb verify --repo REPO [--scope SCOPE ...]
forge kb history --repo REPO
forge kb add|update|remove MANIFEST --repo REPO
```

## Artifact previews

`forge serve DIRECTORY` runs a foreground static server bound to `127.0.0.1`.
The directory is explicit and relative to the command's working directory; it
does not use `--repo` or need a Git checkout. The default port is `0`, selecting
an available port. An explicit occupied port fails instead of silently changing.
Read the printed URL; never guess the port. `--json` prints one readiness record
with `root`, `url`, `port`, and `pid` after the socket binds.

Serve the artifact directory containing `index.html` and its local assets. Nested
directories serve their own `index.html` and redirect to a trailing slash so
relative assets resolve. Files are read fresh on reload with caching disabled.
HTML, CSS, JavaScript, images, PDFs, Markdown and other ordinary files retain
their file MIME types; Markdown is served as a file, not converted to HTML.
Missing files or directories without an index return 404; there is no listing or
SPA fallback. Dotfiles and symlinks under the selected root are not served.

Keep the process in a host-owned terminal/session for as long as the preview is
needed. Ctrl+C or SIGTERM closes the server and releases the port. No daemon,
server registry, project command runner, transpilation, Vite installation, or
browser launch is involved. Use the project's existing dev/build pipeline when
an artifact needs framework imports or compilation, then serve its built output
or use that project's running preview. The browser's Reload action picks up file
edits; no live-reload script is injected into artifacts.

Readiness proves a bound local server. The host must open the returned URL and
inspect the actual asset/revision before claiming rendered proof. Keep local
preview lifetime separate from durable artifact paths and external publication.

## Document metadata and edits

The CLI assigns `id` (UUID), readable `code`, immutable `type`, `title`, `status`,
`createdAt`, and `updatedAt`. Codes contain letters/numbers separated by `-`, `_`,
or `.`. Creation/identity fields stay fixed; use `--set` for other metadata.
Spec/Issue scaffolds are drafts. Initialized indexes and logs are active containers;
neither state means that their contents are approved or their claims proved.

Required metadata uses top-level scalar values. CLI values use JSON-compatible
strings, lists, or objects in YAML frontmatter. This is a deliberately scoped reader,
not a general YAML implementation: unknown nested/block metadata is retained
verbatim during ordinary body edits, but is not interpreted as authority or schema.
`--body-file` accepts body-only Markdown; direct file tools may edit the ordinary
body while preserving its frontmatter. On creation, a missing top-level heading
is supplied from `--title`; an existing heading is retained and empty bodies are
rejected. Updates still require a descriptive heading. `docs validate` with no paths checks the
explicit `.forge/identities.json` corpus; pass paths to check a specific draft.

Edit ordinary document bodies using normal file tools, then validate relevant
managed paths. A decision authorization file is JSON with `actor: "human"`, a
local transcript path or URL in `source`, an actual `quote`, bounded `scope`,
and an ISO `date`. The operation checks a local quote and embeds the context; it
does not authenticate the human. Generic document updates cannot create or
overwrite decision authority.

`forge decision record [LOOP_DECISIONS_PATH]` records the authorized decision in
the canonical decisions bundle, assigns the next readable `D1`, `D2`, or later
code, updates the numeric decisions index, and retains a memory receipt. When a
loop decisions path is supplied, it also records the canonical reference there.
The path may be omitted for standalone recording. `--supersedes` accepts a
canonical D-number or an existing legacy decision identity; supersession creates
a new record and preserves the prior one.

After human approval, specification and associated knowledge reconciliation is
prepared by a qualified specialist and checked for boundary fidelity. The natural
skill request `Forge spec apply <change>` then uses the existing executable
`forge memory verify MANIFEST --repo REPO` and `forge memory apply MANIFEST --repo
REPO` with `application: spec`. Natural-language `Forge spec merge` maps to the
same skill operation; there is no executable Spec apply or merge alias. Generic
memory and explicit delivery-history jobs omit that discriminator and remain
compatible. `forge kb ask`
queries the canonical local corpus and must return cited sources and explicit gaps.
Read [memory](memory.md) for the prepared-change contract and current exact syntax.

`forge kb history` is receipt-derived. It summarizes successful applied memory
operations from `.forge/memory/`; it does not treat a manual log, a failed
operation, or structural validation as shipped behavior or compliance proof.
Malformed or incomplete receipts are reported as issues. An integrated delivery
with no canonical document delta can be recorded explicitly through `forge memory
verify` and `forge memory apply` with an empty `changes` list plus human
authorization and nonempty source, evidence, and acceptance references. KB write
verbs reject empty changes. This receipt does not imply deployment or publication.

Canonical `docs/specs` and `docs/knowledge` are protected from generic document
writes. Prepare drafts under a loop or another ordinary path, pin proposed hashes
and independently retained authority inputs, then use memory verify/apply after approval.
Its document-only receipt does not establish implementation, Review, Acceptance,
or Ship.

Candidate identity excludes `.forge` loop mechanics by default, avoiding
self-invalidating verdict writes. It includes tracked, untracked, deleted, mode,
and symlink state for selected paths. Include changed accepted Spec/decision paths
explicitly with repeated `--path`, or separately pin their exact accepted
revision in the packet.

Treat `--help` from the checked-out version as authoritative. Do not invent a
command or substitute shell writes for a protected operation. CLI success
establishes only the mechanical claim named by that operation.

# Bug diagnosis

Treat a bug as a discrepancy between accepted expected behavior and observed
behavior. The report or [bug template](../assets/bug.md) records expected and
actual results, impact, environment, reproduction steps or evidence, and relevant
Given/When/Then scenarios. A conflict with standing behavior is a human decision.

Before source edits, reproduce through the lowest realistic seam when possible.
Record observations separately from hypotheses. Rank falsifiable hypotheses by
fit and cost, then run the cheapest observation that distinguishes them. Revise
the explanation when evidence falsifies it; do not preserve the first plausible
story.

Trace the behavior through real callers and shared state owners. Fix the common
cause and inspect affected siblings rather than patching one visible symptom.
Remove temporary probes after diagnosis. Preserve the original reproduction as
acceptance proof and add focused regression evidence at the correct seam.

If the behavior, expected result, environment, or required access cannot be
established, report the exact gap instead of guessing. Hotfix urgency can narrow
depth and sequencing; it cannot waive accepted intent, independent Review, the
original-reproduction check, or honest proof limits.

# Design direction and craft

Use this during Design, UI Build, and Design review when the target harness has
not selected a replacement. It is Forge's own baseline guidance; no external
skill or design service is required. Selected specialists refine these choices
within the same accepted scope. Study assembly and proof live in
[design studies](design-studies.md); review admission lives in
[the Design rubric](judges.md#design-rubric).

## Choose a direction from the job

Identify what a person must notice, understand, and do. An operational screen
prioritizes state and efficient action; a reading surface prioritizes structure
and comfortable reading; a persuasive surface needs credible reasons to act;
an exploratory artifact can let its content lead. These are questions for
judgment, not styles to impose on whole product categories.

For existing UI, begin with its actual components, typography, tokens, assets,
content and interaction conventions. Refinement preserves that identity and
behavior outside the requested delta. A replacement needs explicit scope.
For a new surface, use nearby established patterns. For a genuinely new product,
propose a coherent direction grounded in its audience and material; distinguish
a recommendation from human approval.

Describe the visible problem and the proposed effect in one concrete sentence.
For example, “The filter produces an unexplained blank; keep the surrounding list
layout and show the active scope with a way back to results.” Choose the principal
change that solves it: hierarchy, grouping, density, reading, state, or recovery.
Other adjustments should support that change. Do not require a named style,
aesthetic dial, invented alternative, or decorative signature for a small fix.

## Make the direction visible

Use the relevant questions below, not a checklist of mandatory treatments.

| Concern | Design judgment | Evidence to inspect |
| --- | --- | --- |
| Hierarchy and layout | Let the primary task lead. Use proximity and alignment to express relationships before adding containers. Preserve information needed to act. | At normal size, can someone distinguish current state, primary content and next action? Does grouping survive a narrow viewport? |
| Typography and content | Reuse the system's type roles. Tune measure, weight and line spacing to real content; keep labels distinct from values. Keep product terms and factual claims intact. | Long names, wrapping, truncation and fallback fonts; can a person still read and identify the item? |
| Color and contrast | Give color a semantic job. Reuse established action and status roles; include text or shape for meaning. Compare actual foreground and background pairs. | Text, controls, focus and selected states remain distinguishable; muted content is still readable. |
| Density and responsiveness | Choose what wraps, reorders or scrolls according to the task. Preserve meaningful relationships and reading order. | Actual product viewport, not a scaled desktop image; long content and controls at narrow width; any deliberate scrolling is usable. |
| Interaction and recovery | Prefer the target's native or established controls. Make the action, immediate feedback and recovery understandable. Include only states earned by the journey. | Mouse and keyboard activation, focus after updates, repeated actions, and relevant empty/error/pending states. A screenshot cannot prove these. |
| Imagery and motion | Use imagery to explain the subject or establish relevant character. Motion should explain change or provide feedback without blocking action. | Text remains real and readable, assets have a purpose, reduced-motion behavior is usable when animation is present. No image or animation is required. |

Visible labels, semantic controls, useful focus indication and understandable
reading order are part of the design. Avoid simulating an interactive control
with an inert decoration. If a study omits an out-of-scope interaction, disclose
that locally rather than pretending it works. Do not invent destructive,
optimistic, or persistence behavior to make a prototype feel complete.

## Critique the outcome

Inspect the rendered result against the user job and incumbent or accepted
visual authority. Start with the strongest claim the design makes and try a
plausible counterexample: an unusually long existing name, narrow width,
keyboard-only recovery, or a state transition that removes the focused control.
Select checks that could change the recommendation, not a universal state matrix.

Separate a demonstrated failure from another valid treatment. Explain the user
consequence and location of a material issue; avoid judgments such as “not premium”
or demands for more visual novelty. Batch related corrections, preserve the
whole intended outcome, and follow the study workflow's bounded inspection cycle.
A study recommendation and successful local inspection do not approve a design
or establish production Acceptance.

The handoff should make the direction buildable: what changes, what stays,
which states and responsive transformations matter, and what the rendered
artifact demonstrates. Put this in the existing design/visual record; no extra
report or phase is required.

# Codebase-anchored design studies

Produce one browsable page that helps the human understand a proposed UI change.
Use this during Spec Design when a visual decision needs a mock, study, or board.
A direct request stops with the study and its handoff. A small Build patch with
an accepted design reuses that design; it does not earn a new study or approval gate.

The Designer owns the direction and rendered critique. Read the target harness
and [design direction and craft](design-direction.md), or the selected replacement
design specialist, first. Their craft guidance informs this
artifact within Forge's phase and authority boundaries.

## Ground the decision

Start with what the user must accomplish: operate a tool, understand information,
make a decision or explore an artifact. Let that job determine hierarchy, density
and expression. State whether this is a refinement within the incumbent system
or an authorized replacement. Choose one coherent treatment that serves the job;
do not stack unrelated styling moves to make the study look more elaborate.

Name the user, task, proposed change, preserved behavior, and decision the page
must make visible. Preserve the incumbent visual system unless the user asks to
replace it. Missing design documentation does not make an existing app greenfield.

Inspect the target route or surface, its nearest components, tokens/theme and
assets, representative content and state behavior, and package manifest. Record
a short source map in the existing Design or visual record: repository revision
(including relevant dirty changes), paths and symbols, what is reused, and what
is proposed. Read the implementation behind each anchor; a plausible path is not
grounding. Use faithful fixture content and label it as illustrative.

When runnable, inspect the current surface in the browser. Distinguish a captured
baseline from a source reconstruction. If runtime, credentials, source, or assets
are unavailable, label the affected frame and evidence gap; never present a
reconstruction as an observed screenshot. A new surface uses a nearby incumbent
pattern as context, without inventing a before screen.

## Compose one study page

Start from [design-study.html](../assets/design-study.html). Copy and customize it
as an ordinary visual asset, usually `spec/studies/<slug>/r1/index.html`. Use the
existing [Design](../assets/design.md) and [visual companion](../assets/visual.md)
records for intent and identity. Scaffold the companion with `forge docs create visual`
using [CLI mechanics](cli.md), edit its body, and run `forge docs validate` before
handoff; copying a Markdown template or inventing frontmatter does not create a
valid managed record. For a small study, the existing ticket plus one
visual record can carry the brief and source map; do not duplicate prose.

Template the presentation structure, not the product screens:

- **Brief strip:** change, decision, exact revision, proposed/exploratory/accepted
  status, and a visible link to the companion record.
- **Main frames:** a believable slice of the real product with enough surrounding
  context to understand the change. For a refinement, normally show current and
  proposed with the same content, state, viewport, and scale. For an unresolved
  choice, show two or three materially different treatments, explain tradeoffs,
  and recommend one. A single clear direction needs no invented alternatives.
- **Material states:** add only the narrow viewport, empty/loading/failure,
  focus, or other state that the actual decision earns. Give frames stable IDs,
  state, viewport dimensions, evidence type, and revision. A responsive board
  does not prove that the represented product is responsive.
- **Annotations:** put short consequences next to the relevant frames. Separate
  observed behavior, proposed changes, preserved commitments, and open questions.
  Favor product language; keep technical anchors in a compact source section.

Use quiet board chrome and let the product occupy most of the page. The starter's
type, colors, and frame sizes belong to its chrome, never to the target app. Reuse
installed project components when a local preview seam makes that straightforward;
otherwise use an explicitly labelled faithful HTML/CSS reconstruction. Copy only
the necessary tokens and primitives with source anchors. Do not flatten a real
product into generic cards, fake metrics, or a new aesthetic chosen by category.

Plain HTML/CSS with small local scripts is the default for a bounded study. Use
the existing project preview stack only when imports or interaction fidelity earn
it. Isolate frame CSS from board chrome: an iframe gives a real viewport for media
queries; scoped CSS alone does not. Label a scaled desktop frame as scaled desktop,
not mobile proof. Keep full-size frames inspectable through local scrolling or a
frame link. The page itself must remain readable on a narrow screen and keyboard
usable. Model decision-critical interactions locally, label simulated behavior,
and avoid live writes or real account actions from the study.

No editor, canvas engine, new runtime dependency, generated image, or external
design account is required. An existing accepted external design can remain the
visual authority; do not rebuild it just to fit this starter. Use image generation
only when the requested visual material earns it, not to rasterize core UI text
and controls. Respect the host's filesystem and preview capabilities; do not
invent preview URLs or a Forge rendering command. HTML is not a managed Markdown
document and does not go through `forge docs create`.

## Inspect the actual artifact

For static studies, use the executable `forge serve <study-directory> --json`
from [CLI mechanics](cli.md) and keep it running in a host-owned terminal/session.
Open its returned URL and verify that it shows this revision. If the executable
or local listening capability is unavailable, use an available host preview and
report the actual mechanism and gap. Framework-backed studies use their existing
project preview pipeline. Inspect rendered desktop and narrow views together, including
the product frames at their declared viewports. Exercise decision-critical controls
and keyboard focus; check content, clipping, readability, contrast, and material
states against the brief. Capture and view the resulting images. Repair material
defects in one batch and recapture once; name remaining gaps rather than extending
a cosmetic polishing loop. Existing Forge defect escalation still governs blockers.

Save preview observations and final screenshots beside the study, linked from
the companion. This is study inspection, not production Acceptance; do not place
it under `verify/` as if the application had passed. If browser proof is unavailable,
return the useful artifact with inspection pending and the concrete gap. Source
inspection or a generated image cannot substitute for rendered proof.

## Hand off and preserve authority

Return the page path, verified preview URL (mark ephemeral when applicable), exact
revision, final image paths, recommendation/tradeoff, source map, and gaps. Keep
the companion's represented-state links synchronized with actual frame IDs.

A recommendation, selected comparison, local toggle, screenshot, or reviewer PASS
never records human acceptance. Reuse actual human authority when it covers the
same choices; otherwise keep the page proposed and ask only for the consequential
decision after making it reviewable. Record accepted revision, states, materially
locked choices, and Builder latitude in the existing visual record. Preserve an
accepted revision before making a new proposal; editing a proposed study does not
silently update accepted intent.

When an accepted asset lives under `.forge`, explicitly include its revision and
companion in the Review/Acceptance authority packet or selected candidate paths;
the default candidate check excludes loop mechanics. Bind screenshots to the
inspected asset revision and recapture affected states after edits.

Build follows the accepted choices and reuses production architecture rather than
shipping disposable study code. Review and Acceptance compare the real candidate
against the exact accepted frames and interactions, including material preserved
states. Unaccepted variants remain decision evidence, not requirements.

# Lifecycle composition

Full delivery accounts for `Spec → Plan → Build → Acceptance → Ship`. Each phase is
also a useful stopping boundary. The coordinator records whether a phase ran,
reused current accepted evidence, remains pending, or is blocked; absence is never
silently treated as success.

Start with [Launch and workflow selection](workflows.md). Quick/Full depth governs
preparation and staffing; Guided/Auto governs pauses within explicit authority.
Launch is an opening step, not another phase. Review stays inside Build and
`verify` selects Acceptance, not an additional phase.

| Entry | Result and stopping boundary |
| --- | --- |
| Explore | Answers a question or compares approaches; creates no delivery authority |
| Spec | Defines and approves proposed intent without routine canonical writes |
| Plan | Defines the implementation approach and useful outcome Issues |
| Build | Produces one integrated candidate, simplifies it, and obtains independent Review |
| Review | Judges one pinned candidate without editing it |
| Acceptance | Exercises the actual Review-passed outcome |
| Ship | Checks the complete accepted candidate once, records concise closure, and performs authorized publication |
| Finish | At actual work completion, reconciles approved unapplied memory and authorized existing-PR readiness; direct Spec and Plan remain proposal-only |
| Spec apply / legacy Spec merge / KB | Maintains canonical meaning directly, without claiming software delivery |

A full run may reuse an accepted ticket as Spec and record a one-sentence Plan for
a tiny change. It still accounts for those phases. A direct Build or Review stops
without inventing broader acceptance. An Acceptance failure returns to Build,
then affected independent Review and Acceptance. A human-owned semantic decision
returns to the human.

Before moving forward, record the exact candidate, accepted sources, current gaps,
and authority for the next action. Publication, merge, deployment, release, or
production changes require the corresponding user authority.

# Finish

`Forge finish <loop>` is a natural operation inside the existing Forge skill, not
a sixth phase, separate skill, or executable `forge finish` command.

Run routine Finish only at actual work completion: normally after Build or a later
earned boundary, or after a general-work deliverable is complete. A direct Spec or
Plan request remains proposal-only and does not run Finish. An explicitly
authorized direct `Forge spec apply <change>` remains a separate operation.

Inspect the active repository and loop for approved unapplied standing-Spec or
knowledge changes. The two are optional and independent. The active repository
owns its canonical memory; never default another repository's work to Bright. A
deliverable such as a newsletter article is not automatically knowledge.

For an approved unapplied standing-Spec change, invoke `Forge spec apply <change>`
once. That operation alone owns preparation, its single adversarial read, and
guarded verify/apply. For approved knowledge-only work, invoke the existing
guarded KB or memory operation; its owner performs one equivalent fresh
proportional adversarial read before mutation. Finish does not prepare the same
result or add another review. Skip categories with no approved change; do not
create placeholder proposals or receipts.

Persist the resulting repository changes normally within current Git authority.
If Finish or the accepted Launch authorized readiness and exactly one existing PR
belongs to the active branch, a normal non-force push of the exact Finish commits
to that associated head and draft-to-ready are within that bounded authority.
Verify the observed repository, branch, head, and PR state. An already-ready PR or
no PR is a no-op. Report ambiguity or unavailable discovery instead of guessing.
Never create or reopen a PR, force-push, merge, deploy, release, or publish.

On retry, inspect existing receipts and current canonical bytes, Git state, and PR
state. Matching applied bytes and an already-completed PR transition are complete;
do not replay them. Preserve successful earlier work when a later step failed and
resume only the remaining authorized action. Record what actually happened, what
was skipped, the observed receipt/Git/PR result, remaining gaps, and limits in the
ordinary loop index and log.

# Intake is part of Spec

Forge has no separate Intake phase or command. Route context gathering, source
retrieval, workflow detection, informed questions, and authority framing through
[Spec](spec.md). For open-ended investigation with no intended artifact or delivery
commitment, use [Explore](research.md).

# Review judges

The independent Reviewer owns coverage and the integrated verdict. These are five
review responsibilities, not five mandatory agents. Do not omit an applicable
dimension because a change is small.

## Staffing

Use [concrete workflow staffing](workflows.md#concrete-staffing), including its
precedence when both expanded-Review triggers apply. Record the observed trigger
and actual dimension owners. Without either trigger, one Reviewer covers every
applicable dimension with evidence and a verdict in one compact report. Each
required Judge owns one dimension in a separate read-only context; Reviewer
integrates original returns and covers undelegated dimensions. Shared authority
and checks need not be duplicated. Staffing never waives coverage or Acceptance.

## Applicability and ownership

| Dimension | Applies when | Bundled source and responsibility |
| --- | --- | --- |
| Code Review | Code (including UI markup and styles), tests, executable configuration, or agent instructions that control execution change | [Forge Code Review](../../forge-code-review/SKILL.md): defects, regressions, security, code/test quality, lint/types, engineering standards |
| Design | UI behavior, rendered surfaces, or UI design artifacts change | Design rubric below: accepted visual fidelity, interaction states, accessibility, UI conventions |
| Quality | A knowledge-work deliverable is the reviewed outcome | Quality rubric below: accuracy, completeness, reasoning, usefulness, writing/artifact standards |
| Spec | Every candidate | Spec rubric below: approved end state, constraints, omissions, invented requirements, preservation |
| Craft | Every candidate | Craft rubric below: proportionality, overbuilding, underbuilding, current evidence of necessity, justified mechanisms and remedies |

UI markup and stylesheet changes, including CSS-only changes, activate both Code
Review and Design: Code Review inspects source correctness and engineering
standards; Design inspects rendered fidelity, interaction, and accessibility. A
pure design artifact without a code change activates Design without Code Review.

Accompanying software docs, plans, and loop records do not routinely activate
Quality. The Reviewer checks their managed-artifact contract during integration.
A separately requested report or document deliverable does activate Quality.
There is no Standards or Evidence judge: standards belong to their owning
dimension and evidence is required from each. Code Review reads acceptance criteria
to establish correct behavior; Spec owns the exhaustive intent audit. Craft does
not replace code-quality inspection. Route an obvious concern outside a judge's
remit to its owner with evidence, without performing a second full audit.

## Selection, replacement, and disable

Resolve each applicable dimension in this order: explicit current user choice,
applicable repository harness, bundled source. Read the actual selected skill or
rubric; a name or remembered description is not its procedure. A replacement gets
the same boundary, authority, read-only contract, evidence bar, and report schema.
It cannot recursively invoke Forge Review or create another panel.

Selection is human-readable guidance, not configuration or a plugin API. For
example, a repository's AGENTS.md may say:

```text
For Forge Review, replace the Code Review dimension with .agents/skills/team-review/SKILL.md.
For Forge Review, replace the Design dimension with .agents/skills/ui-review/SKILL.md.
```

A user can instead say, "Disable the bundled Code Review skill and use the team
review skill for Code Review." This replaces the implementation, retaining
coverage. "Disable Design for this review" skips that dimension with the reason,
authority, and exact scope recorded; never silently run its bundled default.
Disabling coverage is not proof it passed. Report `DISABLED`, distinct from
`NOT_APPLICABLE` and a returned verdict. A missing explicitly selected replacement
is a gap; do not fall back unless that fallback is already authorized.

Only an explicit human waiver of the omitted coverage can permit an integrated
`PASS` scoped to the remaining dimensions; label that PASS with its excluded
dimension and waiver. A harness disable alone or an agent's tool limitation does
not supply that waiver. Otherwise required disabled or unavailable coverage
precludes PASS. No selection can rewrite accepted requirements or waive required
runtime Acceptance. Preserve user choices through the existing authority records.

## Shared investigation and admission

Try to break the change. Choose plausible counterexamples to its strongest claims,
follow real consumers, and test consequential failure paths. Then challenge your
own allegation: inspect existing safeguards and equally valid implementations.
There is no finding quota. A clean candidate earns a clean report.

Every admitted finding needs controlling authority, a reachable current trigger,
observed evidence or a concrete causal trace, and a material consequence. Name the
smallest honest severity and proportionate remedy boundary. Do not manufacture
nits, personal taste, speculative scale, hypothetical inputs outside the accepted
surface, or unrelated debt. Preserve real standards: an explicit material rule
violation is not dismissed as preference. A required proof gap remains a gap;
state the authority requiring that proof and the unproved claim, without inventing
a runtime failure. Reuse credible current proof and rerun only affected, missing,
stale, contradictory, required, or hypothesis-relevant checks.

## Design rubric

Use [design direction and craft](design-direction.md) as the bundled design
guidance, or the selected replacement. Challenge the primary user task with an
affected long-content, narrow-width, keyboard, or state-transition case. Check
actual type/color roles and content relationships against the incumbent system;
novelty and decoration are not quality requirements.

Load the target's accepted design revision, applicable UI standards, affected
journeys and states, and real rendering tools. Compare actual rendered output for
visual claims. Inspect hierarchy, legibility, alignment, clipping, overflow,
missing content, responsive behavior, and accepted fidelity. Exercise affected
interaction, loading/empty/error/success states, keyboard and focus behavior,
semantics, and accessibility. A screenshot alone cannot prove interaction.

Admit material drift from accepted visual authority or a demonstrated usability
or accessibility failure. Do not invent a redesign, demand pixel equality unless
required, or turn preferred spacing into a blocker. Source inspection may support
a causal accessibility finding; unavailable rendering remains a gap for visual
claims. State actual browser ownership and avoid concurrent browser mutation.

## Quality rubric

Load the deliverable's purpose, audience, accepted questions, source requirements,
and routed writing/artifact standards. Check material claims against their sources,
reasoning from evidence to conclusion, omissions that defeat the stated purpose,
internal consistency, usable structure, and the actual rendered/exported artifact
when layout matters. Try a consequential counterexample or alternative explanation.

Admit factual error, unsupported consequential conclusions, accepted omissions, or
material artifact-standard violations. A different writing voice or an interesting
unrequested topic is not a defect. Disclose unavailable sources and proof limits.

## Spec rubric

Use the assigned candidate purpose and the [Reviewer’s current-obligation
guidance](../../../agents/reviewer/instructions.md) to distinguish preserved
standing behavior, work this candidate must deliver, and explicitly deferred work.

Load independently retained accepted baseline, approved delta, decisions, NFRs,
non-goals, and affected standing commitments. Trace each affected obligation forward
to implementation and proof, then trace material changes back to accepted intent
or legitimate implementation latitude. Check omissions, silent strengthening or
weakening, contradictory scenarios, unauthorized scope, and preserved outcomes.
The mutable candidate Spec or a matching receipt cannot establish its own authority.

Name direct evidence or a concrete gap for each affected commitment. Do not invent
requirements from tests, findings, descriptive knowledge, or synthetic users. A
necessary change to accepted intent goes to the human; it is not a workaround.

## Craft rubric

Judge the mechanism against the accepted problem and present operating conditions.
Challenge both unnecessary machinery and inadequate robustness at real trust,
data-loss, accessibility, and recovery boundaries. Follow the target's reuse
and simplicity standards; an equally valid tactic is not a violation.

A new named type, layer, Spec section, config knob, protocol, or dependency
needs current evidence. It is earned when removing it would break the asked
outcome or a present boundary, collapse distinct current meanings or invariants,
prevent independent work from sharing a contract it already needs, or when
concrete recurrence shows duplication now costs more than the abstraction.
Future flexibility, hypothetical scale, template completeness, and taste are
not evidence.

Apply this test only to the proposed machinery. Do not invent architecture to
justify a concept, and do not erase an earned distinction merely to reduce
concept count. Require a current consequence and a proportionate remedy. A
real defect needing a larger correction stays real and may warrant RETHINK;
disproportionate advice cannot become mandatory work.

# Knowledge and proportional preservation

The optional knowledge bundle helps agents retrieve accepted authority and
current system facts. It never proves compliance, acceptance, or runtime truth.

## Optional topic map

Create only the topics earned by the work. Do not bootstrap empty directories or
placeholder records. OKF concept types are open; the labels and templates below
are suggestions, not a registry.

| Topic | Questions it answers | Suggested type and template |
| --- | --- | --- |
| Domain | What terms, entities, and relationships mean | `Domain Concept`, [concept](../assets/concept.md) |
| Data | What models, schema, persistence lifecycle, constraints, tenancy, and reads/writes require | `Data Model` or `Persistence Contract`, [concept](../assets/concept.md) or [interface](../assets/interface.md) |
| Runtime | What services, workers, events, and runtime boundaries do | `Runtime Component` or `Runtime Contract`, [concept](../assets/concept.md) or [interface](../assets/interface.md) |
| Core processes | How business flows, actors, inputs, outputs, and recovery work | `Core Process`, [process](../assets/process.md) |
| Operations | How deployment, infrastructure, observability, and operating procedures work | `Operational Practice` or `Operations Contract`, [process](../assets/process.md) or [interface](../assets/interface.md) |
| Shared foundations | Which auth, routing, library, and design-system primitives other work relies on | `Shared Foundation` or `Foundation Contract`, [concept](../assets/concept.md) or [interface](../assets/interface.md) |

Use the repository's existing hierarchy and link maintained sources. Do not copy
standing requirements or code that will drift into a competing record.

## Preservation packet

Every loop records the smallest useful chain:

```text
signals -> affected obligations -> selected checks -> gaps
```

Consider these signals: package ownership; internal or public APIs, events, and
shared types; database or schema changes; persistence lifecycle, constraints,
tenancy, or read/write paths; shared auth, routing, libraries, or design
primitives; deleted or renamed files; removed, skipped, or expectation-changing
tests; and Spec, decision, or KB edits. Package paths narrow discovery. Exported
contracts and actual semantics expand it.

The obligations name affected and preserved scenarios, NFRs, decisions, domain
terms, processes, APIs, data rules, and design intent. The checks cover the
changed or new outcome, affected unchanged outcomes, and material failure paths.
Record unavailable evidence or unresolved scope as gaps. A path list is not a
preservation verdict, and a full-product replay is not required for every patch.
For a tiny change, a one-line scope or justified no-op is sufficient. Do not
inventory unrelated untouched areas.

## Ownership and timing

Spec and Plan record approved domain, API, process, data, runtime, operations, and
design intent without routine canonical writes. Direct Spec apply or Finish later
uses guarded memory mechanics for approved changes in the active repository. The
Builder finishes factual observations as implementation becomes observable and
proposes the preservation scope. The Reviewer challenges it. Acceptance exercises
affected unchanged and changed or new outcomes. Ship checks the complete candidate
once and records concise closure.

Use `forge kb ask` to retrieve authority. Use `forge kb history` to inspect
successful receipt-derived changes. KB search and structural verification never
establish implementation compliance.

# Canonical specification and knowledge memory

Forge stores accepted behavior once at `docs/specs/<capability>/SPEC.md`. Supporting
knowledge is a native OKF v0.2 bundle rooted at `docs/knowledge/`. Every
non-reserved `.md` file is a concept with a non-empty `type`; concept types and
directory hierarchy are open. `index.md` and `log.md` are reserved at every
level, and the bundle-root index may declare only `okf_version` frontmatter.

This is distinct from the strict Forge record corpus: `.forge/` workflow files
and `docs/specs/` standing specifications keep their own identities, authority,
and metadata schemas. Knowledge paths remain protected from generic `forge docs`
writes. See the [OKF compatibility boundary](../../../OKF.md) for the supported
consumer and producer claims.

Use [knowledge and proportional preservation](knowledge.md) for the optional
six-topic reading map and the signals -> affected obligations -> selected checks
-> gaps handoff. OKF types stay open and no topic or corpus is mandatory.

## The applying operation owns preparation and review

The responsible Spec or knowledge specialist reads the base, current canonical
file, source intent, relevant decisions, and every affected requirement and
Given/When/Then scenario. They prepare complete proposed files, identify preserved
meaning, and return conflicts to the human. A heading match or successful CLI
check cannot decide semantic preservation, approval, or implementation truth.

`Forge spec apply <change>` requires an approved change and an explicit request or
authority, whether called directly or once by [Finish](finish.md). The operation's
responsible owner prepares complete target bytes from the approved meaning and
current canonical base. One fresh independent agent with no write ownership then
performs a proportional read-only adversarial review of the complete changed
result plus directly affected canonical documents—not the whole corpus by default.
It checks contradictions, omitted or distorted approved commitments,
meaning-changing duplication, broken requirement/scenario meaning or normative
links, and wrong-repository targets.

Record the checker's concise `PASS` or `BLOCKED` verdict and material findings in
the loop log when one exists, otherwise in the direct operation result. The checker
cannot rewrite the proposal or approve changed meaning. `BLOCKED` stops before
mutation; on `PASS`, use the existing guarded verification and application
mechanics below. Preparation, this single adversarial read, and guarded apply are
one Spec-apply sequence. Finish never repeats them. This is not a panel, lifecycle
Review, durable report protocol, or whole-corpus review.

Human decisions use the guarded command
`forge decision record [LOOP_DECISIONS_PATH] --repo REPO --authorization-file FILE
--body-file FILE [--title TITLE] [--supersedes Dn-or-existing-legacy-id]`. It
assigns the next canonical `D1`, `D2`, or later code, updates the numeric
decisions index, retains a receipt, and optionally links the canonical decision
from the loop record. Omit the loop path for a standalone decision. It never
silently rewrites a prior decision.

## Prepared manifest

`Forge spec apply <change>` is a natural skill operation, not an executable
subcommand. The Spec owner prepares the version 1 manifest and uses `forge memory
verify MANIFEST --repo REPO`, then `forge memory apply MANIFEST --repo REPO` only
after the inputs and single adversarial read above pass. Existing generic memory
and KB jobs remain compatible. Natural-language `Forge spec merge` means this same
skill operation; there is no executable Spec apply or merge command.

Finish invokes this natural Spec-apply operation once; there is no executable
`forge finish`.
Standing-Spec and knowledge changes are optional and independent. Record each
successful receipt. On retry, matching receipts and installed bytes are complete;
do not replay them.

```json
{
  "version": 1,
  "application": "spec",
  "operation_id": "SPEC-ACCESS-02",
  "authorization_file": ".forge/prepared/access-authority.json",
  "proof": {
    "status": "document-only",
    "source": [".forge/loops/access/spec/change.md"],
    "evidence": [],
    "acceptance": []
  },
  "retained_inputs": [
    {
      "role": "accepted-baseline",
      "source": ".forge/prepared/access-baseline.md",
      "sha256": "<64 lowercase hex characters>"
    },
    {
      "role": "approved-change",
      "source": ".forge/loops/access/spec/change.md",
      "sha256": "<64 lowercase hex characters>"
    }
  ],
  "changes": [
    {
      "path": "docs/specs/access/SPEC.md",
      "kind": "standing-spec",
      "action": "update",
      "base_sha256": "<64 lowercase hex characters>",
      "proposed_file": ".forge/prepared/access-SPEC.md",
      "proposed_sha256": "<64 lowercase hex characters>",
      "metadata_changes": ["updatedAt", "status"]
    }
  ]
}
```

Every proof field is a list of existing repository files or HTTP(S) references.
`source` is always required. `integrated` also requires evidence and acceptance;
`document-only` may leave those lists empty and never claims implemented behavior.
Reference existence is checked, not authenticity or evidentiary sufficiency.

The authorization file is JSON with nonempty `actor`, `source`, `quote`, `scope`,
and ISO `date`. `actor` must be `human`. For a repository-local source, the exact
quote must occur in that file; an HTTP(S) source is retained without a network
authenticity claim.

An `application: spec` manifest requires at least one `accepted-baseline` and one
`approved-change` retained input. An optional `context` input can retain a named Issue, PRD, or
decision source. Local inputs use repository-relative paths and exact SHA-256;
the apply fails if any bytes changed. An HTTPS source uses `sha256: null`; its
address and evidentiary limit are retained, but Forge does not fetch or
authenticate it. Retain only the named authority inputs needed for recovery.

The accepted baseline, current write base, and approved change are distinct. Do
not reconstruct the accepted baseline from HEAD, the comparison base, or current
pre-apply bytes. A copied file or quote preserves evidence; it does not by itself
authenticate human approval.

Each change uses one of these exact Forge mutation kinds and canonical homes:

| Kind | Canonical path |
| --- | --- |
| [`standing-spec`](../assets/standing-spec.md) | `docs/specs/<capability>/SPEC.md` |
| [`concept`](../assets/concept.md) | Any non-reserved `docs/knowledge/**/*.md` |
| [`kb-index`](../assets/kb-index.md) | Any `docs/knowledge/**/index.md` |
| [`kb-log`](../assets/kb-log.md) | Any `docs/knowledge/**/log.md` |
| [`kb-decision`](../assets/kb-decision.md) | Legacy alias for `docs/knowledge/decisions/<name>.md` |
| [`process`](../assets/process.md) | Legacy alias for `docs/knowledge/processes/<name>.md` |
| [`interface`](../assets/interface.md) | Legacy alias for `docs/knowledge/interfaces/<name>.md` |

The generic `concept` mutation kind is independent of the document's open OKF
`type`. Legacy aliases preserve existing manifests without defining a type registry.

`add` uses a null base hash, a proposed file, and its exact proposed hash. `update`
uses the exact current SHA-256 plus a proposed file and proposed hash. `remove`
uses the exact current SHA-256 and null proposed file/hash. A Spec manifest requires
`proposed_sha256` for every installed file so a changed draft fails before any
write. Compatible generic memory manifests may omit it. Updates list every changed
frontmatter field in
`metadata_changes`. Standing-Spec identity and creation metadata remain immutable;
native OKF metadata can change under the same authorization and stale-base checks
while the separate Forge record identity remains stable. Forge writes
the proposed bytes without reserializing unknown YAML or Markdown, including
frontmatter fields it does not interpret.

An explicit identity-preserving rename is one `move` change with `path` naming
the new canonical path, `from_path` naming the old canonical path,
`base_sha256` and `proposed_sha256` both pinning the unchanged bytes,
`proposed_file: null`, and `metadata_changes: []`. The old and new path must have
the same kind, the target must be unused, and the registry identity moves with the
file. Only an `application: spec` manifest accepts moves. Never infer a rename
from headings or content, and do not encode it as a same-ID remove/add pair.

Validation rejects stale bases, repeated operation IDs, no-op updates, duplicate
targets or Forge identities, unsafe paths, and changes that break protected
standing-Spec links. An `application: spec` manifest additionally requires at
least one standing-Spec change and `proof.status: document-only`; it can never
claim integrated delivery. The complete set validates before mutation. Apply
stages files, transfers a registered prepared draft identity
to its canonical home, and records the manifest, human context, hashes, and
prior/removed bytes under `.forge/memory/<operation_id>.json`.

The immutable receipt records `application: spec`, the copied manifest and
manifest hash, authorization/source snapshots, retained input snapshots, and each
result's installed content/hash plus applicable previous or removed content. Its
status remains document-only after later work; Review and Acceptance create their
own candidate-bound evidence instead of rewriting historical provenance.

Participating local CLI mutations share one advisory lock through checks, writes,
and rollback. On failure, rollback undoes only completed writes whose installed
bytes and mode still match; it preserves intervening changes and reports an
incomplete rollback for reconciliation. Registry undo restores only owned entries.
Raw filesystem writers can bypass the advisory lock; this is not an atomic
transaction against external editors or recovery after process termination.

## Focused knowledge commands

`forge kb scaffold PATH --repo REPO --type TYPE --title TITLE --code CODE`
creates a Forge-identified OKF concept draft under `.forge/prepared/`. It cannot
write canonical memory. Applying the reviewed draft transfers its stable identity;
applying an external draft creates a sidecar identity without rewriting its bytes.
Reserved OKF files always keep identity in `.forge/identities.json` rather than
forbidden frontmatter. Forge reports the bundle-relative OKF concept ID separately
from this Forge UUID and readable code.

Identity transfer is limited to a registered `.forge/prepared/` source. Reusing
bytes from a standing Spec, canonical knowledge document, or other registered file
does not move that source's identity; the new record receives its own. Registered
legacy Forge indexes/logs remain inspectable as `forge-legacy` and nonconformant
until an explicit prepared update converts their bytes to native OKF while keeping
their sidecar identity.

`forge kb ask QUERY --repo REPO [--scope KIND ...]` returns lexical references
and explicit unmatched-term or unreadable-corpus gaps. Every retrieved file is a
`working-copy` observation with authority and implementation explicitly not
inferred. When a valid applicable receipt exists, the result includes its receipt,
operation ID, application, document-only proof status, recorded/current hashes,
and `matching` or `diverged` state. Malformed or diverged provenance is an explicit
gap. It does not synthesize a requirement or turn an old receipt into current
delivery truth. `forge kb verify --repo REPO [--scope KIND ...]` consumes the
native OKF bundle, checks required structure and Forge-owned identities, and
reports optional metadata-family, trust, staleness, and local-link conditions as
health output. Missing optional fields, unknown types or keys, and broken links
remain consumable; malformed required structure is reported as an issue.

When present, a bare `verified` mapping is normalized to one event before Forge
derives the advisory `unverified`, `machine-confirmed`, or `human-reviewed`
trust tier. These signals do not grant acceptance, authorization, or permission
to change the repository. Health output also does not establish semantic truth,
source authenticity, implementation compliance, or attestation.

Scopes are the Forge kind names in the table. With no scope, reading and
verification cover all supported canonical views and native knowledge documents.
Multiple scopes use a repeated `--scope` flag.

`forge kb history --repo REPO` reads successful memory receipts under
`.forge/memory/` and returns a concise changelog of applied Spec changes,
knowledge or decision maintenance, and evidenced system delivery. It does not
reconstruct failed operations or claim that a receipt proves semantic compliance.
Use the retained receipt and linked evidence for the exact operation and gaps.
Malformed, incomplete, and failed receipt-shaped files appear as history issues
instead of successful entries. This is structural validation of the retained
receipt envelope; Forge does not re-run its stale-base check against current files
or authenticate old sources while reading history.

A completed bug fix or refactor with no honest Spec or knowledge delta may still
use `forge memory verify` and `forge memory apply` with `changes: []` only when an
actual delivery-history record was requested. This narrow
delivery-only form requires `proof.status: integrated`, human authorization, and
nonempty source, evidence, and acceptance references. It records reviewed delivery
evidence; it does not imply deployment or publication and is not mandatory
paperwork for restorative work. KB add, update, and remove always require at least
one matching canonical knowledge change.

`forge kb add|update|remove MANIFEST --repo REPO` applies a manifest whose every
change matches that verb and targets only `docs/knowledge/`; it uses the same
human authorization and stale-base protections. Standing Spec changes use
`forge memory apply`. The KB operations can create or update prepared concept,
index, and log bytes, but do not import/export a corpus, bootstrap a repository,
or execute `resource`, `computation`, `executor`, or `attester` references.

# Plan

Plan translates accepted intent into the smallest useful implementation approach.
It never creates product requirements and always remains an explicit accounted
phase, even when its result is one concise note.

A substantial Plan opens with a short Summary, Context, and self-contained End
State, then a Plan of the smallest meaningful steps and proof. A brief Quick note
can stay in its Issue, index, or Build log without those headings.

For direct Plan, this procedure is the entrypoint; full-lifecycle setup is not a
prerequisite. Apply or reuse [Launch, depth, and workflow assignments](workflows.md)
only for this requested boundary. Plan can live as Issue notes or under `spec/`;
it need not be a separate document. Read the accepted Spec or ticket, applicable standing obligations,
relevant human decisions, current implementation, and target repository harness.
Accepted intent owns the outcome; code, plans and logs cannot invent requirements.
Return consequential conflicts to the human before dependent work. Reuse an
imported Issue rather than recreating it.

The Engineer owns technical strategy, decomposition and constraints. Product
Manager owns product scope and observable outcome criteria when those need
authoring; technical tasks stay with Engineer. Use the host's mapped professional
teammates when available, with Forge's judgment guidance for their assignment.
A precise engineering Plan over a ready Issue needs no new PM pass. For an Issue
request without a ready Issue or issue-like object, PM prepares the Issue, then
Engineer assesses it under the shared workflow rules, at either depth. Product
authorship does not add another Product approval gate.

For a small Issue, record the proposed route, existing machinery to reuse, proof,
and material risk. Do not create sub-Issues unless they improve ownership,
coordination, or reviewability. For a project, use [plan.md](../assets/plan.md) only
when additional coordination is useful and create meaningful outcome Issues from
[issue.md](../assets/issue.md). Keep Issue criteria observable and map behavioral
obligations to scenario IDs; never use “implement component X” as acceptance.

## Save the Plan at the requested depth

A direct Plan deliverable or a Plan that needs an independent handoff uses managed
identity and validation. For Quick Build, brief Plan notes may instead live in the
accepted Issue, loop index, or Build log. Do not create a separate Plan merely to
account for the phase. Resume an existing loop when it fits; initialize a new one
only when the work actually needs a managed record. Keep current state accurate
without inventing completed phases. Read [protocol](protocol.md) for additional
authority or handoff details when needed, not to populate every possible lifecycle
record.

When a separate managed Plan is needed, use the installed CLI to scaffold it, then
edit its body with normal file tools, preserving the generated frontmatter and a
descriptive `#` title. For a new loop and Plan, the commands are:

```text
forge init <loop> --repo <repo> --title <title>
forge docs create plan .forge/loops/<loop>/spec/plan.md --repo <repo> --title <title>
forge docs validate .forge/loops/<loop>/spec/plan.md --repo <repo>
```

Skip initialization when resuming; validation follows the body edit. For an existing managed record, update
that record and validate it instead of creating a duplicate. Replace or remove
unused template prompts in authored records; keep the plan, relevant pointers and
Build-pending state sufficient for the next owner. Unused decision and Build
records remain empty. Use a subcommand's `--help` if its syntax is uncertain;
the full [CLI reference](cli.md) is for operations beyond this procedure.

An already-approved ticket is source authority to reference, not by itself a new
request to install a canonical decision or bootstrap a KB. Link that ticket as
authority. A new human decision, not an empty decision file, warrants recording.

Before handoff, inspect the saved result once: the requested artifact exists and
validates; its proposed proof can distinguish the intended change; index/log
pointers and completion claims match observed tool results. Scope code checks to
code or tests so they do not count the ticket or Plan. Run safe discovery or
precondition checks where useful; an expected pre-change failure is different
from an unusable command. Do not implement the change to validate a Plan.

If a save fails, repair the cause and verify the result while tools are available.
Do not end with a promise to retry. Write dependent success entries only after
the operation succeeds; on failure leave accurate incomplete state and report the
gap. Structural validation alone does not prove the Plan sound or delivered.
Follow the host's authorized durable-storage/checkpoint policy, then stop before
Build. Checkpointing does not establish Acceptance or Ship.

A useful Plan covers:

- accepted outcomes, constraints, preserved behavior, and non-goals;
- current flow and reusable machinery;
- approach, material seams, dependencies, integration order, and one-way doors;
- each outcome's acceptance and proof;
- bug hypotheses and cheapest distinguishing observations when applicable;
- actual open decisions and explicit stopping conditions.

For changes that can affect existing behavior, include the compact
signals -> affected obligations -> selected checks -> gaps record from
[knowledge guidance](knowledge.md). Start with changed package ownership, APIs,
events, shared types, persistence, shared foundations, deleted or renamed files,
test expectation changes, and authority edits. Expand from paths when exported
contracts or actual semantics reach more consumers. The Builder proposes this
scope; it is not a path-only pass or a full-product replay.

Avoid speculative architecture, unrequested feature flags, configuration,
fixed agent counts, file-by-file instructions, and duplicated Spec prose. Builders own reversible tactics. If implementation
would require a semantic change, return the decision before dependent work.
Trace the actual flow first and use the existing owner or sound reusable pattern
when it meets accepted intent. If a new cache, parser, class, configuration, or
durable contract is proposed, state the current boundary or demonstrated cost it
solves and why the simpler route fails; use [Craft](judges.md#craft-rubric) to
judge whether it is earned. Do not plan away accepted scenarios because code now
appears unreachable. Preserve them as obligations or seek a scoped change.

In Guided, brief a newly consequential Plan in the conversation, link the
exact Plan, and obtain human approval before its boundary review. Auto uses the explicit grant without an ordinary pause and
records delegated authority, never human approval of unseen text. Existing
approval can be reused when it covers the same strategy. Independent Plan review
checks faithful coverage, technical soundness, proportionality, and usable
handoff without adding requirements. Carry loop domain, API, process, data,
runtime, operations, or design intent into the proposed reviewed KB update. A
direct Plan request stops after the result and records Build as pending, including
under Auto. Guided consequential revisions return to approval; do not dispatch
Build or edit production code while that approval is pending. Brief faithful
tactical notes inside accepted direct-Build authority create no extra human gate
or planning team. Before coordinated Build, show actual Worker ownership,
sequencing, and the integrating Engineer under the shared staffing rules.

# Authority, records, and handoffs

## Authority

The current human instruction and recorded human decisions own intent. Accepted
standing specifications plus an approved change own durable behavior. Project
harness rules and accepted technical/design decisions govern execution. Plans
organize delivery; source, tests, findings, logs, and descriptive knowledge are
evidence rather than authority.

Do not repair a mismatch by rewriting the specification to match current code.
Do not turn an agent proposal, discovered source behavior, prototype, review
finding, or synthetic-user reaction into a requirement. If accepted sources
conflict or changed meaning is needed, state the conflict, consequences, options,
and recommendation for the human.

A question, possibility, analogy, inference, or recommendation is not a decision.
For each normative addition, removal, or stronger guarantee, retain the exact
human source and its scope, or the specifically bounded Auto grant. A generic
go-ahead to a decision brief covers its disclosed material choices, not a buried
commitment in a linked draft. Explicit approval of an exact full revision retains
that revision's stated scope. One answered choice leaves independent choices open.
An edited Spec or favorable Review cannot approve itself. When the human corrects
an authority claim, repair the existing source note and dependent records with
the actual sequence of question, correction, and later answer before relying on
them again.

## Small managed record

Record [Launch choices](workflows.md) in the existing index/log: Workflow, Depth,
Control, boundary, sequence, team, workspace, and pending/satisfied gates. Preserve
the user's acceptance or explicit Auto source and any subsequent changes. Log
ordinary Auto progression as exercised delegated authority over the named revision,
not a human artifact approval; do not fabricate protected decision records. Resume
reuses current choices and actual agent IDs without another Launch ceremony.

Use `.forge/loops/<loop-id>/` for a managed delivery loop:

- `index.md` from [the index template](../assets/index.md): dated current
  snapshot, accepted sources, outcomes, ownership,
  candidate, evidence gaps, and one next action;
- `decisions.md` from [the decision-log template](../assets/decisions.md):
  protected human decisions with source, actual quote, scope, date,
  authorization, status, and supersession;
- `log.md` from [the loop-log template](../assets/log.md): concise lifecycle
  events and handoffs;
- `spec/`: only earned intent, design, technical, work, Issue, Plan, and change
  records. Do not add Spec files, flags, or config the request did not earn.
  A gate briefing is chat only; do not save it here.
- `build/log.md` from [the Build-log template](../assets/build-log.md):
  candidate, Build evidence, independent Review rounds, findings,
  dispositions, repairs, and rethink record;
- `verify/`: actual [acceptance](../assets/acceptance.md) and
  [visual](../assets/visual.md) proof;
- `ship.md` from [the Ship template](../assets/ship.md): authorized publication
  and concise complete-candidate closure.

`forge init` marks these container/index/log records active so they can carry
current state. That status says only that the record is in use; it does not accept
Spec meaning, prove a candidate, or authorize a phase. Fill the initialized
outcome, authority pointers, candidate, gaps, and next action immediately. Authored
Spec, Issue, Plan, change, and evidence documents remain draft until the relevant
human or phase boundary accepts them. Under Auto, distinguish delegated acceptance
from explicit human approval and retain the grant; protected memory still follows
its exact authorization mechanics.

File presence does not create work. Leave unused decision and Build records empty;
their detailed templates apply when those operations are actually requested.
Reference an existing approved ticket as authority rather than re-recording its
approval as a new decision. Only a new human decision warrants a decision entry.
Logs and pointers describe successful observed operations; a failed command must
not be followed by an unconditional success claim.

For Quick Build, keep brief Plan notes and current state in the existing Issue,
index, or Build log. Do not create separate Issue, technical-contract, Plan,
decision, or Acceptance records unless one is independently needed for authority,
handoff, or distinct evidence. Record each fact once and link to it elsewhere;
do not repeat candidate identity, authority, checks, findings, or exclusions
across lifecycle files.

Create documents from the assets linked by the phase references. Managed Markdown
keeps immutable `id`, readable `code`, title/type/status metadata, and ordinary
human-readable bodies. Use the CLI to create or validate records; edit bodies with
the host's normal file tools. Never use a generic update to fabricate or overwrite
a human decision.

## Handoff

Give each accountable owner or helper the smallest complete packet:

```text
OUTCOME: bounded result and stopping boundary
WORKFLOW: selected workflow, depth, control, assignment, and applicable staffing triggers
AUTHORITY: accepted sources, decisions, scenarios, and project rules
CANDIDATE: exact candidate/base or not applicable
SEAMS: affected behavior, shared ownership, and integration obligations
IMPACT: signals -> affected obligations -> selected checks -> gaps, when existing
behavior can be affected
SOURCES: verified repository or external anchors
WRITES: owned paths or read-only
PROOF: runnable setup, checks, and expected observations
GAPS: unavailable evidence and unresolved facts
RETURN: changed behavior/artifact, candidate, evidence, integration concerns, gaps
```

When a defect outside the owned writes prevents assigned proof, return
`BLOCKED_BY_SCOPE` naming the defect, the authority it blocks, the minimal
repair, and why no in-scope route exists. An owner may instead make that repair
itself when it is required to produce assigned proof, is reversible, changes no
accepted meaning, and is reported in the return. Every other write outside the
owned paths is a violation.

This reconciles two rules that otherwise contradict each other: never claim a
check that was not run, and never write outside the grant. An Engineer whose
assigned proof needs a broken test script it does not own, and a Designer whose
template asks for a companion record its assignment did not grant, both use this
route rather than choosing silently between the two rules.

Passing local checks do not imply integrated Review or Acceptance. On resume,
read the index, independently retained accepted baseline and approved change,
their human source, applicable Spec-apply receipt, current canonical files, latest
actual candidate and Build verdict, Acceptance evidence, and focused decision
links. Treat matching receipt bytes as already applied and diverged bytes as a
gap; never replay writes or promote the mutable working copy into accepted
authority. Load older log entries only for a named unresolved fact. Repair stale
projections from authoritative sources.

# Reporting and failure routes

Lead with the achieved result and requested boundary. Name the exact candidate or
artifact, accepted sources, actual evidence, material gaps, and next required
action. Link direct records instead of reproducing long histories or agent chatter.

Use these dispositions:

- `PASS`: the exact artifact or candidate satisfies this phase's contract.
- `REVISE`: a bounded correction inside accepted intent is required.
- `FAIL`: actual acceptance demonstrated a required behavior or constraint fails.
- `RETHINK`: the mechanism or causal explanation must change before more edits.
- `READY_FOR_USER`: a human decision, semantic authority, or ungranted external
  action is required.
- `BLOCKED`: access, environment, dependency, or required evidence prevents an
  honest result.
- `INCONCLUSIVE`: the current acceptance seat cannot judge and a replacement or
  different capability may still resolve the gap.
- `STOPPED`: the user stopped the work.

Review PASS means no admitted blocking finding at the inspected candidate.
Acceptance PASS means the actual Review-passed outcome met applicable acceptance evidence.
Neither means Ship occurred. A structural document check establishes structure,
not semantic correctness or runtime behavior.

For work in progress, report `Done`, `Evidence`, `Gaps`, and `Next`. Omit
empty sections, unchanged status, prompt transcripts, token counts, raw agent
rosters, and speculative follow-on work.

At a human gate, follow the [gate briefing](workflows.md#gate-briefing). That
guidance is chat reporting only. Do not treat a path, heading list, or loop ID
as the briefing, and do not save it as a loop record. At completion, use the same
clarity for actual changes, material exceptions, preserved behavior, proof, gaps,
and the next action. The examples below are shapes to adapt, not required text,
headings, word counts, or tables.

## Chat briefs

**Decision brief example:** “The proposal lets a member reopen a completed task
from its row. **Added:** Reopen returns the task to the active list. **Preserved:**
completion history and permissions. The draft also proposes deleting history
after 30 days; that is a separate retention change. I recommend keeping history
because no accepted source authorizes deletion. The interaction has a prototype;
browser and assistive proof remain open. Choose (1) approve Reopen, which adds
the action, and (2) retain history or authorize a specific retention rule.
The exact Product revision and prototype show the detail.” If the user answers
only (1), (2) stays open. Link the actual revision and prototype in a real brief.

For consequential wording or behavior changes, an optional compact comparison can
show `Item | Current | Proposed | What changes`. Use the last column to say why
the correction or removal matters, not merely repeat the new text. Keep every
material choice and its recommendation in the surrounding chat; the table is a
reading aid, not another artifact or a required format.

**Change brief example:** “Reopen now works from the task row. **Changed:** the
action and active-list update. **Exception:** retention did not change; the
separate choice remains open. **Preserved:** history and permissions. The focused
checks passed on the exact candidate; browser acceptance was not run, so complete
Acceptance is still open. The Review record has the verdict. Next: decide
retention or request acceptance.” Use actual observed evidence and exact links
to the candidate and Review; do not imply a proof level that was not run.

## Explain

`Forge explain <artifact or change>` is a direct read-only operation. Retrieve
the named artifact, its exact revision, applicable accepted sources and decisions,
and available candidate or proof records. Explain the current proposal or actual
result in chat using the brief shape above: material changes and preserved meaning,
accepted versus open choices, evidence and limits, and exact source links. Name a
source gap when one remains. Do not initialize a loop, ask for Launch approval,
edit records, or turn an inference into a decision. Stop after the explanation.

# Explore

Explore investigates an idea, existing system, prior art, defect signal, or
decision before or during another phase. It is directly callable and does not
require a managed loop, mandatory artifact, proposed change, Build, or Ship.

Use the professional perspective that owns the question. A Researcher leads source
and market evidence; an Engineer traces code or runtime behavior; a Product Manager
investigates user/problem framing; a Designer studies experience patterns; an
Architect examines durable system constraints. Delegate independent questions when
parallel evidence helps.

State the question, decision it may inform, accepted context, search boundary,
evidence standard, and stop condition. Retrieve repository facts and current
primary sources before asking the user. Separate observation, sourced fact,
inference, uncertainty, and recommendation. Cite sources directly and expose gaps.

An Explore result may recommend Spec work, a prototype, or no action. A prototype
is evidence for a decision or an explicitly scoped deliverable; it is not authority
for production implementation. Record consequential conclusions only within the
user-authorized document scope. Stop when the requested question is answered.

# Independent Review

Review is independently callable and normally composed inside Build. One separate
Reviewer stays read-only, pins the exact candidate/base, covers applicable
dimensions with required Judge assignments, and owns one integrated verdict. The Reviewer
never edits, delegates repairs, creates requirements, or turns findings into Plan
Issues. Direct Review stops at its report.

## Bind and select

Establish the review purpose and applicable current obligations using the shared
[Reviewer guidance](../../../agents/reviewer/instructions.md). Carry that purpose
to judges with the authority packet: a deferred delta is not automatically a
completion claim, and claimed completion must cover the approved outcome.

Start from the independently retained accepted baseline plus approved delta, their
authority sources, current canonical result, decisions, Plan or bounded assignment,
applicable repository harness, exact candidate/base including dirty state, verified
source anchors, runnable proof, and known gaps. Inspect the actual candidate before
trusting author conclusions, document-only receipts, or earlier PASS labels.
Check the exact source and scope of each material addition, removal, or stronger
guarantee. A question, edited Spec, green check, or earlier Review is not approval.
If an accepted scenario disappeared because its code path appears dead, retain it
as unresolved until a scoped human decision or valid grant covers the removal.
Re-resolve the harness when a trace enters another subtree or standards domain.

Use [Review judges](judges.md) to select Code Review, Design, Quality, Spec, and Craft
and resolve each bundled, replacement, or disabled assignment. Record every
dimension's applicability and selected source. Spec and Craft apply to every
candidate; other dimensions follow the actual outcome. Small work narrows scope
and report size, not required applicable coverage. Standards and proof belong to
each dimension, not additional judges.

## Inspect, delegate, and preserve reports

Choose staffing using [concrete workflow triggers](workflows.md#concrete-staffing).
The Reviewer inspects undelegated dimensions directly with their selected rubrics.
For each delegated dimension, use a clean-context read-only native subagent,
blind to peer conclusions. Give it the [Judge contract](../../../agents/judge/instructions.md),
selected skill or rubric, exact candidate/base and paths, accepted authority,
verified anchors, allowed commands/tools, supplied proof, gaps, and stopping boundary.
Code Review uses the bundled sibling leaf skill by default and never starts a panel.
Run independent Review Judge assignments in parallel where resources permit;
serialize shared browser use with explicit ownership. This is Review inspection,
not Spec authoring. If nested spawning is unavailable, the host
coordinator dispatches the Reviewer's required assignments. Required delegation,
independence, access, or proof gaps prevent judgment;
never label the Builder's self-review an independent return.

Each judge returns a dimension verdict and its own report: dimension, selected
skill/source, candidate/base and path scope, inspected authority, checks and
observations, findings, and gaps. Use the dimension section in
[the review template](../assets/review.md), or the leaf's report template. The
record-owning coordinator persists each return as a distinct labelled section or
linked managed document through existing CLI mechanics; judges never write records.
Preserve delegated originals beside the Reviewer's disposition. Reviewer-owned
dimensions can use concise evidence-backed table entries or sections in the same
report, sharing the boundary and checks. Identify their owner honestly; do not
invent separate judge reports or duplicate the packet for each dimension.

## Integrate and challenge

Actively try to falsify candidate claims, then apply the conservative admission bar
in the judge guidance to every allegation, including replacement-skill returns.
Check authority, candidate binding, real reachability, evidence or causal trace,
material consequence, and severity. No quota, manufactured nits, personal taste,
speculative scale, unrelated debt, or unsupported redesign. Explicit material
standards remain binding. Required proof gaps stay visible and are not invented
defects or inferred success.

Merge duplicates, route concerns to their owning dimension, and disposition
conflicts from evidence rather than votes. Preserve sufficient evidence for every
applicable dimension; a passing dimension cannot conceal a failed one. Check the
managed-artifact contract for accompanying software records without adding Quality.

Use [Craft](judges.md#craft-rubric) to challenge both needless machinery and
missing guards at real present boundaries. A finding is evidence to assess, not
an order to add another layer. Judge whether the existing owner can meet the
accepted result and why a proposed new mechanism is necessary. After a narrowed
scope, reject Review work that serves only the superseded design.

Challenge the Builder's preservation scope using [knowledge guidance](knowledge.md).
Check signals against real consumers and semantics, name affected and preserved
obligations, and require selected checks plus explicit gaps. Expand beyond paths
for exported contracts or actual behavior; do not demand full-product replay for
a narrow patch. Review actual canonical Spec/KB bytes beside code and tests.
Intended target and observed implementation stay distinct; KB retrieval, receipt
matching, and structural validation cannot prove compliance.

## Verdict and boundary

- **P0:** demonstrated accepted-Spec/decision violation or critical trust,
  correctness, security, privacy, data-loss, public-contract, or build-boundary failure.
- **Pragmatic P1:** a current reachable trigger, material consequence, and
  scope-aligned correction are supported; deficient required proof is an explicit gap.
- **P2:** useful nonblocking advice. Omit manufactured nits and preference.

Return `PASS`, `REVISE`, `RETHINK`, `READY_FOR_USER`, or `BLOCKED`.
PASS requires no unresolved P0/pragmatic P1 and sufficient current evidence for
all required Review claims. Missing required evidence or independence blocks PASS.
`REVISE` means supported correction is needed; `RETHINK` means the mechanism needs
reconsideration; `READY_FOR_USER` identifies a consequential intent/authority
choice; `BLOCKED` means required access, evidence, or capability prevents judgment.
Disabled coverage and an explicit scoped human waiver follow the judge guidance;
label exclusions, never imply they passed. Review PASS does not establish Acceptance.

State the authority status of the intent you judged against. When it carries no
recorded human approval, say so in the boundary and scope the verdict to fidelity
to that draft. Unapproved intent is reported, not escalated: it is not a finding
on its own, and it is not `READY_FOR_USER` when the loop record already shows the
Coordinator routed that gate under a standing grant. Reserve `READY_FOR_USER` for
an intent or authority choice nobody has made yet.

On a changed repair candidate, review the complete accepted packet again and
inspect prior dispositions without narrowing to a patch list. Reuse unaffected
proof only with a candidate-bound reason. Record preservation scope, individual
reports, disagreements, and reused or missing evidence in the integrated handoff.

# Runtime and delegation

Forge runs inside one hosting coding agent and uses that host's native subagents.
Forge describes the outcome, professional perspective, clean-context independence,
write ownership, and evidence; the host owns spawning, scheduling, tools, and
permissions. Forge has no provider adapter or subprocess agent fallback. If the
host cannot provide required independent context or evidence, report the gap.

## Accountabilities

- **Coordinator:** owns Launch, requested boundary, authority, current state, and
  phase composition using [workflows](workflows.md).
- **Professional owner:** Product Manager, Designer, Engineer, Architect,
  Researcher, Reviewer, or QA perspective accountable for a phase result.
- **Engineer:** owns tactical planning, implementation, required Worker
  delegation, integration, simplification, internal review, and repairs.
- **Reviewer:** owns the read-only integrated candidate verdict in a separate context.
- **Acceptance owner:** a clean-context QA professional exercises the actual outcome.
- **Explorer / Worker / Judge:** temporary helpers. They investigate, produce a
  bounded outcome, or inspect one dimension; a Judge owns its dimension report and
  verdict, never integration or the final Review/Acceptance verdict.

Use the [concrete workflow assignments](workflows.md#concrete-staffing). These are
native subagent jobs, not multiple personas adopted by the Coordinator. A Quick
ready Issue without additional triggers uses Engineer and Reviewer. Spec
specialists follow [specialist sequence](workflows.md#specialist-sequence). Do
not spawn Product Manager, Designer, and Architect together. Parallelize other
work when it is read-only or writes do not overlap; one accountable owner
integrates all returns. Keep useful subagents across repair follow-ups while their context
stays focused. Judge Review independence by separate relevant context, read-only
ownership, pinned authority and candidate, and checked evidence. A different
provider, model family, or lineage is not required. Never claim clean context,
browser access, or independence the host did not provide.

## Model selection

Honor explicit user and host preferences, then inspect only models and capabilities
the current host actually exposes. The host's current model is a sensible default.
Choose proportionately: a fast economical model can extract a bounded fact, update
a local mechanical seam, or run a focused check; stronger reasoning fits ambiguous
architecture, cross-boundary integration, or a difficult Review. A small patch may
use the current model throughout. An API and database contract change may assign
stronger reasoning to the Builder and relevant Review lenses. A focused regression
review may use a faster model when the authority, candidate, and reproduction are
already crisp. Deterministic claims still come from tools and executed checks.

An independent Reviewer may use the same model family as the Builder when the
context and capability meet the Review contract. Do not invent model equivalence
or availability, hard-code a provider default, or use maximum effort for every
task. Model selection remains natural-language guidance. Model configuration is
deferred.

For Review, use the [five named dimensions and staffing](judges.md).
The Reviewer covers dimensions directly or dispatches required Judges
with clean, read-only contexts and the exact authority/candidate packet. Preserve
delegated reports, record Reviewer-owned assessments, and resolve conflicts from
evidence rather than votes. Staffing changes do not waive applicable coverage,
required independence from Build, or Acceptance.

# Ship

Ship closes the authorized local outcome and performs only publication actions
the user actually authorized. It starts from the exact Review-passed and
Acceptance-passed candidate, comparison base, retained accepted baseline and
approved change, current canonical files, applicable Spec-apply receipts, and
explicit external-action authority.

Before closure, check once that:

- candidate/base still match Review and Acceptance;
- required scenarios, NFRs, preserved obligations, and visual acceptance passed
  or have explicit blocking gaps;
- selected authority, runtime inputs, canonical files, and applicable receipt
  hashes still match the reviewed candidate; and
- each requested PR, merge, deployment, release, document publication, or other
  external action is explicitly authorized.

Reconcile the exact candidate, human grant, Spec status, Build changes, Review and
Acceptance results, and affected target prerequisites. A missing accepted clause
or an unrun required check remains a gap, even if focused tests passed. If code
depends on a new schema step, confirm that separately authorized operation has
completed on the target before the dependent code serves; otherwise hold
activation and report the missing prerequisite or authority. A release grant alone
does not authorize an additive or destructive schema mutation. Follow the target
repository's exact operation-and-target authorization rule and inspect destructive
SQL where that rule requires it. Correct contradictions in existing records rather
than creating a parallel release ledger.

Run [Finish](finish.md) before publication when approved unapplied Spec/knowledge
meaning or authorized existing-PR readiness remains. It reuses existing guarded
operations and observed Git/PR state; it does not replace Build Review or
Acceptance. Structural checks, receipt matching, or a clean tree do not replace
either judgment.

An exact inspected canonical-only delta produced by Finish's Spec apply does not
by itself stale the implementation Review or Acceptance candidate. Record and
inspect that the delta is limited to the reviewed canonical result. Any code,
runtime, test, configuration, uninspected canonical file, or additional meaning
change returns to the affected Review or Acceptance boundary before closure.

Record one concise [ship.md](../assets/ship.md) closure with the accepted candidate,
current candidate, comparison base, Review and Acceptance references, applicable
Spec-apply receipts, publication actions, and limits. Normally accepted and final
candidate are identical. Publication facts belong in this closure; a deployment
timestamp does not require a canonical status edit or another review loop.

If an authorized merge or rebase changes only Git identity, retain the historical
verdicts under their original candidate, record the exact old-to-new relationship,
and judge which proof remains applicable. Never relabel an old verdict. If source,
runtime input, authority, canonical meaning, or accepted behavior changed, route
the affected work to its owning Build, Review, or Acceptance boundary before
closure.

For an existing operation ID, inspect its retained receipt and current result
hashes. Matching bytes are already applied; do not replay writes or invent another
operation ID. Diverged bytes, malformed provenance, a missing Review/Acceptance
reference, or a changed authority/runtime input stop the affected claim and name
the owner who must resolve it.

Execute only authorized repository or publication mechanics. A PR request does
not imply merge or deploy; a merge request does not imply production release.
Use `READY_FOR_USER` for an ungranted external action or unresolved human-owned
meaning. Mechanical freshness success does not prove semantic fidelity,
Acceptance, deployment, or publication.

# Simplify is Build work

Simplification belongs inside [Build](build.md), before independent Review, and is
also directly callable as a bounded behavior-preserving Build operation. It is not
a lifecycle phase. Prefer deletion, reuse, direct code, fewer concepts, and a
justified no-op when the candidate is already focused. Any semantic change returns
to accepted intent rather than entering through cleanup.

# Spec

Spec defines accepted intent and can stop with a useful draft. It owns discovery,
context retrieval, informed questions, and the proposed change to standing meaning.
It does not authorize Build or Ship.

Start with accepted [Launch choices and workflow assignments](workflows.md).
PM prepares a missing/unready Issue at either depth; Engineer assesses after
that draft exists. Designer and Architect join under the shared triggers in
that order, each waiting on the upstream artifact.

## Choose the smallest useful artifact

- **Project:** Product Manager authors a concise PRD from
  [product.md](../assets/product.md). Add [design.md](../assets/design.md) when
  experience decisions matter and [tech.md](../assets/tech.md) when durable
  contracts, data, trust boundaries, migration, failure behavior, or material NFRs
  need early alignment.
- **Issue:** reuse a ready Issue or have PM create/complete
  [issue.md](../assets/issue.md), including effort/complexity, uncertainty, depth,
  specialist assignments, and proof after Engineer assessment. Do not duplicate it into
  a project Spec or infer low complexity from its workflow name.
- **Bug:** Engineer records expected/actual behavior, impact, available
  reproduction, and applicable scenarios in [bug.md](../assets/bug.md). Do not
  guess the cause.
- **Design:** Designer defines flows, states, responsive and accessibility intent,
  and an identified mock or visual board using [design.md](../assets/design.md) and
  [visual.md](../assets/visual.md). For a visual change or look-and-decide request,
  follow [codebase-anchored design studies](design-studies.md) to produce a
  browsable single-page study with project-native frames and rendered evidence.
  Reuse an adequate accepted visual; do not create a board for every small patch.
- **Work:** the relevant professional defines the deliverable, audience, goals,
  constraints, source standard, and proof in [work.md](../assets/work.md).

Use [spec-change.md](../assets/spec-change.md) when proposed behavior changes
standing requirements. Name additions, modifications, removals, preserved
commitments, affected knowledge, source authority, and full Given/When/Then
scenarios. Do not express a removal by omission or copy standing Spec into a
second corpus.

Use [knowledge guidance](knowledge.md) to carry only earned domain, data, runtime,
process, operations, or design intent into proposed OKF concepts. State the
preservation signals, affected obligations, selected checks, and gaps when the
change can affect existing behavior.

## Authoring

Retrieve relevant standing Spec, decisions, domain concepts, processes,
interfaces, repository facts, and existing solutions. Missing coverage is a
visible gap rather than a reason to block incremental adoption. Ask only
consequential human choices that cannot be retrieved, and include a recommendation.
Treat a question, possibility, analogy, or agent recommendation as open, not as
authority for a stronger guarantee. Trace each proposed addition or removal to an
exact accepted source or bounded Auto grant; otherwise label it proposed and keep
the accepted baseline. A later answer does not retroactively turn an earlier
question into approval. Correct mistaken source and dependent records in order.
Do not force a fixed interview, exhaustive catalog, or empty
sections. Do not add Spec files, feature flags, configuration, extra scenarios,
or compatibility promises the human did not ask for. Delete unused template
sections. Do not bury extra product or technical decisions inside a Spec to
make it look complete.

For a substantial Product, Design, Technical, or Work artifact, open with a short
Summary, Context, and self-contained End State before earned detail. State the
proposal, why it matters, and the observable or operational result and boundaries.
Omit empty sections. A ready Quick Issue stays brief. First look for the existing
owner or pattern that can deliver the outcome; new machinery must earn its cost
under [Craft](judges.md#craft-rubric), including a first real safety boundary.

Use `forge kb ask` to retrieve authority and existing vocabulary. Keep human
decisions, accepted requirements, observations, and proposals distinct. A loop
Spec records intent for the KB; it does not make that intent canonical or prove
that the implementation satisfies it.

Product intent uses PM judgment without an extra Product gate. In Guided, present
new/materially revised meaning and obtain human approval before boundary review.
In Auto, record the explicit grant and exercised delegated authority before the
same review; do not label unseen text human-approved. Reuse accepted requests or
artifacts when they cover current meaning. Boundary review checks fidelity,
clarity, consistency, demonstrability, cost, and downstream usability; it cannot
replace a human decision or authorize protected standing-Spec writes.

After the applicable authority gate, a native Worker may prepare bounded outputs.
A separate fast checker performs that same boundary fidelity check against the
retained accepted baseline, approved change, scenarios, decisions, and source.
Do not add a second lifecycle review or provider/model default. If the checker is
unavailable or meaning is ambiguous, report the gap to the responsible owner;
return newly consequential meaning to the human.

Record proposed standing-Spec and knowledge meaning independently when the work
earns either. Both are optional. The active repository owns its canonical memory,
and a user-facing deliverable is not automatically knowledge. Spec records and
approves the loop change; it does not routinely edit canonical Specs or knowledge.
The explicit natural operation `Forge spec apply <change>` remains available with
separate request or authority. Routine [Finish](finish.md) may invoke it at actual
work completion, normally Build-or-later or after a general-work deliverable;
direct Spec and Plan remain proposal-only.

For behavior, assign stable scenario IDs and write explicit Given/When/Then:

```text
Scenario: SCN-…
Given <accepted starting state>
When <observable actor action or event>
Then <observable outcome>
```

Keep prototypes and mocks identified as decision evidence until the human accepts
their meaning. Record accepted visual revision, states, and representative
viewports so later Review and Acceptance can compare the actual result.

## Completion

Return the artifact paths, accepted and open decisions, proposed Spec or knowledge
meaning when present, active repository, preservation chain, boundary-check status,
and next requested boundary. A direct Spec call stops here, including under Auto.
In Guided
delivery, brief the new/materially revised Spec in the conversation, link the
exact draft, and stop before Plan; record human approval of that revision
before boundary review. Auto follows its grant through
ordinary gates and retains the same review. Follow [workflow authority rules](workflows.md)
for consequential revisions, depth changes, and protected-Spec application.

# Acceptance

Acceptance exercises the actual outcome after independent Review. Use a
clean-context QA professional for software or the relevant acceptance specialist
for general work when there is a distinct outcome to exercise. Acceptance stays
read-only on the candidate and does not prescribe implementation.
The natural requests `Forge acceptance` and `Forge verify` enter this same phase;
the `verify.md` filename and `verify/` evidence path remain stable compatibility
names.

Pin the Review-passed candidate/base and load accepted scenarios, NFRs, design
revision, relevant decisions, environment/fixtures, runnable setup, and known
gaps. If current independent Review is missing, changed, or unbound, first obtain a
bounded Review of the same candidate. That Review does not itself prove acceptance.
For a directly applied Spec, also retain the accepted baseline and approved delta as
independent inputs; the current canonical file and matching receipt do not prove
authority or implementation.

Load the reviewed preservation scope. Exercise changed or new outcomes, affected
unchanged outcomes, and material failure paths named by the obligations. Reuse
unaffected proof only with a reason tied to the scope. A changed path list alone
does not establish preservation, and every patch does not require full-product
reverification.

When a candidate changes only instructions or documentation and has no runtime,
UI, or external outcome that Acceptance can exercise beyond exact-candidate Review
and deterministic checks, reuse that evidence by reference. Do not dispatch a
separate acceptance agent or create a standalone Acceptance record. State any
unrun live-agent or provider behavior honestly; evidence reuse does not turn it
into runtime proof.

For each applicable item, record in [acceptance.md](../assets/acceptance.md):
scenario/NFR, environment and candidate, action or command, expected result,
observed result, `PASS | FAIL | NOT RUN`, and trace/output/visual link. Written
tests, generated mocks, structural validation, source inspection, and prior labels
do not replace required current runtime proof. Required unavailable proof blocks
acceptance and stays explicit. Actively try to falsify consequential claims through
current public inputs and real failure paths, then require authority, reachability,
observed evidence, and material consequence before declaring a failure. No finding
quota, manufactured nits, personal taste, speculative scale, or unrelated debt.
Material accepted standards remain binding; missing proof stays NOT RUN rather
than an invented runtime failure.

## Complete outcome

Judge whether the integrated result realizes the accepted product or technical
end state, including confirmed design, cross-Issue behavior, preserved standing
commitments, and material regressions. Passing every listed Issue or scenario is
not sufficient when the combined experience is missing or contradictory. Reuse
current credible evidence; runtime contradictions outrank earlier green checks.
Focused passing tests cannot make an unimplemented or unrun accepted clause PASS;
mark that clause FAIL or NOT RUN and withhold complete Acceptance PASS.
This is part of Acceptance, not an additional Product gate. A project checkpoint
uses the same Review then Acceptance composition over its stated completed scope
and names unfinished outcomes without claiming full-project completion.

Acceptance exercises the obligations selected by the Builder and challenged by
Review. It may use the KB to locate authority, but KB search, OKF validation, and
history output never establish candidate compliance.

## Browser and visual acceptance

For applicable UI work, use an actual browser against the identified candidate.
Confirm URL/build identity, authentication, test data, browser ownership, states,
and representative viewports. Exercise real interactions and inspect console,
network, persistence, focus, keyboard behavior, semantics, responsive behavior,
and regressions when relevant.

Compare the rendered candidate with the accepted design/mock revision and states.
Record images or traces through [visual.md](../assets/visual.md). Judge material
fidelity, hierarchy, spacing, typography, alignment, clipping, overflow, contrast,
interaction feedback, and responsive behavior. Code inspection is not visual
acceptance; pixel precision applies only when accepted authority requires it.

Use synthetic-user journeys to exercise accepted scope from specific goals,
knowledge, permissions, and starting states. They are simulated acceptance or
exploratory tests, not real user research, and cannot invent requirements.

For a bug, rerun the original reproduction plus affected behavior. For a visual
artifact, open/render it and inspect the actual output. For other general work,
exercise or inspect the deliverable against its stated purpose and source standard.

Return `PASS`, `FAIL`, `RETHINK`, `READY_FOR_USER`, `INCONCLUSIVE`, or
`BLOCKED`. A material failure returns the complete accepted packet and evidence
to Build, followed by affected Review and Acceptance. Use the shared finite repair
count; never mark unrun evidence PASS.

# Workflows and Launch

Read this before starting or resuming Forge work. Workflow identifies the outcome;
depth follows effort, complexity, uncertainty, and risk. Control determines human
pauses. These choices are independent and do not change the requested boundary.

## Launch

Read enough of the request, supplied artifacts, current state, and target harness
to choose the workflow and identify available capabilities. Before specialist
dispatch or substantive artifact/source edits, brief the user in plain language
per [gate briefing](#gate-briefing), then show a short bullet list:

- Workflow: Project, Issue, Bug, or Work
- Depth: Quick or Full
- Control: Guided or Auto
- Agents: selected role names
- Boundary: requested final phase or deliverable and publication limits
- Sequence: phases to perform and accepted artifacts to reuse
- Gates: pending approvals, existing approvals, and decisions outside authority
- Workspace: selected repository and actual branch/worktree, when relevant

Show only the selected values, such as `Workflow: Issue`, `Depth: Full`, and
`Control: Guided`. Never append subtypes, “recommended,” or rationale to those
values. Use these names consistently: PM (Product Manager), Designer, Architect,
Engineer, Reviewer, QA, Researcher, Worker, and Judge. Independence is an assignment
requirement, not a role name: use Reviewer, not Independent Reviewer or Engineer
Reviewer. These are prose names, not code enums. Never attach first names.

After all bullets, write one short paragraph explaining the workflow, depth, and
team choices: effort/complexity evidence, unresolved uncertainty, each specialist's
responsibility, who starts next, and what the user can override. For Auto, cite
the instruction granting it. List roles before dispatch and record actual host
agent IDs afterward; show models/effort only when selected or exposed by the host.
Spawn Spec specialists in [sequence](#specialist-sequence), not together.
Future Worker counts depend on Plan. State the delegation rule at Launch, then
show actual ownership and the integrating Engineer before dispatching Workers.

**Guided is the default.** Present Launch and stop for the user to accept or edit
the workflow, depth, team, and control. Lead with the [gate briefing](#gate-briefing)
in the user's words, then the Launch list. An explicit current acceptance of an
already displayed Launch satisfies this gate. Launch approval does not approve an
unseen Spec or consequential Plan. Resume retains accepted choices without a new
ceremony. Routine follow-ups inside the accepted assignment do not relaunch.

**Auto requires an explicit instruction for this run**, such as “full auto” or
“run autonomously through Acceptance.” Show Launch, then proceed through ordinary
Launch, Spec, and Plan gates within that grant. Record exercised delegated
authority and its source, never human approval of unseen text. “Build this,”
“deliver this,” urgency, and silence alone do not select Auto. Independent
boundary checks, Review, and Acceptance still run.

**An instruction that does not clearly grant Auto is Guided.** When wording
could be read either way, resolving it toward Auto decides on the user’s behalf
whether a human ever sees the Spec, so present Launch and stop instead. A
request to observe, supervise, or watch the run asks for visibility and grants
no autonomy. Ask for the grant in one line rather than inferring it, and never
cite an ambiguous instruction as the Auto source in the loop record.

Both controls preserve accepted intent, host permissions, protected-Spec rules,
and publication restrictions. Conflicts, new scope, unresolved consequential user
choices, or actions outside the grant return to the user. Auto is not authority
to apply protected standing Spec bytes without the required exact approval. Keep
such proposals unapplied and hold dependent work when that authority is required;
never fabricate a decision or use generic writes to bypass memory mechanics.

Direct operations show only their own assignments and stopping boundary. Auto
for Spec does not schedule Build. Mode changes govern subsequent work. Disclose
material workflow, scope, team, or gate-policy changes before dependent work;
Guided waits, while Auto follows its explicit grant. Depth changes still require
the user's choice unless that choice was explicitly delegated.

## Gate briefing

This is conversation reporting, not a new artifact. Do not write a briefing
file, managed document, or Spec section for it.

Every human stop is a short briefing the user can decide from, plus links to
the exact artifacts for when they want depth. Do not assume they already read
the Spec, Issue, Plan, Review, or log. Speak in the user's product language.
Loop IDs, scenario codes, phase names, and harness jargon stay out of the
briefing or appear only in those links.

This applies at Launch, Spec, Plan, and any return for a decision, including
`READY_FOR_USER`, new scope, and Auto conflicts. Auto still briefs when it
actually pauses.

Name the proposed result, every material addition or removal, important preserved
behavior, risks and proof limits, and the exact choices with a recommendation and
consequence. A generic reply cannot approve a material commitment omitted here;
an explicit approval of the exact full revision retains its stated scope. If the
human answers one choice, leave the other choices open. Give one clear next ask
and links to the exact revision. Aim for about one page of chat; use more when the
decision requires it. Group related changes, use verified quantities when useful,
and show a representative screenshot or small comparison table only when it makes
the choice easier. Keep implementation detail in the linked artifact. See the
adaptable [decision and change briefs](reporting.md#chat-briefs).

## Depth

**Quick** uses ready intent, brief Engineer Plan notes, implementation, local
checks, Reviewer judgment, and repair. It is the Build/check/fix loop, not a waiver
of preparation or proof. Acceptance runs when requested; Ship only when authorized.
Recommend Quick when the outcome is clear, effort and complexity are low, accepted
design/contracts suffice, and decisive proof is known. One ticket, few files, or
urgency does not establish those conditions.

A bounded prompt, skill, instruction, or documentation change with no new
executable mechanism defaults to Quick. Full requires a concrete unresolved
interaction, contract, or material risk that Quick cannot cover. If Forge's
process is becoming larger than the requested change, name that concrete risk or
downshift; process artifacts are not evidence of product complexity.

**Full** performs needed Spec shaping, design/contracts, Plan, Build with Review,
and Acceptance through the requested boundary. Recommend it for substantial
effort, uncertainty, interactions, or risk. One Issue can require Full; multiple
coordinated outcomes normally do. Full does not dispatch unused specialists.

A current human request is a ready issue-like object when it states the intended
outcome, relevant boundaries, and observable completion. Do not assign PM merely
because no external ticket exists. When those elements are materially missing,
the initial choice is provisional: PM completes the Issue, then Engineer supplies
technical judgment. Designer and Architect join only under the triggers below,
in that order. Reuse adequate estimates. Do not introduce an estimator, scoring
system, or separate estimation document.

Show changed recommendations before dependent work. The user's depth selection
wins. If Quick cannot cover a demonstrated requirement, name the missing design,
contract, or proof and seek a depth/scope decision, including under Auto unless
depth changes were explicitly delegated. Never silently enlarge the team or omit
required work.

When the human materially narrows or simplifies accepted scope, reassess depth
and staffing before further delegation. A direct instruction to use the simpler
approach supersedes machinery that existed only for the broader design unless the
human explicitly preserves Full depth. Superseded artifacts and assignments do
not trigger specialists, expanded Review, or additional gates.

At every depth, understand the actual flow and accepted outcome, then choose the
first sound route: no change, existing owner or pattern, standard library, native
platform, installed dependency, then the smallest new mechanism. The target
harness may add technique, but cannot weaken accepted meaning or proof. Apply the
same simple-first judgment in Spec, Plan, Build, repair, and Review; it creates no
extra pass or form. [Craft](judges.md#craft-rubric) defines when complexity is earned.

## Workflow sequences

The Coordinator owns conversation, routing, authority, and progress. The following
assignments are actual native subagent jobs, not personas loaded into the
Coordinator. Retain continuing authors and separate contexts for judgment. All
sequences stop at the requested boundary and reuse applicable accepted artifacts.

| Workflow | Spec and Plan | Build | Acceptance |
| --- | --- | --- | --- |
| Project | Multiple outcomes need shared decisions or integration. PM owns product scope and outcome criteria first. Designer follows when experience is triggered. Architect follows with technical project scope/contracts after those upstream artifacts exist. Mixed projects still use this order, not simultaneous authoring. Engineer owns strategy, dependencies, integration, and outcome Issues with PM-authored product criteria. | Engineer assigns Workers to separable bounded outcomes, integrates, and repairs the whole candidate. Reviewer judges that candidate. | QA exercises integrated outcomes, Issue interactions, and affected existing behavior in a separate context. |
| Issue | One item at any effort/complexity. Reuse a ready Issue; otherwise PM authors/completes it, then Engineer assesses. Quick uses brief Plan notes. Full resolves required design, then contracts, then strategy, in that specialist order. Keep this on the Issue unless separate artifacts improve the handoff. | Quick uses Engineer and Reviewer. Full adds the triggered specialists in sequence and Workers only for separable outcomes, under one integrating Engineer. | QA proves the changed outcome and affected regressions, including required design and contracts. |
| Bug | Observed expected/actual mismatch. Engineer owns the bug record, reproduction, falsifiable hypotheses, and distinguishing checks. A reported cause is not established fact. Hotfix changes urgency, not responsibilities or truth. | The same Engineer reproduces, diagnoses, repairs the shared cause, and checks affected callers. Reviewer judges repair and preservation. | QA proves the original reproduction no longer fails and exercises affected behavior. Unrelated green tests are insufficient. |
| Work | A bounded non-software deliverable. Researcher authors evidence work, Designer visual work, or the applicable professional authors the artifact and its production/proof approach. | The author produces the artifact; Reviewer in a separate context checks claims, completeness, and craft with the applicable professional instructions. | A separate acceptance assignment inspects/exercises the final artifact against purpose, sources, and format. Software/browser tests apply only when needed. |

Feature, improvement, polish, technical task, and patch select Issue, never a
compound display label. A standalone mockup selects Work; a mock deciding a
product experience remains within that product's Spec.

Ship reuses the responsible owner for current-evidence checks, closure, and only
authorized publication. There is no mandatory Ship agent. Project Workers receive
outcome boundaries, shared contracts, owned writes, and proof. Run dependency-ready
disjoint work together; serialize shared writes. Worker returns add no gates. An
Issue inside a Project reuses that Project's team and acceptance strategy instead
of recursively launching a complete Project.

## Concrete staffing

Apply these triggers to the requested work, not workflow name or file count.

| Condition | Assignment |
| --- | --- |
| Issue lacks a ready Issue or issue-like object | PM authors/completes the Issue first. Engineer assesses effort after that draft exists, at either depth. |
| New or materially revised journeys, visual direction, or interaction design | Designer authors that Spec portion. Straightforward reuse of accepted design needs no new design assignment. |
| New/changed shared API/event contracts, data ownership, trust boundaries, migration strategy, or cross-system recovery | Architect resolves contracts before dependent implementation. A restorative Bug leaving contracts intact does not trigger new architecture work. |
| A Spec decision needs missing external evidence, competing approaches, or prior art | Researcher investigates named questions with sources and limits. Local tracing remains with Engineer or Architect. |
| Full implementation has separable bounded outcomes | Engineer delegates Workers, shows ownership/sequencing, and retains integration. This governs both Issue and Project. |
| Issue or Bug reveals multiple independently accepted outcomes requiring coordination | Propose Project with evidence; preserve usable work. |
| Full candidate spans multiple implementation outcomes, or a separate Designer or Architect assignment authored a design or contract document whose commitments this implementation must satisfy | Reviewer dispatches one Judge per applicable dimension and integrates original reports. |
| Issue or Bug changes authorization, tenancy, persistent-data integrity, a public contract, or cross-system recovery, without the broader Full condition above | Reviewer dispatches separate Code Review and Spec Judges and directly covers remaining applicable dimensions. |
| Neither expanded-Review condition applies | One Reviewer covers every applicable dimension directly in one compact report. |

Answer the second clause of the first row from the loop record rather than by
inference: there is a separate Designer or Architect assignment, and it authored
a document this candidate had to satisfy. One condition without the other does
not fire it. A Designer who only reused accepted design, or an Engineer who
recorded contracts inside its own Plan, is not a separate authoring assignment.
Two Reviewers reading the same record should reach the same staffing, so do not
expand coverage for defensibility when the record does not show both halves.
Superseded assignments and documents never satisfy an expanded-Review trigger. A
narrow guidance-only candidate uses one Reviewer for all applicable dimensions
unless the current candidate still contains multiple implementation outcomes or
a concrete high-risk contract seam.

When both expanded-Review triggers apply, the Full rule wins and covers every
applicable dimension, including Code Review and Spec. Dimensions remain Code
Review, Design, Quality, Spec, and Craft; see [judges](judges.md) for applicability,
rubrics, and replacement/waiver rules. Explicit user staffing choices take
precedence; any coverage waiver remains visible. If native nesting is unavailable,
the Coordinator dispatches required assignments on the owner's behalf. Missing
required agents, separate context, or proof capability is a gap that holds
dependent work, not permission for author self-Review or self-Acceptance.

## Specialist sequence

Triggered Spec specialists run in dependency order. Listing them at Launch is
not permission to spawn them together.

1. Product Manager authors product intent or the missing Issue.
2. Designer authors experience only after that product intent exists. Design is
   downstream of product.
3. Architect authors contracts only after product intent exists, and after design
   when design was triggered. Architecture is downstream of product and design.
4. Engineer assesses the Issue after the PM draft, then Plans and Builds after
   the required Spec artifacts exist.

Do not run Product Manager, Designer, and Architect in parallel. Later work
needs the earlier artifact; simultaneous authoring invents conflicting scope.

Parallelize other work when it is read-only or writes do not overlap. One
accountable owner integrates all returns.

## Spec and Plan gates

In Guided, brief a new/materially revised Spec in the conversation, link the
exact draft, and wait before dependent Plan or Build. After approval, record
source/revision and run its independent boundary review. A consequential new
Plan is briefed and approved before its boundary review and Build. A boundary
review cannot make a new human decision; consequential revisions return to the
gate. In Auto, the same jobs/checks run within the cited grant without ordinary
human pauses; record delegated progression honestly. When Auto does pause, still
brief.

Accepted artifacts satisfy their gate when identity, approval, and relevance are
recorded. Direct Build over accepted intent authorizes reversible Engineer tactics:
brief faithful Plan notes create no extra human gate or planning team. Consequential
strategy outside that authority requires the appropriate control/authority gate.

The Quick Issue sequence is Launch → reuse a ready Issue or PM prepares it then
Engineer assesses → settle new intent and changed depth → Engineer's brief Plan
and Build → Reviewer → requested QA Acceptance → authorized Ship. Full shapes
Spec in order: Product Manager, then Designer if triggered, then Architect if
triggered; then resolves consequential Plan and coordinates Build with Review
and requested Acceptance.
Plan remains a job, optionally notes on the Issue or under `spec/`. Review is inside
Build; `Forge verify` selects Acceptance. There is no extra Verify phase.

## Example: accepted small Issue

- Workflow: Issue
- Depth: Quick
- Control: Guided
- Agents: Engineer, Reviewer
- Boundary: Build
- Sequence: Spec (reuse) → Plan (brief notes) → Build (including Review)
- Gates: Launch approval; new intent or consequential strategy changes
- Workspace: the selected repository and actual worktree branch

The Issue defines the sidebar-label change and acceptance criteria. Effort and
complexity are low, accepted design suffices, and a focused check proves the change.
Engineer starts with brief notes and builds; Reviewer checks the result separately.
You can change depth, team, or control before starting. Guided waits for Launch
approval; Acceptance and Ship remain outside this request.

At that Launch stop the briefing names the sidebar-label change, what stays the
same, and the ask to start. It does not lead with loop or phase jargon.

## Example: an instruction that does not grant Auto

The user writes, “orchestrate a build of this and let me watch how it goes.”
That asks for delivery and for visibility, and it grants no autonomy, so it is
Guided and the Spec gate stands.

- Workflow: Issue
- Depth: Full
- Control: Guided
- Agents: PM, Engineer, Reviewer
- Boundary: Build
- Sequence: Spec → Plan → Build (including Review)
- Gates: Launch approval; the Spec gate before Plan
- Workspace: the selected repository and actual worktree branch

Present Launch and stop. Do not record the instruction as an Auto grant, and do
not read the request to watch as delegated authority over unseen intent. If the
user then says to carry on without stopping, that is the grant, and the loop
record keeps its exact words.