Adding in persistent knowledge base and milestone thinking

CHANGELOG.md

@@ -10,6 +10,24 @@ what a plugin user sees.
 
 ## [Unreleased]
 
+### Added
+- **`paad:kb-brain` — repository-native working knowledge for humans and
+  agents.** Initializes a `kb-brain/` tree (separate from stable `docs/`),
+  routes durable notes to the right section, and gives every managed task a
+  focused workspace with index-first retrieval. Sub-agents may append findings,
+  questions, failures, conflicts, and handoffs; only the lead or human owner
+  changes scope, assignments, confirmed decisions, or closure. Closed
+  workspaces are sealed (`SEAL.json`) and corrected only via amendments.
+  Ships templates plus stdlib `scripts/kb_brain.py` (`init` / `start` / `new` /
+  `index` / `check` / `close` / `amend`) and Make targets. Does not wire
+  automatic KBB behaviour into existing skills.
+- **`paad:brief-ruminate` — brief-to-milestone-spec expansion.** Reads a
+  human-owned brief, repository evidence, and KB-Brain context, then expands
+  one milestone into a candidate specification at `review-needed`. Stops before
+  approval, planning, or implementation; only a human may mark
+  `approved-spec`. Does not auto-run `pushback`, `alignment`, or
+  `agentic-review`.
+
 ## [1.24.1] — 2026-08-01
 
 ### Fixed

Makefile

@@ -2,14 +2,17 @@ SKILLS_DIR := plugins/paad/skills
 SKILL_DIRS := $(wildcard $(SKILLS_DIR)/*)
 SKILL_NAMES := $(notdir $(SKILL_DIRS))
 
-.PHONY: help test validate check-versions check-skill-versions check-digraphs check-help check-readme check-frontmatter check-references check-dispatch-sites check-announce check-export-current bump-version export release tag
+.PHONY: help test validate check-versions check-skill-versions check-digraphs check-help check-readme check-frontmatter check-references check-dispatch-sites check-announce check-export-current check-kb-brain bump-version export release tag
 
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-22s %s\n", $$1, $$2}'
 
-test: validate check-versions check-skill-versions check-digraphs check-help check-readme check-frontmatter check-references check-dispatch-sites check-announce check-export-current ## Run all checks
+test: validate check-versions check-skill-versions check-digraphs check-help check-readme check-frontmatter check-references check-dispatch-sites check-announce check-export-current check-kb-brain ## Run all checks
 	@echo "All checks passed."
 
+check-kb-brain: ## Run KB-Brain tooling unit tests
+	@python3 -m unittest discover -s plugins/paad/skills/kb-brain/tests -p 'test_*.py' -b
+
 validate: ## Validate marketplace and all plugins
 	@claude plugin validate .
 	@for dir in plugins/*/; do \

README.md

@@ -37,6 +37,8 @@ Not using Claude Code? PAAD also supports **Cursor**, **Kiro**, and
 | `/agentic-a11y [path]` | Accessibility audit against WCAG 2.2 AA, by disability category |
 | `/vibe [task]` | Small fixes, TDD guardrails still on |
 | `/makefile` | Creates or updates a project `Makefile` |
+| `/kb-brain [action...]` | Repository-native working knowledge base for humans and agents |
+| `/brief-ruminate [brief] [milestone]` | Expand one brief milestone into a candidate spec for human review |
 | `/paad:help [skill-name]` | Lists the skills, or explains one |
 | `/agentic-dedup [scope]` | Finds duplicated *meaning*, not duplicated text — experimental |
 | `/rethink [topic]` | Checks whether the premises under a recommendation hold — experimental |
@@ -663,6 +665,52 @@ automatically and never modifies an existing target without asking first.
 Note: this skill might be removed in the future, or moved to a different
 namespace. Let me know if you rely on it.
 
+#### `/kb-brain [action...]`
+
+Agents forget. Sessions end. The next run invents a different answer to a
+question you already settled. `kb-brain` keeps a repository-native working
+knowledge base under `kb-brain/` — mutable context, decisions, failures,
+improvements, debt, and focused task workspaces — while stable architecture
+stays in `docs/`.
+
+* **Arguments:** `/kb-brain init [level]`, `/kb-brain start <slug> [level]`,
+  `/kb-brain record <section> [title]`, `/kb-brain status [task-id]`,
+  `/kb-brain index`, `/kb-brain check`, `/kb-brain close [task-id]`,
+  `/kb-brain amend <closed-task-id> <record-path>`, `/kb-brain route <text>`
+* **Levels:** `minimal`, `standard` (default), `strict` — raise freely; lowering
+  below the repository default needs explicit human approval
+* **Permissions:** sub-agents append findings, questions, failures, conflicts,
+  and handoffs; only the lead or human owner changes scope, assignments,
+  confirmed decisions, or closes a workspace
+* **Closure:** sealed with `SEAL.json`; later corrections are amendments, not
+  edits to history
+* **Tooling:** copies `scripts/kb_brain.py` and Make targets into the target
+  repo on init — no bulk ingest of existing `docs/`
+
+Does not automatically wire into other PAAD skills. Invoke it explicitly, or
+point agents at it from `AGENTS.md`.
+
+#### `/brief-ruminate [brief-path] [milestone-id]`
+
+A human writes the project brief. `brief-ruminate` expands **one** milestone
+into a repository-grounded candidate specification for human review. It stops
+at `review-needed`. It does not approve the spec, plan the work, or run
+`pushback` / `alignment` / `agentic-review` for you.
+
+* **Arguments:** `/brief-ruminate <brief-path>`,
+  `/brief-ruminate <brief-path> <milestone-id>`,
+  `/brief-ruminate next <brief-path>`, `/brief-ruminate status <brief-path>`
+* **Storage:** `kb-brain/briefs/<slug>/` for the brief and milestones;
+  `kb-brain/specs/<slug>/` for candidate specs
+* **Selection:** without a milestone id, recommends the next valuable and
+  sufficiently unblocked milestone — not merely the first one
+* **Stop conditions:** missing controlling decisions, invented product
+  behaviour, unresolved ownership overlap, or an oversized milestone without an
+  accepted split — record the blocker and leave the work unapproved
+
+Requires `kb-brain/` to be present. Only a human may mark a spec
+`approved-spec`.
+
 #### `/vibe [task description]`
 
 Speed without recklessness. `vibe` supports smaller fixes and quick changes