@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/references/archive/context-quality-tiers.md

@@ -0,0 +1,45 @@
+# Context Quality Tiers
+
+Behavioral guidance for agents based on context window utilization.
+
+## Tier Definitions
+
+| Tier | Context Used | Quality | Guidance |
+|------|-------------|---------|----------|
+| PEAK | 0-30% | Full capacity | Explore freely, read broadly, take time to understand |
+| GOOD | 30-50% | High capacity | Be selective with reads, skip non-essential exploration |
+| DEGRADING | 50-70% | Declining capacity | Write incrementally, finish current task, skip nice-to-haves |
+| POOR | 70%+ | Critical | Finish current task IMMEDIATELY and return. No new reads. |
+
+## Behavioral Rules Per Tier
+
+### PEAK (0-30%)
+- Read all relevant files before making changes
+- Explore adjacent code for patterns and conventions
+- Write comprehensive commit messages
+- Full self-check protocols
+
+### GOOD (30-50%)
+- Read only files directly relevant to current task
+- Skip exploratory reads of "nice to have" context
+- Standard commit messages
+- Standard self-check
+
+### DEGRADING (50-70%)
+- Write changes incrementally (don't accumulate large diffs)
+- Skip optional verification steps
+- Brief commit messages
+- Abbreviated self-check (key_files only)
+
+### POOR (70%+)
+- STOP exploring. Finish the current task only.
+- Write SUMMARY.md immediately if executor
+- Return completion marker immediately
+- Do NOT start new tasks or reads
+
+## Agent-Specific Overrides
+
+- **Researcher**: At DEGRADING, write findings immediately rather than accumulating
+- **Executor**: At DEGRADING, complete current task then return CHECKPOINT
+- **Verifier**: At DEGRADING, check existence only (skip substantiveness/wiring layers)
+- **Planner**: At GOOD, reduce task detail level; at DEGRADING, finish current plan file only

package/plugins/pbr/references/archive/hook-ordering.md

@@ -0,0 +1,89 @@
+# Hook Ordering Reference
+
+Claude Code does **not** guarantee execution order between separate hook entries
+registered on the same event matcher. This document records the ordering
+expectations and safety invariants that PBR hooks rely on.
+
+## PostToolUse Write|Edit Hooks
+
+Two independent hook entries fire on every `Write` or `Edit` tool use:
+
+| Hook Script | Purpose |
+|-------------|---------|
+| `post-write-dispatch.js` | Validates plan format, roadmap sync, state sync |
+| `post-write-quality.js` | Auto-format, type-check, detect console.log |
+
+These hooks may execute in **any order** or even concurrently. They are safe
+because they write to **different files** and do not share mutable state:
+
+- `post-write-dispatch` writes to `STATE.md`, `ROADMAP.md`, and logs.
+- `post-write-quality` only returns `additionalContext` warnings; it does not
+  write files.
+
+## PreToolUse Hooks
+
+PreToolUse hooks match on distinct tool types, so ordering between them is
+irrelevant:
+
+| Hook Script | Tool Matcher |
+|-------------|-------------|
+| `pre-write-dispatch.js` | `Write`, `Edit` |
+| `pre-bash-dispatch.js` | `Bash` |
+
+Within each dispatch script, sub-checks run sequentially and results are
+collected independently (no early returns).
+
+## Design Rules
+
+1. **No shared mutable state.** Hooks on the same event must not read/write the
+   same in-memory variable or the same file without coordination. Use
+   append-only patterns (e.g., `hook-logger.js` with `fs.open('a')`) for any
+   file that multiple hooks touch.
+
+2. **Idempotency.** Every hook must produce the same result if called twice with
+   the same input. This guards against Claude Code retrying a hook or firing it
+   redundantly.
+
+3. **Independent error handling.** Each hook wraps its logic in try-catch. One
+   hook crashing must not prevent others from running. Dispatch scripts
+   (`post-write-dispatch.js`) run all sub-checks and merge results.
+
+4. **Dirty flag protection.** `check-state-sync.js` uses mtime comparison to
+   detect external edits to `STATE.md` and `ROADMAP.md`. If another process
+   (or the user) modifies these files between hook invocations, the sync hook
+   skips the overwrite and logs a `skip-dirty` entry.
+
+## Known Safe Pairs
+
+These hook combinations fire on the same event and have been verified to not
+conflict:
+
+| Event | Hook A | Hook B | Why Safe |
+|-------|--------|--------|----------|
+| PostToolUse Write | `post-write-dispatch` | `post-write-quality` | Write different files |
+| PostToolUse Write | `post-write-dispatch` | `suggest-compact` | One writes state, other returns context |
+| PostToolUse Read | `track-context-budget` | (sole hook) | No conflict |
+| PostToolUse Task | `check-subagent-output` | (sole hook) | No conflict |
+
+## Adding New Hooks
+
+When registering a new hook on an existing event:
+
+1. Check this table for conflicts with existing hooks on the same event.
+2. Ensure your hook does not write to files that another hook on the same event
+   also writes.
+3. If you must share a file, use append-only writes (`fs.open` with `'a'` flag).
+4. Add your hook to the "Known Safe Pairs" table above.
+
+## PreToolUse and Session JSONL Logging
+
+**[Todo 016] Investigation result: by design.**
+
+Claude Code's session JSONL (at `~/.claude/projects/*/`) records tool calls, not hook decisions.
+
+- When a PreToolUse hook **allows** (exit 0): the tool runs and a `tool_use` + `tool_result` pair appears in session JSONL. The hook decision itself is NOT separately logged in session JSONL — visible only in `.planning/logs/hooks-*.jsonl`.
+- When a PreToolUse hook **blocks** (exit 2): the tool never runs, so no `tool_use` entry appears in session JSONL. The block IS recorded in `.planning/logs/hooks-*.jsonl`.
+
+**Implication for audit analysis:** The `/pbr:audit` behavioral compliance dimensions that rely on session JSONL will not see PreToolUse hook decisions. Use `.planning/logs/hooks-*.jsonl` directly for hook enforcement evidence. The BC-04 dimension (block-skill-self-read enforcement) should be verified from the hooks log, not session JSONL.
+
+**No code change required.** This is consistent with Claude Code's architecture.

package/plugins/pbr/references/archive/limitations.md

@@ -0,0 +1,106 @@
+# Accepted Limitations
+
+Known constraints in PBR's hook and CLI architecture. Each section explains
+the limitation, why it exists, and the recommended workaround.
+
+---
+
+## PostToolUse Hooks Are Warn-Only
+
+**Limitation**: PostToolUse hooks fire AFTER the tool has already executed. They
+can return `{ additionalContext: "..." }` to surface warnings, but they CANNOT
+block or undo the tool call.
+
+**Contrast with PreToolUse**: PreToolUse hooks fire BEFORE execution and can
+return `{ decision: "block", reason: "..." }` to prevent the action entirely.
+
+**Why it matters**: Validation that lives in a PostToolUse hook (e.g.,
+`check-plan-format.js` warning about malformed frontmatter) is advisory. The
+malformed file is already written to disk by the time the warning appears.
+
+**What to do instead**:
+
+- For critical enforcement (phase boundary, dangerous commands, format gates),
+  use **PreToolUse** hooks that block before execution.
+- Use PostToolUse only for telemetry, context injection, and soft advisories
+  where the cost of a bad write is recoverable.
+- Example: `check-phase-boundary.js` runs as PreToolUse to block cross-phase
+  writes. `post-write-quality.js` runs as PostToolUse because a missed
+  formatting warning is not destructive.
+
+---
+
+## CLI Commands in Prompts Are Best-Effort
+
+**Limitation**: When skill or agent prompts instruct the LLM to run CLI
+commands (e.g., `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state advance-plan`), the LLM may skip
+them under cognitive load. Prompt instructions are suggestions, not guarantees.
+
+**Why it matters**: State updates, progress tracking, and roadmap syncing that
+rely on agents calling CLI commands will be missed when the agent's context is
+saturated or it encounters deviations.
+
+**What to do instead**:
+
+- For critical state updates, use **hooks that fire automatically**. For
+  example, `check-state-sync.js` auto-syncs STATE.md on ROADMAP.md writes
+  without any agent cooperation.
+- Reserve CLI commands in prompts for actions where skipping is tolerable or
+  where hook-level enforcement is impractical.
+- Design principle: "Push intelligence into CODE (hooks/scripts), not PROMPTS
+  (markdown)."
+
+---
+
+## Hook Execution Order Is Not Guaranteed
+
+**Limitation**: When multiple hooks register on the same Claude Code event
+(e.g., two PostToolUse hooks on `Write`), their execution order is undefined.
+They may run sequentially in any order, or concurrently.
+
+**Why it matters**: If Hook A writes a file that Hook B reads, the result
+depends on which runs first -- producing nondeterministic behavior.
+
+**What to do instead**:
+
+- Design hooks to be **independent**: no hook should depend on another hook
+  having already run on the same event.
+- Hooks on the same event must not write to the same file. Use append-only
+  patterns (`fs.open` with `'a'` flag) for shared log files.
+- Each hook must be **idempotent** -- calling it twice with the same input
+  produces the same result.
+- See `references/hook-ordering.md` for the Known Safe Pairs table and
+  conflict-checking procedure when adding new hooks.
+
+---
+
+## Session State Flows via stdin, Not Shared Memory
+
+**Limitation**: Each hook invocation receives session context (`session_id`,
+`tool_name`, tool input) as a JSON blob on stdin. There is no persistent
+in-process state between hook calls -- every invocation is a fresh Node.js
+process.
+
+**Why it matters**: Hooks cannot accumulate state across calls without writing
+to disk. Any cross-call coordination requires file I/O (e.g., `.active-skill`
+files, mtime comparisons).
+
+**What to do instead**:
+
+- Accept the per-invocation cost of stdin parsing. It is fast (< 1ms) and
+  reliable.
+- For state that must persist across hook calls, use well-defined files with
+  clear ownership (one writer, many readers).
+- For session-scoped state, use the `session_id` from stdin to namespace files
+  (e.g., `.active-skill-{session_id}`).
+
+---
+
+## Summary Table
+
+| Limitation | Risk | Mitigation |
+|-----------|------|------------|
+| PostToolUse warn-only | Bad writes not blocked | Use PreToolUse for critical checks |
+| CLI in prompts skipped | State updates missed | Use auto-firing hooks instead |
+| Hook order undefined | Race conditions | Design hooks to be independent |
+| stdin-only session state | No cross-call memory | Use namespaced files for persistence |

package/plugins/pbr/references/archive/pbr-rules.md

@@ -0,0 +1,194 @@
+# Plan-Build-Run Rules
+
+Authoritative rules for all Plan-Build-Run skills, agents, hooks, and workflows.
+Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these rules govern.
+
+---
+
+## Philosophy
+
+1. **Context is precious.** The orchestrator stays lean (~15% usage). Delegate heavy work to subagents.
+2. **State lives on disk.** Skills and agents communicate through `.planning/` files, not messages.
+3. **Agents are black boxes.** Clear input/output contracts. Agents never read other agent definitions.
+4. **Gates provide safety.** Users control pace via config toggles. Never skip a gate.
+5. **One task, one commit.** Atomic commits for clean history and easy rollback.
+6. **Cross-platform always.** `path.join()`, CommonJS, test on Windows/macOS/Linux.
+7. **Test everything.** 70% coverage minimum. All 9 CI matrix combinations must pass.
+8. **PLAN-BUILD-RUN branding only.** Always use `PLAN-BUILD-RUN ►` prefix in banners.
+
+---
+
+## Context Budget
+
+9. Target 15% orchestrator context usage. Warn user at 30%.
+10. **Never** read agent definitions (`agents/*.md`) in the orchestrator — `subagent_type` auto-loads them.
+11. **Never** inline large files into `Task()` prompts — tell agents to read files from disk.
+12. **Never** read full subagent output — read frontmatter only (first 10-20 lines).
+13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
+14. Use the `limit` parameter on Read to restrict line counts.
+15. Proactively suggest `/pbr:pause-work` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
+
+---
+
+## State Management
+
+16. STATE.md is the **single source of truth** for current position.
+17. **Never** infer current phase from directory listings, git log, or conversation history.
+18. Always read STATE.md before making state-dependent decisions.
+19. Update STATE.md at: begin, plan, build, review, pause, continue, milestone.
+20. **Never** commit STATE.md mid-skill — hooks handle session persistence.
+21. Agents write artifacts (SUMMARY.md, VERIFICATION.md). Only the orchestrator writes STATE.md.
+22. Every ROADMAP.md phase must have a matching `.planning/phases/` directory, and vice versa.
+23. config.json is validated against `scripts/config-schema.json` on load.
+
+---
+
+## Agent Spawning
+
+24. Always use `subagent_type: "pbr:{name}"` to spawn agents.
+25. Pass file paths to agents, not file contents.
+26. Agents never read other agent definition files.
+27. Each agent gets a fresh 200k token context window — let them do the heavy reading.
+
+---
+
+## User Interaction Patterns
+
+28. Use `AskUserQuestion` for all structured gate checks — never plain-text "Type approved" prompts.
+29. AskUserQuestion is an orchestrator-only tool. It **cannot** be called from subagents (Task contexts).
+30. Max 4 options per AskUserQuestion call. If more options exist, split into a 2-step flow.
+31. `header` field must be max 12 characters. Keep it a single word when possible.
+32. `multiSelect` is always `false` for Plan-Build-Run gate checks.
+33. Always handle the "Other" case — users may type freeform text instead of selecting an option.
+34. Reuse patterns from `skills/shared/gate-prompts.md` by name. Do not reinvent prompts inline.
+35. Do **not** use AskUserQuestion for freeform text input (symptom gathering, Socratic discussion, open-ended questions). Use plain conversation for those.
+36. Skills that do not require user interaction (continue, health, help, pause) intentionally omit AskUserQuestion from allowed-tools.
+
+---
+
+## Skill Authoring
+
+37. Every SKILL.md starts with YAML frontmatter: `name`, `description`, `allowed-tools`, `argument-hint`.
+38. Skills that spawn agents **must** have a `## Context Budget` section.
+39. Mark each step as `(inline)` or `(delegate)` — inline for light work, delegate for analysis.
+40. Reference templates and references by filename — never inline them.
+41. Gate checks: read config toggle → display summary → ask user → proceed/abort/revise.
+42. Use branded UI elements from `references/ui-brand.md`.
+
+---
+
+## Agent Authoring
+
+43. Every agent file starts with YAML frontmatter: `name`, `description`, `model`, `memory`, `tools`.
+44. Agent name matches the agent file name (no prefix needed).
+45. `tools` array: only include tools the agent actually uses.
+46. Agents write artifacts to disk. They never modify STATE.md or ROADMAP.md.
+47. Agent definitions are self-contained — no cross-agent references.
+
+---
+
+## Hook Development
+
+48. All hooks use **CommonJS** (`require`), never ES modules (`import`).
+49. All hooks call `logHook()` from `hook-logger.js`. No silent exits.
+50. Exit codes: `0` = allow/success, `2` = block (PreToolUse only), other = error (logged, non-blocking).
+51. Hooks receive JSON on stdin, write JSON to stdout.
+52. Fail gracefully: wrap in try/catch, exit 0 on parse errors.
+53. Every hook in `hooks.json` must have a `statusMessage` field (gerund form: "Validating...", keep short).
+54. Windows file deletion: use 3-attempt retry loop to handle AV/indexer locks.
+55. Every hook script must have a corresponding `tests/{name}.test.js`.
+
+---
+
+## Commits
+
+56. Format: `{type}({scope}): {description}`.
+57. Valid types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `wip`.
+58. Valid scopes: a short descriptive word for what changed (e.g., `auth`, `executor`, `config`), `quick-{NNN}`, `planning`, or `{NN}-{MM}` (phase-plan, legacy).
+59. **Never** use `git add .` or `git add -A` — stage specific files only.
+60. Blocked files: `.env` (not `.env.example`), `*.key`, `*.pem`, `*.pfx`, `*.p12`, `*credential*`, `*secret*` (unless in `tests/` or `*.example`).
+61. TDD tasks: exactly 3 commits — RED (test), GREEN (feat), REFACTOR.
+62. Executors: one atomic commit per task.
+
+---
+
+## Templates
+
+63. Default syntax: `{variable}` placeholders for string substitution.
+64. Only use EJS (`<%= %>`, `<% %>`) when loops or conditionals are genuinely needed.
+65. Template files use `.tmpl` extension. Name matches the output file (e.g., `SUMMARY.md.tmpl` → `SUMMARY.md`).
+66. Templates live in `templates/` (global), `templates/codebase/` (scan), `templates/research/` (research), or `skills/{name}/templates/` (skill-specific).
+
+---
+
+## File Naming
+
+67. Skills: `plugins/pbr/skills/{skill-name}/SKILL.md` — lowercase hyphenated dir, uppercase `SKILL.md`.
+68. Agents: `plugins/pbr/agents/{name}.md` — agent name matches file name.
+69. Scripts: `plugins/pbr/scripts/{name}.js` — lowercase, hyphenated, CommonJS.
+70. References: `plugins/pbr/references/{name}.md` — lowercase, hyphenated.
+71. Tests: `tests/{script-name}.test.js` — mirrors the script name.
+
+---
+
+## Testing
+
+72. Test files mirror script names: `scripts/foo.js` → `tests/foo.test.js`.
+73. Use the fixture project at `tests/fixtures/fake-project/` for integration tests.
+74. Hook tests: use stdin/stdout protocol with `execSync()`, timeout 5000ms, run in temp dir.
+75. Coverage target: 70% branches/functions/lines/statements.
+76. CI matrix: Node 18/20/22 × ubuntu/macos/windows. All 9 must pass.
+77. Local pre-push: `npm run lint && npm test && npm run validate`.
+
+---
+
+## Cross-Platform
+
+78. **Never** hardcode `/` or `\` — always `path.join()`.
+79. Use `\n` in string literals — Node.js and Git normalize line endings.
+80. In `hooks.json`, use `${CLAUDE_PLUGIN_ROOT}` — Claude Code expands this internally on all platforms.
+81. **Never** use `$CLAUDE_PLUGIN_ROOT` (shell expansion is platform-dependent).
+82. **Never** rely on execute bits — always invoke via `node script.js`.
+
+---
+
+## Dependencies & Gates
+
+83. Check all `depends_on` plans have SUMMARY.md files before executing.
+84. Checkpoint tasks (`checkpoint:human-verify`) require STOP — write partial SUMMARY.md, return metadata.
+85. Respect all `gates.confirm_*` config toggles. Never auto-proceed when a gate is enabled.
+
+---
+
+## Logging
+
+86. Hook scripts → `logHook()` (writes to `logs/hooks.jsonl`, max 200 entries).
+87. Workflow milestones → `logEvent()` (writes to `logs/events.jsonl`, max 1,000 entries).
+88. Rule of thumb: inside a hook? `logHook()`. Tracking a high-level event? `logEvent()`.
+
+---
+
+## Gotchas
+
+89. JSDoc `*/` in glob patterns closes Babel comments early — use `//` line comments instead.
+90. Regex anchors: use `\b` word boundaries, not `^` anchors (misses chained commands like `cd && git commit`).
+91. Windows cwd locking in tests: use `cwd` option in `execSync()` instead of `process.chdir()`.
+92. PLAN.md frontmatter must include all required fields: `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, `must_haves`.
+
+---
+
+## Quick Reference: Never Do This
+
+| # | Anti-Pattern | Impact |
+|---|-------------|--------|
+| 1 | Read agent definitions in orchestrator | Context balloons 15% → 88% |
+| 2 | Inline large files into Task() prompts | Wasted orchestrator context |
+| 3 | Read full subagent output | Context bloat |
+| 4 | Use non-Plan-Build-Run branding | User confusion |
+| 5 | Hardcode path separators | Cross-platform breakage |
+| 6 | Use ES modules in hooks | Hook fails to load |
+| 7 | Skip hook logging | Silent failures |
+| 8 | Modify STATE.md in agents | Race conditions, corruption |
+| 9 | Use `git add .` | Sensitive data leaks |
+| 10 | Skip tests for new scripts | CI failures, regressions |