docs: add native memory help pack and enforce workflow in AGENTS

AGENTS.md

@@ -3,27 +3,42 @@
 This repo is execution-first, evidence-first, and beads-driven.
 
 ## Core Rules
-
-1. Use `bd` as the source of truth for work state.
-2. When user says "what's up" or "yo" or any introductory phrase, that means figure out what beads were recently closed and what beads are now unblocked and suggest the next bead to work on.
-3. No direct writes to `.beads/issues.jsonl`; mutate via `bd` commands only.
-4. Evidence before assertions: do not claim fixed/passing/done without fresh command output.
-5. Keep language simple in user-facing labels and UI copy.
-6. Reuse shared code paths/components; avoid one-off logic drift across pages.
-7. Treat BeadBoard as a multi-agent coordination + communication system first; optimize feature decisions for swarm execution clarity before cosmetic/layout preferences.
-8. Runtime UI route surface is query-driven from `/` (`view=social|graph|activity`); do not reintroduce direct App Router page sprawl without explicit approval.
+0. We both hate markdown files for memory; we use beads instead. View `beadboard/help/` for more info on how to use beads. Use the `--help` flags when you need help, or reference this folder.
+1. Our working directory for this project is `codex/beadboard`.
+2. Use `bd` as the source of truth for work state.
+3. When user says "what's up" or "yo" or any introductory phrase, that means figure out what beads were recently closed and what beads are now unblocked or related to the recently closed beads and suggest the next bead to work on using `bd query "status=closed" --sort closed --reverse --limit 10` and `bd ready`.
+4. No direct writes to `.beads/issues.jsonl`; mutate via `bd` commands only.
+5. Evidence before assertions: do not claim fixed/passing/done without fresh command output.
+6. Keep language simple in user-facing labels and UI copy.
+7. Reuse shared code paths/components; avoid one-off logic drift across pages.
+8. Treat BeadBoard as a multi-agent coordination + communication system first; optimize feature decisions for swarm execution clarity before cosmetic/layout preferences.
+9. Runtime UI route surface is query-driven from `/` (`view=social|graph|activity`); do not reintroduce direct App Router page sprawl without explicit approval.
 
 ## Quick Beads Workflow
 
 ```bash
 bd ready
 bd show <id>
-bd update <id> --status in_progress --notes "<plan>"
+bd update <id> --status in_progress
 bd update <id> --notes "<progress/evidence>"
 bd close <id> --reason "<what was completed>"
-bd sync
+bd dolt pull   # pull latest from remote before starting work
+bd dolt push   # push to remote after closing beads
 ```
 
+## Native Memory Workflow (Required)
+
+Use `help/memory/` for all memory operations.
+
+1. Memory source-of-truth is `bd` + Dolt history, not markdown files.
+2. At task start, run the query/injection playbook in `help/memory/query_and_injection.txt`.
+3. Canonical memory must be `decision` beads with labels:
+   - `memory,mem-canonical,mem-hard|mem-soft,<domain>`
+4. Memory indexing uses `bd dep relate` to domain anchors; do not use blocker edges for indexing.
+5. Only hard constraints may become blockers, via a memory-contract bead linked with `bd dep add`.
+6. Memory evolution must use `bd supersede <old> --with <new>`; do not rewrite canonical history.
+7. Apply noise budget limits from `help/memory/schema_and_noise_budget.txt` before adding new nodes.
+
 ## Bead Prompting Standard
 
 1. When creating or rewriting bead details, follow `docs/protocols/bead-prompting.md`.
@@ -44,7 +59,7 @@ bd sync
 1. Dependencies model execution order, not visual order.
 2. Validate that "ready/blocked/done" logic matches dependency semantics in all views.
 3. If a bead should be parallelizable, do not chain it unnecessarily.
-4. After closing a bead, confirm newly unblocked beads with `bd close <id> --suggest-next`.
+4. After closing a bead, confirm newly unblocked beads with `bd ready`.
 
 ## Test-First Implementation
 
@@ -127,9 +142,10 @@ When ending a coding session:
 4. Sync and push:
    ```bash
    git pull --rebase
-   bd sync
+   bd dolt pull
+   git add -p && git commit -m "..."
    git push
-   git status
+   bd dolt push
    ```
 5. Hand off with:
    - what changed,
@@ -164,27 +180,27 @@ unless you have run the proving command(s) in the current session and can cite r
 **Check for ready work:**
 
 ```bash
-bd ready --json
+bd ready
 ```
 
 **Create new issues:**
 
 ```bash
-bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
-bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
+bd create --title="Issue title" --description="Detailed context" --type=bug|feature|task --priority=0-4
 ```
 
 **Claim and update:**
 
 ```bash
-bd update bd-42 --status in_progress --json
-bd update bd-42 --priority 1 --json
+bd update <id> --status in_progress
+bd update <id> --notes "<evidence/progress>"
+bd update <id> --priority 1
 ```
 
 **Complete work:**
 
 ```bash
-bd close bd-42 --reason "Completed" --json
+bd close <id> --reason "Completed"
 ```
 
 ### Issue Types
@@ -209,29 +225,30 @@ bd close bd-42 --reason "Completed" --json
 2. **Claim your task**: `bd update <id> --status in_progress`
 3. **Work on it**: Implement, test, document
 4. **Discover new work?** Create linked issue:
-   - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
+   - `bd create --title="Found bug" --description="Details" --priority=1`
+   - `bd dep add <new-id> <parent-id>`
 5. **Complete**: `bd close <id> --reason "Done"`
 
-### Auto-Sync
+### Sync
 
-bd automatically syncs with git:
+Issues live in Dolt SQL (not JSONL). Sync with remote via:
 
-- Exports to `.beads/issues.jsonl` after changes (5s debounce)
-- Imports from JSONL when newer (e.g., after `git pull`)
-- No manual export/import needed!
+```bash
+bd dolt pull   # pull latest from remote before starting work
+bd dolt push   # push after closing beads
+```
+
+`.beads/issues.jsonl` is a **git-history artifact and fallback only** — do not treat it as the source of truth.
 
 ### Important Rules
 
 - ✅ Use bd for ALL task tracking
-- ✅ Always use `--json` flag for programmatic use
-- ✅ Link discovered work with `discovered-from` dependencies
 - ✅ Check `bd ready` before asking "what should I work on?"
+- ✅ Link related work with `bd dep add`
 - ❌ Do NOT create markdown TODO lists
-- ❌ Do NOT use external issue trackers
+- ❌ Do NOT write directly to `.beads/issues.jsonl`
 - ❌ Do NOT duplicate tracking systems
 
-For more details, see README.md and docs/QUICKSTART.md.
-
 ## Data Backend & Platform Notes
 
 BeadBoard reads issues from the Dolt SQL server (`bd`'s native backend since bd 0.56+). The Dolt server runs locally at `127.0.0.1:3307` and is started automatically by the `bd` daemon.

help/memory/README.txt

@@ -0,0 +1,14 @@
+BeadBoard Native Memory System (Index)
+
+Use this folder when you need to understand, query, or update memory in BeadBoard.
+Memory source-of-truth is bd + Dolt history, not markdown notes.
+
+Files:
+- memory_fabric_workflow.txt: full lifecycle and operating procedure
+- query_and_injection.txt: task-start retrieval and attachment commands
+- schema_and_noise_budget.txt: node types, edge rules, and anti-noise limits
+
+Fast path for agents:
+1) Read memory_fabric_workflow.txt
+2) Run query_and_injection.txt command sequence at task start
+3) Follow schema_and_noise_budget.txt before creating new memory nodes

help/memory/memory_fabric_workflow.txt

@@ -0,0 +1,46 @@
+# Memory Fabric Workflow (bd-native)
+
+Goal: keep memory durable, queryable, and behavior-changing without graph noise.
+
+Core model:
+1. Domain Anchors (open epic)
+- Purpose: index and discovery root per domain
+- Labels: memory,memory-anchor,<domain>
+- Example domains: memory-arch,memory-workflow,memory-ux,memory-agent,memory-reliability
+
+2. Canonical Memory Nodes (closed decision)
+- Purpose: ratified reusable rules/patterns
+- Labels: memory,mem-canonical,mem-hard|mem-soft,<domain>
+- Lifecycle: create -> ratify -> close
+
+3. Execution Contracts (open task or decision)
+- Purpose: temporary enforcement wrapper for hard constraints only
+- Labels: memory-contract,mem-hard,<domain>
+- Lifecycle: attach to active work while unresolved, close when satisfied
+
+Required lifecycle:
+1) Propose memory node
+- Create as decision bead using strict template fields (Scope, Out of Scope, Rule, Rationale, Failure Mode)
+
+2) Ratify memory node
+- Add acceptance checks and metadata JSON
+- Close with explicit reason: Ratified canonical memory
+
+3) Index memory node
+- Relate canonical node to exactly one primary domain anchor
+  bd dep relate <anchor-id> <memory-id>
+
+4) Inject memory into execution
+- At task start, query by domain and attach relevant nodes via relates_to
+- Promote only mem-hard constraints to blocker contracts
+
+5) Evolve memory safely
+- Do not rewrite historical canonical truth
+- Create a new canonical node and link lineage:
+  bd supersede <old-memory-id> --with <new-memory-id>
+
+Non-negotiables:
+- No direct writes to .beads/issues.jsonl
+- No markdown-only memory source of truth
+- No blanket blocker links for all memories
+- Evidence before completion claims

help/memory/query_and_injection.txt

@@ -0,0 +1,40 @@
+# Query and Injection Playbook
+
+Run this sequence at task start.
+
+Step 1: Determine task domain
+- Choose one primary domain label:
+  memory-arch | memory-workflow | memory-ux | memory-agent | memory-reliability
+
+Step 2: Query canonical memory for that domain
+```bash
+bd query "label=memory AND label=mem-canonical AND label=<domain> AND status=closed" --sort updated --reverse
+```
+
+Step 3: Query hard constraints subset
+```bash
+bd query "label=memory AND label=mem-canonical AND label=mem-hard AND label=<domain> AND status=closed" --sort updated --reverse
+```
+
+Step 4: Attach context to active work (soft + hard)
+```bash
+bd dep relate <active-task-id> <memory-id>
+```
+
+Step 5: Enforce hard constraints only (optional contract bead)
+```bash
+bd create --title "[MEMORY-CONTRACT] <short hard rule title>" --type task --labels memory-contract,mem-hard,<domain> --description "Contract for active task <active-task-id>" --acceptance "Hard rule is acknowledged and verified in task evidence." --silent
+bd dep relate <contract-id> <canonical-memory-id>
+bd dep add <active-task-id> <contract-id>
+```
+
+Step 6: Record acknowledgement
+```bash
+bd update <active-task-id> --notes "Memory injection: related <memory-id list>; hard contracts <contract-id list>."
+```
+
+Expected response patterns:
+- bd query: list of IDs + labels + titles
+- bd dep relate: relation confirmation
+- bd dep add: blocker edge confirmation
+- bd show/dep list: attached memory visible on task graph

help/memory/schema_and_noise_budget.txt

@@ -0,0 +1,55 @@
+# Memory Schema and Noise Budget
+
+One memory bead = one atomic reusable rule.
+If it is not reusable across future tasks, keep it in task notes instead.
+
+Canonical memory schema:
+- type: decision
+- status: closed (after ratification)
+- labels: memory,mem-canonical,mem-hard|mem-soft,<domain>
+- title format: [MEMORY][<DOMAIN>][HARD|SOFT] <rule sentence>
+
+Required description sections:
+- Scope:
+- Out of Scope:
+- Rule:
+- Rationale:
+- Failure Mode:
+
+Required acceptance style:
+- Given / When / Then invariant
+- Verification commands
+
+Required metadata JSON keys:
+- memory_version
+- memory_strength
+- domain
+- effective_date
+- owner
+- supersedes
+- superseded_by
+
+Edge rules:
+1) Anchor <-> Canonical memory
+- Use: bd dep relate
+- Never use blocker edge for anchor indexing
+
+2) Active task <-> Memory
+- Default: bd dep relate
+
+3) Active task <- Contract (hard rules only)
+- Use: bd dep add <active-task> <contract>
+
+4) Memory versioning
+- Use: bd supersede <old> --with <new>
+
+Noise budget limits:
+- Per active task: 3-7 related memory nodes
+- Per active task: 0-2 blocker contracts
+- Per canonical memory: 1 primary anchor domain
+- Promote incident/workaround memory only after repetition evidence
+
+Promotion policy:
+1) Incident repeats 2+ times -> candidate soft canonical memory
+2) Workaround survives release window -> candidate hard/soft canonical memory
+3) Obsolete canonical memory -> supersede, do not rewrite history