refactor(docs+skills): consolidate doc structure and add arch interview protocol to architect skill

[nullhack]

Summary

This issue tracks a set of structural changes agreed during the beehave project doc design review. The changes consolidate redundant documentation files, slim the discovery.md format, embed arch Q&A into ADRs, and add a proper architectural interview protocol to the architect skill.

---

Changes Required

1. docs/system.md — absorb three separate files

• Add ## Domain Model section (entities, relationships, module graph — currently in docs/domain-model.md)
• Add ## Context section (C4 Level 1 diagram — currently in docs/context.md)
• Add ## Container section (C4 Level 2 diagram — currently in docs/container.md)
• Rename ## Relevant ADRs → ## ADRs and drop the index table (redundant with docs/adr/ directory)
• Fix any residual "test scaffolding" wording → "test stubs"

Delete: docs/domain-model.md, docs/context.md, docs/container.md

---

2. docs/discovery.md — slim to feature derivation table

• Replace current template with: per-session ## Session YYYY-MM-DD block containing a summary paragraph + | Feature | Change | Source questions | Reason | table
• Row criterion: a row appears only when a .feature file would be updated as a result of the session. Confirmations of existing behavior do not appear.
• Drop the ### Entities Added or Deprecated section entirely (glossary owns terms)

Example of the new format:

## Session 2026-04-21

**Summary**: Discovered the configuration reading and directory setup features.
Developer configures beehave via `[tool.beehave]` in `pyproject.toml`; CLI flags override config values.
`nest` is the initialization command; it is additive and idempotent.

| Feature | Change | Source questions | Reason |
|---|---|---|---|
| `config-reading` | created | C3: "Where is config stored?" → pyproject.toml; C1: "How is framework selected?" → explicit key, default=pytest | New behavior: read [tool.beehave], apply defaults, merge CLI overrides |
| `nest` | created | Q8: "What does the nest command do?" → directory + pyproject.toml init; Q8a: "--check mode?" → CI dry-run | New behavior: additive/idempotent init with --check and --overwrite modes |

---

3. docs/adr/*.md (9 files) — add ## Context section

Each ADR gains a ## Context section containing the Q&A exchange that produced the decision (currently in docs/arch_journal.md).

Delete: docs/arch_journal.md after Q&A is embedded into each ADR.

---

4. .opencode/skills/architect/SKILL.md — add arch interview protocol

• Add arch interview session flow:

  1. Read system.md (all sections)
     Read in-progress .feature
          ↓
  2. Domain modeling pass — entities, relationships, boundaries
     → update system.md (domain model section)
          ↓
  3. Critical thinking pass — pre-mortem, adversarial review, identify decisions
          ↓
  4. One architectural question → one ADR
     (answer goes into ADR ## Context section)
          ↓
  5. Write domain stubs (.py)
          ↓
  6. Update system.md
  

• Add ADR-per-question interview pattern (question format, context section, decision gate)
• Add CIT / laddering / pre-mortem techniques (same as define-scope — duplicated intentionally; no shared interview skill)
• Remove all references to docs/domain-model.md (now a section of system.md)
• Remove reference to domain-model.md.template
• Update read phase: read system.md only (no separate domain-model, context, container files)

---

5. .opencode/skills/define-scope/SKILL.md — update session flow and discovery format

• Clarify glossary is read before session start (anchors interview language) and updated after session closes (batch, not real-time during interview)
• Update discovery.md write instructions to match new slimmed format (feature derivation table, source questions column, behavioral-change-only criterion)
• Remove reference to entities section in discovery.md

---

6. AGENTS.md — update filesystem structure

• Remove domain-model.md, context.md, container.md from the Filesystem Structure section
• Update system.md description: "SA creates/updates at Step 2; absorbs domain model, C4 context, and C4 container sections"
• Remove arch_journal.md from Filesystem Structure

---

7. Residual "scaffold" term cleanup

The word "scaffold" must not appear in any current-state documentation. Occurrences to fix:

• docs/system.md line 5: "test scaffolding" → "test stubs"
• Any other current-state doc using "scaffold" as a verb or noun for the nest concept

Note: docs/adr/ADR-2026-04-22-module-structure.md contains historical references explaining why "scaffold" was rejected — these should remain unchanged as they document the rejected alternative.

---

File Action Summary

File	Action	Owner
docs/system.md	Update — add Domain Model + Context + Container sections; drop ADR index table; fix "scaffolding"	SA
docs/domain-model.md	Delete — content moved to system.md	SA
docs/context.md	Delete — content moved to system.md	SA
docs/container.md	Delete — content moved to system.md	SA
docs/discovery.md	Rewrite — slim to feature derivation table with source questions	PO
docs/arch_journal.md	Delete — Q&A embedded into ADR ## Context sections	SA
docs/adr/*.md (9 files)	Update — add ## Context section per ADR	SA
.opencode/skills/architect/SKILL.md	Rewrite — add arch interview protocol; update read phase	SA
.opencode/skills/define-scope/SKILL.md	Update — glossary timing + discovery format	PO
AGENTS.md	Update — filesystem structure table	human/stakeholder

[nullhack]

Partially resolved in v7.1.20260422 (PR #107):

Done:

• docs/system.md now absorbs ## Domain Model, ## Context (C4 L1), and ## Container (C4 L2) sections — domain-model.md, context.md, container.md deleted
• AGENTS.md filesystem structure updated to remove those three files
• docs/index.html updated — context.md card replaced with system.md#context
• Architectural Interview Protocol already exists in .opencode/skills/architect/SKILL.md (items 1 and 4 from this issue)

Still open:

1. docs/discovery.md slim format — feature-derivation table with Source questions column (item 2)
2. ADR ## Context sections with embedded arch Q&A (item 3)
3. define-scope skill update for new discovery.md format (item 5)
4. Residual scaffold → test stubs cleanup (item 7)