chore(workflow): document model v6 — 2-stage discovery, PO-owned feature moves, unified session protocol

- Split docs/discovery.md into three append-only files:
  docs/discovery_journal.md (raw Q&A), docs/discovery.md (synthesis),
  docs/architecture.md (architectural decisions)
- Remove docs/features/discovery.md (superseded)
- Replace Phase 1/Phase 2 model with 2-stage model: Stage 1 Discovery
  (unified iterative sessions) + Stage 2 Specification (stories + criteria)
- PO is sole owner of all .feature file moves; SE and reviewer never move
  or edit .feature files; explicit escalation when no in-progress feature
- Add bug handling protocol: PO adds @bug @id, SE writes both @id test
  and @given Hypothesis property test
- Add real-time split rule: >2 concerns or >8 Examples splits immediately
  within the same session
- Add session status markers to discovery_journal.md: IN-PROGRESS/COMPLETE
- Update all agent files, skills, workflow docs, and research docs to match

Author: nullhack

.opencode/agents/product-owner.md

@@ -25,15 +25,16 @@ Load `skill session-workflow` first — it reads TODO.md, orients you to the cur
 
 | Step | Action |
 |---|---|
-| **Step 1 — SCOPE** | Load `skill scope` — contains the full 4-phase discovery and criteria protocol |
+| **Step 1 — SCOPE** | Load `skill scope` — contains Stage 1 (Discovery sessions) and Stage 2 (Stories + Criteria) |
 | **Step 5 — ACCEPT** | See acceptance protocol below |
 
 ## Ownership Rules
 
-- You are the **sole owner** of `.feature` files and `docs/features/discovery.md`
+- You are the **sole owner** of `.feature` files, `docs/discovery_journal.md`, and `docs/discovery.md`
 - No other agent may edit these files
+- **You are the sole owner of all `.feature` file moves**: backlog → in-progress (before Step 2) and in-progress → completed (after Step 5 acceptance). No other agent moves `.feature` files.
 - Software-engineer escalates spec gaps to you; you decide whether to extend criteria
-- **NEVER move a feature to `in-progress/` unless its discovery section has `Status: BASELINED`** — if not baselined, complete Step 1 (Phase 2 + 3 + 4) first
+- **NEVER move a feature to `in-progress/` unless its `.feature` file has `Status: BASELINED`** — if not baselined, complete Step 1 (Stage 1 Discovery + Stage 2 Specification) first
 
 ## Step 5 — Accept
 
@@ -55,8 +56,17 @@ When a gap is reported (by software-engineer or reviewer):
 | Behavior contradicts an existing Example | Write a new Example with new `@id`. |
 | Post-merge defect | Move the `.feature` file back to `in-progress/`, add new Example with `@id`, resume at Step 3. |
 
+## Bug Handling
+
+When a defect is reported against any feature:
+
+1. Add a `@bug @id:<new-8-char-hex>` Example to the relevant `Rule:` block in the `.feature` file.
+2. Write the Example using the standard `Given/When/Then` format describing the correct behavior.
+3. Update TODO.md to note the new `@id` for the SE to implement.
+4. SE implements the `@id` test in `tests/features/` **and** a `@given` Hypothesis property test in `tests/unit/`. Both are required.
+
 ## Available Skills
 
 - `session-workflow` — session start/end protocol
 - `feature-selection` — when TODO.md is idle: score and select next backlog feature using WSJF
-- `scope` — Step 1: 3-session discovery (Phase 1 + 2), stories (Phase 3), and criteria (Phase 4)
+- `scope` — Step 1: Stage 1 (Discovery sessions with stakeholder) and Stage 2 (Stories + Criteria, PO alone)

.opencode/agents/reviewer.md

@@ -42,6 +42,14 @@ Load `skill session-workflow` first. Then load `skill verify` for Step 4 verific
 - **Never suggest `noqa`, `type: ignore`, or `pytest.skip` as a fix.** These are bypasses, not solutions.
 - **Report specific locations.** "`physics/engine.py:47`: unreachable return" not "there is dead code."
 - **Every PASS/FAIL cell must have evidence.** Empty evidence = UNCHECKED = REJECTED.
+- **Never move `.feature` files.** The PO is the sole owner of all feature file moves. After producing an APPROVED report, update TODO.md and stop — the PO accepts and moves the file.
+
+## After APPROVED
+
+When your report verdict is APPROVED:
+1. Write the report as described in `skill verify`.
+2. Update TODO.md `## Next` line: `Run @product-owner — accept feature <name> at Step 5.`
+3. Stop. Do not touch `.feature` files. The PO reviews the feature themselves and moves it to `completed/`.
 
 ## Gap Reporting
 

.opencode/agents/software-engineer.md

@@ -45,6 +45,14 @@ Load `skill session-workflow` first — it reads TODO.md, orients you to the cur
 
 - You own all technical decisions: module structure, patterns, internal APIs, test tooling, linting config
 - **PO approves**: new runtime dependencies, changed entry points, scope changes
+- **You never move `.feature` files.** The PO is the sole owner of all feature file moves (backlog → in-progress → completed). If you find no `.feature` file in `docs/features/in-progress/`, **STOP** — do not self-select a feature. Write the gap in TODO.md and escalate to PO.
+
+## No In-Progress Feature
+
+If `docs/features/in-progress/` contains only `.gitkeep` (no `.feature` file):
+1. Do not pick a feature from backlog yourself.
+2. Update TODO.md: `Next: Run @product-owner — load skill feature-selection and pick the next BASELINED feature from backlog.`
+3. Stop. The PO must move the chosen feature into `in-progress/` before you can begin Step 2.
 
 ## Spec Gaps
 

.opencode/skills/feature-selection/SKILL.md

@@ -100,7 +100,7 @@ Run @<agent-name> — <first concrete action for this feature>
 ```
 
 - If the feature has no `Rule:` blocks yet → Step 1 (SCOPE): `Run @product-owner — load skill scope and write stories`
-- If the feature has `Rule:` blocks but no `@id` Examples → Step 1 Phase 4 (Criteria): `Run @product-owner — load skill scope and write acceptance criteria`
+- If the feature has `Rule:` blocks but no `@id` Examples → Step 1 Stage 2 Step B (Criteria): `Run @product-owner — load skill scope and write acceptance criteria`
 - If the feature has `@id` Examples → Step 2 (ARCH): `Run @software-engineer — load skill implementation and write architecture stubs`
 
 ### 6. Commit

.opencode/skills/implementation/SKILL.md

@@ -28,7 +28,7 @@ Design correctness is far more important than lint/pyright/coverage compliance.
 
 ### Prerequisites (stop if any fail — escalate to PO)
 
-1. `docs/features/in-progress/` contains only `.gitkeep` (no `.feature` files). If another `.feature` file exists, **STOP** — another feature is already in progress.
+1. `docs/features/in-progress/` contains exactly one `.feature` file (not just `.gitkeep`). If none exists, **STOP** — update TODO.md `Next:` to `Run @product-owner — move the chosen feature to in-progress/` and stop. Never self-select or move a feature yourself.
 2. The feature file's discovery section has `Status: BASELINED`. If not, escalate to PO — Step 1 is incomplete.
 3. The feature file contains `Rule:` blocks with `Example:` blocks and `@id` tags. If not, escalate to PO — criteria have not been written.
 4. Package name confirmed: read `pyproject.toml` → locate `[tool.setuptools]` → confirm directory exists on disk.
@@ -39,24 +39,18 @@ Design correctness is far more important than lint/pyright/coverage compliance.
 2. Confirm directory exists: `ls <name>/`
 3. All new source files go under `<name>/`
 
-### Move Feature File
-
-```bash
-mv docs/features/backlog/<name>.feature docs/features/in-progress/<name>.feature
-```
-
-Update `TODO.md` Source path from `backlog/` to `in-progress/`.
+**Note on feature file moves**: The PO moves `.feature` files between folders. The software-engineer never moves or edits `.feature` files. Update TODO.md `Source:` path to reflect `in-progress/` once the PO has moved the file.
 
 ### Read Phase (all before writing anything)
 
-1. Read `docs/features/discovery.md` (project-level)
+1. Read `docs/discovery.md` (project-level synthesis changelog) and optionally `docs/discovery_journal.md` (Q&A history for context)
 2. Read **ALL** `.feature` files in `docs/features/backlog/` (discovery + entities sections)
 3. Read in-progress `.feature` file (full: Rules + Examples + @id)
 4. Read **ALL** existing `.py` files in `<package>/` — understand what already exists before adding anything
 
 ### Domain Analysis
 
-From Entities table + Rules (Business) in `.feature` file:
+From the Domain Model table in `docs/discovery.md` + Rules (Business) in the `.feature` file:
 - **Nouns** → named classes, value objects, aggregates
 - **Verbs** → method names with typed signatures
 - **Datasets** → named types (not bare dict/list)
@@ -116,19 +110,20 @@ class UserRepository(Protocol):
 
 Place stubs where responsibility dictates — do not pre-create `ports/` or `adapters/` folders unless a concrete external dependency was identified in scope. Structure follows domain analysis, not a template.
 
-### Write ADR Files (significant decisions only)
+### Record Architectural Decisions
 
-For each significant architectural decision, create or append to `docs/architecture/adr.md`:
+Append a new dated block to `docs/architecture.md` for each significant decision:
 
 ```markdown
-# ADR-NNN: <title>
+## YYYY-MM-DD — <feature-name>: <short title>
 
-**Decision:** <what was decided>
-**Reason:** <why, one sentence>
-**Alternatives considered:** <what was rejected and why>
+Decision: <what was decided>
+Reason: <why, one sentence>
+Alternatives considered: <what was rejected and why>
+Feature: <feature-name>
 ```
 
-Only write an ADR if the decision is non-obvious or has meaningful trade-offs. Routine YAGNI choices do not need an ADR.
+Only write a block for non-obvious decisions with meaningful trade-offs. Routine YAGNI choices do not need a record.
 
 ### Architecture Smell Check (hard gate)
 
@@ -155,7 +150,7 @@ Commit: `feat(<feature-name>): add architecture stubs`
 
 - [ ] Exactly one .feature `in_progress`. If not present, Load `skill feature-selection` 
 - [ ] Architecture stubs present in `<package>/` (committed by Step 2)
-- [ ] Read all `docs/architecture/adr.md` files — understand the architectural decisions before writing any test
+- [ ] Read `docs/architecture.md` — understand all architectural decisions before writing any test
 - [ ] Test stub files exist in `tests/features/<feature-name>/<rule_slug>_test.py` — one file per `Rule:` block, all `@id` stub functions present with `@pytest.mark.skip`; if missing, write them now before entering RED
 
 ### Write Test Stubs (if not present)
@@ -284,10 +279,10 @@ tests/features/<feature-name>/<rule_slug>_test.py
 ### Function Naming
 
 ```python
-def test_<rule_slug>_<@id>() -> None:
+def test_<feature_slug>_<@id>() -> None:
 ```
 
-- `rule_slug` = the `Rule:` title with spaces/hyphens replaced by underscores, lowercase
+- `feature_slug` = the `.feature` file stem with spaces/hyphens replaced by underscores, lowercase
 - `@id` = the `@id` from the `Example:` block
 
 ### Docstring Format (mandatory)