@wefter/opencode 0.1.0 → 0.2.1

package/src/workflows/product-shaping/README.md

@@ -1,7 +1,1245 @@
 # Product Shaping
 
-Planned workflow for turning an initial idea into product documentation that agents can use without guessing.
+Product Shaping is the Wefter workflow that turns raw product intent into product specifications that are explicit, auditable and ready to become implementation deliverables.
 
-Target outputs include product vision, domain model, operational flow, feature catalog, release scope, acceptance criteria, explicit decisions and open questions.
+The workflow must not jump from idea to code. It must create a layered product specification where each file has one responsibility, clear boundaries, known precedence and a defined consumer.
 
-This module is intentionally registered now so the Wefter architecture can grow without renaming workflow IDs later.
+By default, product specifications belong under `.wefter/specs/`. Projects may override these paths during installation or through workflow config, but agents must never hardcode `docs/` as the default destination.
+
+## Central Rule
+
+No agent may move from raw idea to implementation planning without passing through product-shaped specs.
+
+The product-shaping workflow ends at `DELIVERABLES.md`. Detailed task specs belong to the delivery implementation workflow.
+
+The only valid handoff from product shaping to delivery implementation is the configured `DELIVERABLES.md`. Other product specs are source documents for cross-checking, validation and context; they are not direct implementation plans.
+
+Agents must not implement or plan implementation directly from the product-shaping README, `IDEA_BRIEF.md`, `FEATURE_CATALOG.md`, `SCOPE.md`, `DOMAIN_SPEC.md` or `ACCEPTANCE_CRITERIA.md`. They must first produce or consume the configured `DELIVERABLES.md`, then cross-check that handoff against the relevant source specs.
+
+Migration note:
+
+The current executable implementation engine may still be named `work-unit-implementation` while Wefter migrates to the target `delivery-implementation` vocabulary. Conceptually, product shaping targets `DELIVERABLES.md` and delivery implementation. During migration, `work-unit-implementation` is treated as the legacy implementation engine, not the product-shaping vocabulary.
+
+## Source Of Truth And Enforcement
+
+This README is the primary doctrine for the product-shaping workflow inside the Wefter repository. It defines what each product spec file is, why it exists, what its limits are, which agents use it, and which rules must stop execution.
+
+The installed workflow must not rely on this README alone for enforcement. When Wefter is installed into a user's repository, the workflow rules must be reinforced by executable and operational artifacts:
+
+| Layer | Responsibility |
+| --- | --- |
+| Workflow README | Defines the doctrine and source-of-truth responsibilities for product-shaping files. |
+| Workflow config | Defines repository-specific paths, release id, gates and enabled behavior. |
+| Schemas | Validate config, profile and run manifest shape. |
+| Prompt templates | Instruct each agent to create, use and validate files according to this doctrine. |
+| OpenCode agents | Constrain writes to configured spec/run roots and reinforce role boundaries, execution order and stop conditions. Role-specific ownership is enforced by agent instructions, prompts, validators and tests because release ids and configured paths are dynamic. |
+| Run manifests | Record the exact run, paths, prompts, outputs and handoff artifacts. |
+| Validators and gates | Block publication or implementation handoff when required files, rules or decisions are missing. |
+| Tests | Prevent regressions in installed paths, templates, command behavior and safety rules. |
+
+The user's product specs are the source of truth for that user's product. This README is the source of truth for how Wefter must create, organize, validate and consume those specs.
+
+Hard rule:
+
+If an agent, prompt, schema, config default or CLI command contradicts this README, the implementation artifact is wrong and must be repaired unless this README is intentionally updated first.
+
+## Default Paths
+
+Wefter must be self-contained by default. Product shaping must use these repository-relative roots unless the user explicitly overrides them in config:
+
+```text
+.wefter/
+  specs/
+  workflows/
+  runs/
+```
+
+| Root | Responsibility |
+| --- | --- |
+| `.wefter/specs/` | Versioned product specifications produced and consumed by Wefter. |
+| `.wefter/workflows/` | Installed workflow process docs, configs, profiles and prompt templates. |
+| `.wefter/runs/` | Runtime artifacts generated by workflow executions. |
+
+Hard rules:
+
+1. Product specs must not be written to `docs/` by default.
+2. Runtime artifacts must not be written to `.audit/` by default for product shaping.
+3. Workflow templates and process files must not be mixed with product specs.
+4. Runtime run outputs must not be mixed with versioned product specs.
+5. Any non-default path, including `docs/` or `.audit/`, must come from explicit repository config.
+
+## OpenCode Exceptions
+
+OpenCode integration still requires a small number of files outside `.wefter/` because OpenCode discovers project commands, agents and skills from its own configuration paths:
+
+```text
+.opencode/
+  agent/
+    wefter-*.md
+  skills/
+    <workflow-name>/
+      SKILL.md
+opencode.json
+```
+
+Those files are integration adapters only.
+
+| Path | Responsibility |
+| --- | --- |
+| `opencode.json` | Registers OpenCode commands and points to installed Wefter agents/skills. |
+| `.opencode/agent/wefter-*.md` | Defines OpenCode agent roles, permissions and orchestration instructions. |
+| `.opencode/skills/<workflow-name>/SKILL.md` | Teaches OpenCode when and how to invoke the installed Wefter workflow. |
+
+Hard rules:
+
+1. OpenCode files must not contain product specs.
+2. OpenCode files must not contain run outputs.
+3. OpenCode files must not become the source of truth for product-shaping doctrine.
+4. OpenCode files may summarize workflow rules only to enforce execution behavior.
+5. If OpenCode files conflict with this README, the OpenCode files are wrong unless this README was intentionally changed first.
+6. Product intent, workflow config, generated specs and runtime artifacts must remain contained in `.wefter/` by default.
+7. If a future OpenCode version can load all required agents, skills and commands from `.wefter/`, Wefter should reduce or remove these exceptions.
+
+## Vocabulary
+
+Use this vocabulary consistently:
+
+```text
+idea -> product specs -> release -> deliverable -> task
+```
+
+| Term | Meaning |
+| --- | --- |
+| Idea | Raw product input: transcript, notes, prompt, conversation, customer context or initial concept. |
+| Product specs | Structured product documentation under `.wefter/specs/`. |
+| Release | A defined delivery scope, such as `01_mvp`. |
+| Deliverable | A small, ordered, verifiable unit of delivery inside a release. |
+| Task | The smallest executable unit generated by delivery implementation. |
+
+Vocabulary transition rules:
+
+```text
+idea becomes product specs
+product specs define releases
+releases are decomposed into deliverables
+deliverables are decomposed into tasks by delivery implementation
+```
+
+Deliverable vs task boundary:
+
+| Level | Owns | Must not contain |
+| --- | --- | --- |
+| Deliverable | Outcome, scope, out of scope, dependencies, source specs, acceptance criteria, risk areas, human gate triggers and expected verification. | File-by-file implementation steps, code edits, test-first sequence, detailed task checklist or executor instructions. |
+| Task | Concrete executable step produced by delivery implementation, with implementation requirements, approval scenarios, tests and review evidence. | Product scope changes, release redefinition or unapproved domain decisions. |
+
+A deliverable says what bounded result must be delivered and how readiness will be recognized. A task says exactly what to change, test and review to deliver part of that result.
+
+Hard rules:
+
+1. These terms are not interchangeable.
+2. A product spec is not a release commitment unless it is included in `SCOPE.md`.
+3. A release item is not a deliverable until it appears in the configured `DELIVERABLES.md`.
+4. A deliverable is not a task and must not contain task-level implementation detail.
+5. A task must not be created by product shaping; tasks are created only by delivery implementation.
+6. `Release` is the canonical Wefter term for a defined delivery scope; legacy terms such as `phase` may appear only as compatibility vocabulary and must be mapped to `release` when Wefter artifacts are generated.
+7. Legacy terms such as `work unit` or `slice` may appear only as migration or compatibility vocabulary and must be mapped to `deliverable` when Wefter artifacts are generated.
+
+## Hard Rules For Agents
+
+These rules are mandatory. If an agent cannot satisfy them, it must stop, write the blocker to the expected run artifact and ask for a human decision or documentation repair.
+
+1. Each product spec file has exactly one primary responsibility.
+2. Do not duplicate the responsibility of another file.
+3. Do not hide unresolved decisions inside narrative text.
+4. Unresolved questions must be recorded in `discovery/OPEN_QUESTIONS.md`.
+5. Closed product decisions must be recorded in `product/PRODUCT_DECISIONS.md`.
+6. `PRODUCT_VISION.md` must not contain a detailed feature catalog, roadmap, domain rules, acceptance criteria or technical decisions.
+7. `FEATURE_CATALOG.md` must not become a backlog, delivery promise or release scope.
+8. `MODULE_ROADMAP.md` must not become a calendar, sprint plan or delivery commitment.
+9. `SCOPE.md` is the source of truth for what enters and does not enter a release.
+10. `DOMAIN_SPEC.md` is the source of truth for closed release behavior and domain rules.
+11. `ACCEPTANCE_CRITERIA.md` is the source of truth for how release readiness is verified.
+12. `DELIVERABLES.md` is the handoff from product shaping to delivery implementation.
+13. `DELIVERABLES.md` must not contain detailed task specs.
+14. Task specs must be created only by delivery implementation.
+15. If two files conflict, do not choose silently. Record the conflict and stop for repair or human decision.
+16. Do not invent product, scope, domain, security or persistence decisions to unblock the flow.
+17. Every decision-relevant inference or generated requirement must cite source material, market reference, explicit assumption or recorded decision.
+18. Future scope must be marked as future or out of release scope.
+19. A release cannot be marked ready for delivery implementation while blocking open questions remain.
+20. Product shaping is complete only after adversarial review and final validation pass with no blocking findings.
+
+## Hard Rule Enforcement
+
+Every `Hard rule` or `Hard rules` block in this README is binding for agents, prompts, validators and future implementation code.
+
+Violation handling:
+
+1. If a rule is violated in a draft artifact, the agent must record the violation and repair the draft before publication.
+2. If a rule is violated in an approved/versioned spec, the agent must stop and require documentation repair before using that spec as source of truth.
+3. If a rule is violated by unresolved product ambiguity, the agent must record the issue in `discovery/OPEN_QUESTIONS.md` and require a human decision when it blocks the target release.
+4. If a rule is violated by a conflict between source files, the agent must record the conflict, cite the conflicting files and apply the precedence rules only to classify the conflict, not to silently erase it.
+5. If a rule is violated by generated prompts, agents, schemas, configs, manifests or CLI defaults, the derived artifact must be repaired or this README must be intentionally updated first.
+6. If a rule is violated during delivery implementation, execution must stop before creating or advancing tasks until the product handoff is repaired or explicitly approved by gate.
+
+Hard rules are not suggestions, style guidance or best-effort checks. They are stop conditions.
+
+## Documentation Drift Prevention
+
+Product shaping creates a chain of dependent specs. Agents must treat changes to upstream files as potential invalidation of downstream files.
+
+Dependency chain:
+
+```text
+SOURCE_MATERIALS.md
+-> IDEA_BRIEF.md
+-> PRODUCT_VISION.md
+-> FEATURE_CATALOG.md
+-> MODULE_ROADMAP.md
+-> DOMAIN_MODEL.md / OPERATIONAL_FLOW.md / PRODUCT_DECISIONS.md
+-> SCOPE.md
+-> DOMAIN_SPEC.md
+-> ACCEPTANCE_CRITERIA.md
+-> DELIVERABLES.md
+```
+
+Hard rules:
+
+1. If an upstream spec changes, agents must review affected downstream specs before declaring the workflow consistent.
+2. If a downstream spec depends on an outdated upstream statement, agents must mark the downstream spec as drifted and repair or block publication.
+3. If a product decision changes scope, behavior, priority or tradeoff, agents must update `PRODUCT_DECISIONS.md` and review `SCOPE.md`, `DOMAIN_SPEC.md`, `ACCEPTANCE_CRITERIA.md` and `DELIVERABLES.md` for impact.
+4. If an open question is resolved, agents must update `OPEN_QUESTIONS.md`, record any resulting decision in `PRODUCT_DECISIONS.md` when decision-relevant and review impacted specs.
+5. If a reference-derived capability changes status, agents must review `FEATURE_CATALOG.md`, `MODULE_ROADMAP.md` and target release scope.
+6. If a release scope changes, agents must review `DOMAIN_SPEC.md`, `ACCEPTANCE_CRITERIA.md` and `DELIVERABLES.md` before handoff.
+7. If `DOMAIN_SPEC.md` changes, agents must review `ACCEPTANCE_CRITERIA.md`, `DELIVERABLES.md` and future technical shaping inputs.
+8. If `ACCEPTANCE_CRITERIA.md` changes, agents must review `DELIVERABLES.md` before delivery implementation.
+9. If a drift cannot be repaired automatically without inventing decisions, agents must stop and require documentation repair or human decision.
+10. Documentation audit findings about drift must not be ignored during product shaping validation.
+
+## Persistent Product Spec Tree
+
+The default product spec tree is:
+
+```text
+.wefter/specs/
+  README.md
+  PRODUCT_VISION.md
+  discovery/
+    SOURCE_MATERIALS.md
+    IDEA_BRIEF.md
+    OPEN_QUESTIONS.md
+  references/
+    README.md
+    <reference>.md
+  product/
+    FEATURE_CATALOG.md
+    MODULE_ROADMAP.md
+    DOMAIN_MODEL.md
+    OPERATIONAL_FLOW.md
+    PRODUCT_DECISIONS.md
+  releases/
+    README.md
+    <release-id>/
+      README.md
+      SCOPE.md
+      DOMAIN_SPEC.md
+      ACCEPTANCE_CRITERIA.md
+      DELIVERABLES.md
+```
+
+Tree rules:
+
+1. This tree is the default product-shaping output tree only.
+2. Technical specs such as `TECHNICAL_DECISIONS.md`, `DOMAIN_GLOSSARY.md` and `DATA_CONTRACT.md` belong to technical shaping, not product shaping.
+3. Runtime artifacts belong under `.wefter/runs/`, not `.wefter/specs/`.
+4. Installed workflow docs, configs, profiles and templates belong under `.wefter/workflows/`, not `.wefter/specs/`.
+5. Projects may override this tree in config, but generated product specs must preserve the same document responsibilities.
+
+## Optional Extensions And Out-Of-Scope Docs
+
+The required tree is intentionally limited. Product shaping must not add mandatory documents unless they are necessary across most Wefter projects.
+
+Optional product spec extensions may be configured for project-specific needs, such as:
+
+```text
+personas or user research
+pricing or packaging notes
+go-to-market notes
+support or operations notes
+regulatory notes
+competitive positioning
+```
+
+Hard rules:
+
+1. Optional product docs must be explicitly configured or approved; agents must not create them ad hoc.
+2. Optional product docs must declare their relationship to the required source-of-truth files.
+3. Optional product docs must not override `SCOPE.md`, `DOMAIN_SPEC.md`, `ACCEPTANCE_CRITERIA.md` or `DELIVERABLES.md`.
+4. Technical docs belong to technical shaping unless they are brief product constraints recorded as assumptions or decisions.
+5. Delivery plans, task specs, task logs, task reviews and implementation validation belong to delivery implementation, not product shaping.
+
+## File Contracts
+
+### `.wefter/specs/README.md`
+
+Why it exists:
+
+This file is the map of documentation responsibilities. It tells agents which file owns which kind of product knowledge and prevents documentation drift.
+
+It is the first versioned product spec artifact. It may be created from a Wefter template before content-specific agents start writing product specs.
+
+Limits:
+
+It must not contain detailed product rules, feature lists, roadmap content, release scope or technical decisions. It is an index and responsibility contract.
+
+Creation order:
+
+Create first, before final product spec files.
+
+If the file is missing, agents must create it before writing any other product spec file.
+
+Usage order:
+
+Read first by every agent that works with product specs.
+
+Used by:
+
+All product-shaping agents, documentation audit, documentation repair, technical shaping and delivery planning.
+
+Minimum content:
+
+```text
+Purpose of the spec tree
+Configured spec root
+Release path convention
+Document responsibility table
+Source-of-truth and precedence summary
+Rules for open questions and product decisions
+Rules for custom paths and compatibility vocabulary
+Handoff rule to DELIVERABLES.md
+```
+
+Hard rule:
+
+If an agent does not know where information belongs, it must consult this file. If the destination is still unclear, record the issue in `discovery/OPEN_QUESTIONS.md`.
+
+Agents must not create ad hoc product spec files outside the documented tree unless the configured workflow explicitly allows custom output paths.
+
+### `.wefter/specs/discovery/SOURCE_MATERIALS.md`
+
+Why it exists:
+
+This file catalogs raw material used for shaping: transcript, notes, prompts, links, conversations, screenshots, documents and user-provided files.
+
+It is mandatory even when no external file was provided. In that case, it must record the available conversational input, user request, manually entered idea, or state explicitly that no source material was provided beyond the current prompt.
+
+Limits:
+
+It must not interpret the product, define scope, synthesize features or make product decisions. It records sources and context only.
+
+Creation order:
+
+Create immediately after `.wefter/specs/README.md`.
+
+Usage order:
+
+Use before `IDEA_BRIEF.md`.
+
+Used by:
+
+`wefter-product-intake-analyst`, `wefter-product-auditor`, `wefter-product-validator` and `wefter-product-repairer`.
+
+Minimum content:
+
+```text
+Source id
+Source type: transcript | note | prompt | conversation | link | file | screenshot | other
+Source location or path when available
+Capture date or provided date when available
+Neutral summary of the source
+Relevant quoted excerpts or precise references when available
+Known limitations, missing context or uncertainty
+Usage restrictions or privacy notes when applicable
+```
+
+Hard rule:
+
+No decision-relevant product idea or generated requirement may appear in final specs unless it is traceable to `SOURCE_MATERIALS.md`, a market reference or a recorded product decision.
+
+### `.wefter/specs/discovery/IDEA_BRIEF.md`
+
+Why it exists:
+
+This file turns raw input into an initial product understanding: problem, target users, jobs to be done, context, goal, constraints, assumptions and non-goals.
+
+Limits:
+
+It must not list detailed features, define releases, close domain behavior or decide technical stack.
+
+Creation order:
+
+Create after `SOURCE_MATERIALS.md`.
+
+Usage order:
+
+Use before market reference research and before `PRODUCT_VISION.md`.
+
+Used by:
+
+`wefter-product-reference-researcher`, `wefter-product-shaper`, `wefter-product-release-planner` and product auditors.
+
+Minimum content:
+
+```text
+Problem statement
+Target users or customer segments
+User context and current workflow
+Jobs to be done
+Desired product outcome
+Current alternatives or manual workarounds when known
+Constraints and assumptions
+Explicit non-goals
+Source material references
+Open questions created from the brief
+```
+
+Hard rule:
+
+If the brief does not clearly state problem, user and expected value, the workflow must stop before creating roadmap or release scope.
+
+### `.wefter/specs/discovery/OPEN_QUESTIONS.md`
+
+Why it exists:
+
+This file keeps uncertainty visible. It separates open questions from closed decisions.
+
+Limits:
+
+It must not become a backlog or long-form discussion log. Each question must include impact, owner when known, status and whether it blocks the target release.
+
+Creation order:
+
+Create with `IDEA_BRIEF.md` and keep updated throughout product shaping.
+
+Usage order:
+
+Check at every gate before publishing candidate artifacts.
+
+Used by:
+
+All agents, especially `wefter-product-orchestrator`, `wefter-product-validator`, `wefter-product-repairer` and the delivery planner.
+
+Minimum content:
+
+```text
+Question id
+Question
+Context and source reference
+Affected files or decisions
+Impact if unresolved
+Blocks target release: yes | no | unknown
+Known options or candidate answers
+Owner or decision maker when known
+Status: open | answered | deferred | obsolete
+Resolution and linked product decision when answered
+```
+
+Hard rule:
+
+If a question affects release scope, domain behavior, acceptance criteria or deliverables, it must be listed here. Agents must not resolve it silently.
+
+Open or deferred questions with `Blocks target release: yes` block completion. A deferred question can pass the target-release gate only when it is explicitly marked `Blocks target release: no`.
+
+### `.wefter/specs/references/README.md`
+
+Why it exists:
+
+This file maps the references researched for the product and explains why each reference matters.
+
+Limits:
+
+It must not consolidate all features, replace individual reference files or act as the feature catalog.
+
+Creation order:
+
+Create during reference research, before or immediately after individual reference files.
+
+Usage order:
+
+Use before consolidating features.
+
+Used by:
+
+`wefter-product-reference-researcher`, `wefter-product-shaper` and product auditors.
+
+Minimum content:
+
+```text
+Research purpose
+Selection criteria for references
+Reference map table
+For each reference: name, file path, category, primary focus, relevance, research date, freshness status
+Explicit exclusions or skipped reference types when relevant
+Rules for using references as inspiration, not commitments
+```
+
+Hard rule:
+
+Every individual reference file must be listed here with its `references/<reference>.md` path, focus and relevance. Zero individual references are valid only when this file explicitly states that no references were used or researched and explains why.
+
+### `.wefter/specs/references/<reference>.md`
+
+Why it exists:
+
+Each file records analysis of one competitor, product, tool, workflow, market category or relevant reference.
+
+Limits:
+
+It must not treat external claims as permanent truth. It must not convert competitor behavior into product requirements automatically.
+
+Creation order:
+
+Create during market reference research, after `IDEA_BRIEF.md`.
+
+Usage order:
+
+Use before `FEATURE_CATALOG.md`.
+
+Used by:
+
+`wefter-product-reference-researcher`, `wefter-product-shaper` and product auditors.
+
+Minimum content:
+
+```text
+Name
+Research date
+Reference URL or source
+Primary focus
+Target users
+Observed capabilities
+Notable differentiators
+Limitations or risks
+Applicable ideas
+Ideas not applicable
+Confidence and freshness notes
+```
+
+Each file must distinguish observed claims, agent inferences and product opportunities. Observed claims should cite the source where possible. Agent inferences must be marked as inferences. Product opportunities must remain candidates until they are evaluated in `FEATURE_CATALOG.md` or `PRODUCT_DECISIONS.md`.
+
+Hard rule:
+
+Every feature derived from a reference must be marked as inspiration, not commitment.
+
+### `.wefter/specs/PRODUCT_VISION.md`
+
+Why it exists:
+
+This file defines the product at the macro level: objective, direction, pillars, scope rule and positioning.
+
+Limits:
+
+It must not contain a detailed feature catalog, roadmap, release scope, domain rules, acceptance criteria or technical decisions.
+
+Creation order:
+
+Create after `IDEA_BRIEF.md` and initial references.
+
+Usage order:
+
+Use before feature catalog, roadmap, release scope and deliverable shaping.
+
+Used by:
+
+All agents. It is the macro product compass.
+
+Minimum content:
+
+```text
+Product objective
+Target users or customer segments
+Problem and value summary
+Product direction
+Product pillars
+Macro non-goals
+Scope rule explaining which details belong in other files
+Source references to idea brief, decisions or references
+```
+
+Hard rule:
+
+If a later artifact contradicts `PRODUCT_VISION.md`, the agent must record a finding and stop until the contradiction is repaired or an explicit product decision supersedes it.
+
+### `.wefter/specs/product/FEATURE_CATALOG.md`
+
+Why it exists:
+
+This file centralizes possible product capabilities from the idea, references and product decisions.
+
+Limits:
+
+It is not a backlog, not a roadmap, not release scope and not a delivery promise.
+
+Creation order:
+
+Create after `PRODUCT_VISION.md` and market references.
+
+Usage order:
+
+Use before `MODULE_ROADMAP.md` and `SCOPE.md`.
+
+Used by:
+
+`wefter-product-shaper`, `wefter-product-release-planner`, product auditors and validators.
+
+Minimum content:
+
+```text
+Catalog purpose and non-backlog rule
+Feature id
+Feature name
+Capability description
+Source: idea | reference | decision | inference
+Status: candidate | core | future | rejected | needs-decision
+Rationale
+Relevant references or source ids
+Known dependencies
+Release relevance when known
+Reason if rejected or deferred
+```
+
+Hard rule:
+
+Every feature must have exactly one status: `candidate`, `core`, `future`, `rejected` or `needs-decision`. A feature without status cannot become release scope, and a feature marked `future`, `rejected` or `needs-decision` cannot enter `SCOPE.md` without an explicit product decision.
+
+### `.wefter/specs/product/MODULE_ROADMAP.md`
+
+Why it exists:
+
+This file organizes product evolution into modules and releases by conceptual priority and dependency. Legacy phase vocabulary may be referenced only as compatibility language.
+
+Limits:
+
+It is not a calendar, sprint plan, timeline or closed delivery commitment. It must not list every feature in detail.
+
+Creation order:
+
+Create after `FEATURE_CATALOG.md`.
+
+Usage order:
+
+Use before choosing and shaping the initial release.
+
+Used by:
+
+`wefter-product-release-planner`, product auditors and deliverable shaping.
+
+Minimum content:
+
+```text
+Roadmap purpose and non-schedule rule
+Module or release sequence
+For each module/release: objective, included capability groups, dependencies, rationale, expected maturity
+Candidate initial release
+Future modules explicitly marked as future
+Known sequencing risks
+References to feature catalog items or product decisions
+```
+
+Hard rule:
+
+The roadmap defines relative sequence and conceptual dependencies only. Dates and commitments do not belong here.
+
+### `.wefter/specs/product/DOMAIN_MODEL.md`
+
+Why it exists:
+
+This file describes conceptual business entities, relationships and modeling principles.
+
+Limits:
+
+It is not a database schema, migration plan, ORM model or technical naming glossary. It does not replace `DOMAIN_SPEC.md`.
+
+Creation order:
+
+Create after vision, feature catalog and initial roadmap.
+
+Usage order:
+
+Use before `DOMAIN_SPEC.md` and later before technical data contracts.
+
+Used by:
+
+`wefter-product-domain-modeler`, `wefter-product-release-planner`, technical shaping and delivery planning.
+
+Minimum content:
+
+```text
+Modeling principles
+Core business entities
+Entity responsibilities
+Relationships and cardinality at conceptual level
+Lifecycle notes for important entities
+Business invariants
+Terms and definitions in business language
+Out-of-model or future concepts when relevant
+References to source specs and product decisions
+```
+
+Hard rule:
+
+Names here are business/conceptual names. Final technical names belong to technical shaping.
+
+### `.wefter/specs/product/OPERATIONAL_FLOW.md`
+
+Why it exists:
+
+This file describes the target operational flow end to end, including actors, states, inputs, outputs and major steps.
+
+Limits:
+
+It may describe future flow, but future steps must be explicitly marked. It does not close release scope by itself.
+
+Creation order:
+
+Create after or in parallel with `DOMAIN_MODEL.md`.
+
+Usage order:
+
+Use before `SCOPE.md`, `DOMAIN_SPEC.md` and `ACCEPTANCE_CRITERIA.md`.
+
+Used by:
+
+`wefter-product-domain-modeler`, `wefter-product-release-planner`, acceptance shaping and auditors.
+
+Minimum content:
+
+```text
+Flow purpose and target scenario
+Actors and responsibilities
+Trigger events
+Preconditions
+Main operational steps
+State/status transitions when conceptually relevant
+Alternate flows and exceptions
+Inputs and outputs per major step
+Future or out-of-release steps explicitly marked
+References to domain model, scope candidates or product decisions
+```
+
+Hard rule:
+
+Any operational step outside the target release must be marked as future or out of release scope.
+
+### `.wefter/specs/product/PRODUCT_DECISIONS.md`
+
+Why it exists:
+
+This file records closed product decisions, assumptions, risks and impacts so knowledge does not remain only in chats or temporary run artifacts.
+
+Limits:
+
+It is not a changelog, backlog or full scope document. It should not repeat complete specs.
+
+Creation order:
+
+Create during product shaping and update whenever decisions are made. It may be created before its nominal position if decisions appear early.
+
+Usage order:
+
+Read before validation, repair, release planning and deliverable shaping.
+
+Used by:
+
+All agents.
+
+Minimum content:
+
+```text
+Decision id
+Status: accepted | superseded | rejected
+Date or decision timestamp when known
+Context and source references
+Decision statement
+Alternatives considered
+Rationale
+Impact on scope, domain, acceptance, roadmap or deliverables
+Affected files
+Follow-up actions
+Supersedes or superseded by when applicable
+```
+
+Hard rule:
+
+Every accepted decision that changes scope, behavior, priority, tradeoff or product direction must be recorded here. Proposed but unresolved decisions belong in `OPEN_QUESTIONS.md` until accepted or rejected.
+
+### `.wefter/specs/releases/README.md`
+
+Why it exists:
+
+This file explains release organization and the relationship between release-level files.
+
+Limits:
+
+It must not define detailed scope or behavior for one release.
+
+Creation order:
+
+Create before the first release folder.
+
+Usage order:
+
+Read before files under `releases/<release-id>/`.
+
+Used by:
+
+`wefter-product-release-planner`, validators and delivery orchestrators.
+
+Minimum content:
+
+```text
+Release organization purpose
+Release id convention
+Release directory/path convention
+Release map table
+For each release: id, title, status, objective, path, relationship to roadmap
+Compatibility notes for custom paths such as docs/phases
+Rule that release-specific detail belongs inside releases/<release-id>/
+```
+
+Hard rule:
+
+If a project uses a custom release path, such as `docs/phases`, that must come from config, not from hardcoded agent assumptions.
+
+### `.wefter/specs/releases/<release-id>/README.md`
+
+Why it exists:
+
+This file indexes one release and declares precedence for that release's documents.
+
+Limits:
+
+It must not replace `SCOPE.md`, `DOMAIN_SPEC.md`, `ACCEPTANCE_CRITERIA.md` or `DELIVERABLES.md`.
+
+Creation order:
+
+Create when opening a release.
+
+Usage order:
+
+Read first inside a release folder.
+
+Used by:
+
+Release planner, validator, technical shaping and delivery planning.
+
+Minimum content:
+
+```text
+Release id and title
+Release status
+Release objective summary
+File index for SCOPE.md, DOMAIN_SPEC.md, ACCEPTANCE_CRITERIA.md and DELIVERABLES.md
+Source-of-truth responsibility table
+Precedence summary for release files
+Handoff rule to DELIVERABLES.md
+Known blockers or links to OPEN_QUESTIONS.md
+```
+
+Hard rule:
+
+It must declare which file owns release scope, domain behavior, acceptance and implementation deliverable handoff.
+
+### `.wefter/specs/releases/<release-id>/SCOPE.md`
+
+Why it exists:
+
+This file defines the release commitment: objective, expected result, included scope, excluded scope, tradeoffs and boundaries.
+
+Limits:
+
+It must not define all detailed domain rules, task specs or technical stack.
+
+Creation order:
+
+Create after roadmap, domain model and operational flow are sufficiently clear.
+
+Usage order:
+
+Use before `DOMAIN_SPEC.md`, `ACCEPTANCE_CRITERIA.md` and `DELIVERABLES.md`.
+
+Used by:
+
+Release planner, domain shaper, acceptance shaper, delivery planner and auditors.
+
+Minimum content:
+
+```text
+Release objective
+Expected outcome
+Included scope
+Explicit out of scope
+Accepted tradeoffs
+Assumptions
+Dependencies and preconditions
+Open blockers or linked open questions
+Scope boundaries by domain or capability group
+References to roadmap, feature catalog and product decisions
+```
+
+Hard rule:
+
+Nothing may enter `DOMAIN_SPEC.md`, `ACCEPTANCE_CRITERIA.md` or `DELIVERABLES.md` if it is outside `SCOPE.md`, unless the artifact records an explicit pending scope change requiring human decision.
+
+### `.wefter/specs/releases/<release-id>/DOMAIN_SPEC.md`
+
+Why it exists:
+
+This file closes release domain behavior: operational entities, rules, states, conceptual permissions, validations, invariants and meaningful alternate flows.
+
+Limits:
+
+It is not a data contract, UI spec, task plan or stack decision document.
+
+Creation order:
+
+Create after `SCOPE.md`.
+
+Usage order:
+
+Use before `ACCEPTANCE_CRITERIA.md`, technical data contracts and `DELIVERABLES.md`.
+
+Used by:
+
+Domain modeler, acceptance shaper, technical shaping, delivery planner and auditors.
+
+Minimum content:
+
+```text
+Release domain responsibility
+Closed domain decisions
+Entities and concepts in release scope
+Domain rules and invariants
+State/status model when applicable
+Allowed transitions when applicable
+Conceptual permissions and actor capabilities
+Validations and invalid states
+Alternate flows and exceptions
+Audit/history expectations when relevant
+Explicit unresolved domain questions if any
+References to SCOPE.md, DOMAIN_MODEL.md, OPERATIONAL_FLOW.md and PRODUCT_DECISIONS.md
+```
+
+Hard rule:
+
+An unresolved domain rule cannot become an implementable deliverable without a human gate.
+
+### `.wefter/specs/releases/<release-id>/ACCEPTANCE_CRITERIA.md`
+
+Why it exists:
+
+This file turns scope and domain behavior into verifiable release readiness criteria.
+
+Limits:
+
+It must not redefine scope or introduce domain rules that are not present in `DOMAIN_SPEC.md` or `PRODUCT_DECISIONS.md`.
+
+Creation order:
+
+Create after `DOMAIN_SPEC.md`.
+
+Usage order:
+
+Use before `DELIVERABLES.md` and during implementation traceability.
+
+Used by:
+
+Release planner, delivery planner, implementation planner, task reviewer and validator.
+
+Minimum content:
+
+```text
+Acceptance objective
+Definition of release accepted
+End-to-end acceptance flows
+Preconditions for each flow
+Expected outcomes for each flow
+Acceptance criteria by domain area
+Cross-cutting acceptance rules
+Negative or invalid scenarios when relevant
+Out-of-acceptance scenarios
+Traceability to SCOPE.md and DOMAIN_SPEC.md
+Definition of release ready for delivery implementation
+```
+
+Hard rule:
+
+Every criterion must be testable, observable or otherwise objectively verifiable. Vague criteria must be rewritten or recorded as open questions.
+
+### `.wefter/specs/releases/<release-id>/DELIVERABLES.md`
+
+Why it exists:
+
+This file converts the release into ordered, small, verifiable deliverables ready for delivery implementation.
+
+Limits:
+
+It must not contain task specs, code, detailed implementation plans or task-level TDD requirements. Those belong to the implementation workflow.
+
+Creation order:
+
+Create last in product shaping.
+
+Usage order:
+
+Use first by delivery implementation.
+
+Used by:
+
+Delivery orchestrator, delivery planner, plan auditors and validators.
+
+Hard rule:
+
+Every deliverable must include goal, scope, out of scope, dependencies, source docs, acceptance criteria, risk areas, human gate triggers and expected verification.
+
+Every deliverable must have a stable id in the heading `## Deliverable <id>: <title>` and exactly one status: `candidate`, `ready`, `blocked`, `deferred` or `done`. Only `ready` deliverables may enter delivery implementation without an additional human gate.
+
+Recommended deliverable format:
+
+```md
+## Deliverable 00: <title>
+
+Status: candidate | ready | blocked | deferred | done
+Type: functional | technical | foundation | validation | documentation | migration | integration | security
+
+### Goal
+
+### Scope
+
+### Out Of Scope
+
+### Dependencies
+
+### Source Docs
+
+### Acceptance Criteria
+
+### Risk Areas
+
+### Human Gate Triggers
+
+### Expected Verification
+```
+
+## Hard Creation Order
+
+Agents must create product specs in this order unless resuming an existing run with already-created artifacts:
+
+```text
+1. README.md
+2. discovery/SOURCE_MATERIALS.md
+3. discovery/IDEA_BRIEF.md
+4. discovery/OPEN_QUESTIONS.md
+5. references/<reference>.md files when used
+6. references/README.md, including an explicit no-reference statement when none are used
+7. PRODUCT_VISION.md
+8. product/FEATURE_CATALOG.md
+9. product/MODULE_ROADMAP.md
+10. product/DOMAIN_MODEL.md
+11. product/OPERATIONAL_FLOW.md
+12. product/PRODUCT_DECISIONS.md
+13. releases/README.md
+14. releases/<release-id>/README.md
+15. releases/<release-id>/SCOPE.md
+16. releases/<release-id>/DOMAIN_SPEC.md
+17. releases/<release-id>/ACCEPTANCE_CRITERIA.md
+18. releases/<release-id>/DELIVERABLES.md
+```
+
+The numbered order lists fixed required files plus the conditional reference-file step. Machine-readable `creationOrder` contracts list fixed required files only; dynamic reference files are represented by the `references/<reference>.md` collection rule and must be created before `references/README.md` when used.
+
+`OPEN_QUESTIONS.md` and `PRODUCT_DECISIONS.md` are living documents. They may be updated at any point, but they must not be skipped.
+
+## Hard Utilization Order
+
+Agents that consume product specs for validation, repair, technical shaping or delivery implementation must read files in this order unless a prompt explicitly narrows scope:
+
+```text
+1. .wefter/specs/README.md
+2. .wefter/specs/releases/<release-id>/README.md
+3. .wefter/specs/PRODUCT_VISION.md
+4. .wefter/specs/product/PRODUCT_DECISIONS.md
+5. .wefter/specs/releases/<release-id>/SCOPE.md
+6. .wefter/specs/releases/<release-id>/DOMAIN_SPEC.md
+7. .wefter/specs/releases/<release-id>/ACCEPTANCE_CRITERIA.md
+8. .wefter/specs/releases/<release-id>/DELIVERABLES.md
+9. .wefter/specs/product/DOMAIN_MODEL.md
+10. .wefter/specs/product/OPERATIONAL_FLOW.md
+11. .wefter/specs/product/FEATURE_CATALOG.md
+12. .wefter/specs/product/MODULE_ROADMAP.md
+13. .wefter/specs/discovery/OPEN_QUESTIONS.md
+14. .wefter/specs/discovery/IDEA_BRIEF.md
+15. .wefter/specs/references/
+```
+
+Creation order moves from raw input to refined release handoff. Utilization order starts from responsibility and release source-of-truth files, then moves outward to context.
+
+## Precedence Rules
+
+When files conflict, agents must apply these precedence rules to classify the conflict. They must not silently rewrite history or choose a side without recording the issue.
+
+Release-level precedence:
+
+```text
+SCOPE.md > DOMAIN_SPEC.md > ACCEPTANCE_CRITERIA.md > DELIVERABLES.md
+```
+
+Product-level precedence:
+
+```text
+PRODUCT_VISION.md > MODULE_ROADMAP.md > FEATURE_CATALOG.md
+```
+
+Decision precedence:
+
+```text
+PRODUCT_DECISIONS.md supersedes older narrative text only when the decision is explicit, dated or otherwise clearly recorded.
+```
+
+Blocking question rule:
+
+```text
+OPEN_QUESTIONS.md with open or deferred release-blocking questions blocks completion regardless of file precedence.
+```
+
+Precedence classifies which file should be repaired or superseded. It does not authorize agents to silently rewrite, ignore or delete conflicting information.
+
+Hard conflict examples:
+
+```text
+ACCEPTANCE_CRITERIA.md requires behavior outside SCOPE.md -> conflict.
+DELIVERABLES.md implements item excluded by SCOPE.md -> conflict.
+DOMAIN_SPEC.md closes a behavior still blocking in OPEN_QUESTIONS.md -> conflict.
+FEATURE_CATALOG.md marks a future feature but SCOPE.md includes it without decision -> conflict.
+```
+
+## Agent Responsibilities
+
+| Agent | Primary files |
+| --- | --- |
+| `wefter-product-orchestrator` | All product-shaping files and run artifacts. |
+| `wefter-product-intake-analyst` | `SOURCE_MATERIALS.md`, `IDEA_BRIEF.md`, `OPEN_QUESTIONS.md`. |
+| `wefter-product-reference-researcher` | `IDEA_BRIEF.md`, `references/README.md`, `references/<reference>.md`. |
+| `wefter-product-shaper` | `PRODUCT_VISION.md`, `FEATURE_CATALOG.md`, `MODULE_ROADMAP.md`. |
+| `wefter-product-domain-modeler` | `DOMAIN_MODEL.md`, `OPERATIONAL_FLOW.md`, `DOMAIN_SPEC.md`. |
+| `wefter-product-release-planner` | `SCOPE.md`, `ACCEPTANCE_CRITERIA.md`, `DELIVERABLES.md`. |
+| `wefter-product-auditor` | All files, with focus on contradiction, omission, overreach and ambiguity. |
+| `wefter-product-validator` | All files, with focus on readiness for delivery implementation. |
+| `wefter-product-repairer` | Candidate or approved artifacts only, never raw source materials. |
+| Delivery planner | `DELIVERABLES.md`, `SCOPE.md`, `DOMAIN_SPEC.md`, `ACCEPTANCE_CRITERIA.md`, `PRODUCT_DECISIONS.md`. |
+
+Agent role boundaries:
+
+| Agent | Must not do |
+| --- | --- |
+| `wefter-product-orchestrator` | Must not invent product decisions to keep the run moving. |
+| `wefter-product-intake-analyst` | Must not create roadmap, release scope, deliverables or technical decisions. |
+| `wefter-product-reference-researcher` | Must not convert competitor behavior into requirements or commitments. |
+| `wefter-product-shaper` | Must not close release scope or domain behavior without release/domain artifacts. |
+| `wefter-product-domain-modeler` | Must not create database schema, migrations, ORM models or final technical names. |
+| `wefter-product-release-planner` | Must not create task specs, code instructions or delivery plans. |
+| `wefter-product-auditor` | Must not edit product specs while auditing. |
+| `wefter-product-validator` | Must not pass validation with blocking open questions, unresolved conflicts or missing required files. |
+| `wefter-product-repairer` | Must not change raw source materials or erase conflict evidence. |
+| Delivery planner | Must not redefine product scope, domain behavior or acceptance criteria. |
+
+Hard rule:
+
+When an agent encounters work outside its role boundary, it must record the required handoff, blocker or follow-up instead of performing the work directly.
+
+## Completion Gate
+
+Product shaping is complete only when all conditions are true:
+
+1. Every required file exists at the configured spec path.
+2. Every required file respects its responsibility and limits.
+3. `OPEN_QUESTIONS.md` contains no unresolved blocker for the target release.
+4. `PRODUCT_VISION.md` is consistent with release direction.
+5. `SCOPE.md` clearly defines included and excluded release scope.
+6. `DOMAIN_SPEC.md` covers the complete release scope.
+7. `ACCEPTANCE_CRITERIA.md` verifies behavior from `DOMAIN_SPEC.md` without redefining scope.
+8. `DELIVERABLES.md` covers release acceptance criteria without becoming task specs.
+9. Adversarial review has no blocking findings.
+10. Every deliverable intended for implementation is marked `ready`.
+11. Final validation states the release is ready for delivery implementation.
+
+The completion gate has two enforcement layers.
+
+Deterministic CLI and evidence checks owned by `wefter product validate`:
+
+- Required configured files exist.
+- `OPEN_QUESTIONS.md` contains no open or deferred release-blocking question.
+- `DELIVERABLES.md` has valid ready statuses and required fields.
+- `DELIVERABLES.md` does not contain obvious task, code or task-level TDD markers.
+- Adversarial review and final validation evidence exist at the canonical paths inside the selected run and contain passing evidence. These evidence gates are mandatory for completion.
+
+Semantic checks owned by product auditor, product validator and human decisions:
+
+- Required files respect their responsibility and limits.
+- `PRODUCT_VISION.md` is consistent with release direction.
+- `SCOPE.md` clearly defines included and excluded release scope.
+- `DOMAIN_SPEC.md` covers the complete release scope.
+- `ACCEPTANCE_CRITERIA.md` verifies behavior from `DOMAIN_SPEC.md` without redefining scope.
+- `DELIVERABLES.md` covers release acceptance criteria without becoming detailed implementation planning beyond deterministic markers.
+- Applicable documentation-audit drift findings are resolved, marked not applicable or recorded as blockers/human decisions.
+
+`wefter product validate` is the deterministic gate plus verification that required prompt/human semantic evidence exists and declares pass. It must not pretend to prove semantic coverage by regex.
+
+## Doctrine Stability Criteria
+
+This README is stable enough to derive schemas, configs, prompts, agents and tests only when all conditions are true:
+
+1. Every required product spec file has a contract.
+2. Every file contract defines why the file exists, limits, creation order, usage order, consumers, minimum content and hard rules.
+3. The default tree is self-contained under `.wefter/specs/` and separates specs, workflows and runs.
+4. The vocabulary is consistent with `idea -> product specs -> release -> deliverable -> task`.
+5. Legacy vocabulary appears only as migration or compatibility language.
+6. Creation order and utilization order are explicit and non-conflicting.
+7. Precedence rules and conflict examples are explicit.
+8. Drift prevention rules cover upstream and downstream spec changes.
+9. Agent responsibilities and role boundaries are explicit.
+10. Completion gate and delivery handoff rules are explicit.
+11. No known TODO, placeholder or unresolved doctrine question remains in this README.
+12. Any remaining decision that requires human approval is recorded outside the README as a task result or open question.
+
+## Handoff To Delivery Implementation
+
+The only product-shaping handoff artifact for implementation is:
+
+```text
+.wefter/specs/releases/<release-id>/DELIVERABLES.md
+```
+
+Delivery implementation must consume one configured deliverable from `DELIVERABLES.md` and cross-check it against:
+
+```text
+.wefter/specs/releases/<release-id>/SCOPE.md
+.wefter/specs/releases/<release-id>/DOMAIN_SPEC.md
+.wefter/specs/releases/<release-id>/ACCEPTANCE_CRITERIA.md
+.wefter/specs/product/PRODUCT_DECISIONS.md
+```
+
+The implementation workflow turns one deliverable into:
+
+```text
+delivery-plan.md
+traceability-matrix.md
+verification-plan.md
+gate-assessment.md
+task-specs/
+task logs
+task reviews
+final validation
+```
+
+Agents must not create task specs during product shaping. If a product-shaping agent identifies likely tasks, it must either keep them at deliverable granularity or record them as implementation notes inside the appropriate deliverable without task-level detail.