@tyroneross/build-loop 0.30.3

package/skills/build-loop/references/self-review.md

@@ -0,0 +1,232 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Self-Review — Periodic Autonomous Self-Improvement
+
+Single source of truth for the build-loop self-review subsystem: purpose, light/deep model, config schema, launchd schedule, graceful degradation, and the headless apply prompt.
+
+---
+
+## Purpose
+
+Self-review mines recent build-loop runs for recurring issues and efficiency signals, produces a human-readable digest, and (in deep mode) automatically applies safe improvements via the normal build-loop pipeline. It closes the loop between observations captured during builds and durable fixes that land in the repo — without requiring the user to manually schedule or trigger a review.
+
+Two cadences balance cost against coverage:
+
+| Mode | Default cadence | Scope | Auto-apply |
+|---|---|---|---|
+| **light** | Daily (09:00) | Issues in the last 7 days; proposal cap 10 | No — digest + queue only |
+| **deep** | Weekly (Sunday 03:00) | Issues in the last 30 days; uncapped | Yes — SAFE proposals auto-routed through build-loop |
+
+---
+
+## Config schema
+
+Add a `selfReview` block to `.build-loop/config.json` (all fields optional; defaults shown):
+
+```json
+{
+  "selfReview": {
+    "enabled": true,
+    "autonomy": "apply_push",
+    "light": "daily",
+    "deep": "weekly"
+  }
+}
+```
+
+| Field | Values | Meaning |
+|---|---|---|
+| `enabled` | `true` / `false` | `false` disables the launchd jobs and is a no-op for the installer |
+| `autonomy` | `apply_push` \| `apply_local` \| `propose` | `apply_push` — apply SAFE items and push main; `apply_local` — apply but do not push; `propose` — queue only, no auto-apply |
+| `light` | `daily` \| `weekly` \| `disabled` | Cadence for the light job |
+| `deep` | `daily` \| `weekly` \| `disabled` | Cadence for the deep job |
+
+Cadence values map to launchd `StartCalendarInterval`. `daily` → every day at the job's configured hour. `weekly` → once per week on the configured weekday. `disabled` skips installing that job.
+
+---
+
+## How it works
+
+### Data-gathering layer (scripts/self_review/ package — frozen CLI)
+
+`python3 scripts/self_review/__main__.py --mode {light|deep} [--workdir <repo>] [--days N] [--dry-run] --json`
+
+Always exits 0. Writes:
+- `.build-loop/self-review/<UTCdate>-<mode>.md` — human digest
+- `.build-loop/proposals/self-review-*.md` — one file per candidate improvement, each with `classify_hint: SAFE|RISKY|DECISION` frontmatter
+
+Returns JSON to stdout:
+```json
+{
+  "mode": "light|deep",
+  "window_days": 7,
+  "mined": {"corrections": [], "rituals": [], "sequences": []},
+  "efficiency_findings": [],
+  "self_simplification": [],
+  "digest_path": ".build-loop/self-review/2026-05-29-deep.md",
+  "queued": [".build-loop/proposals/self-review-foo.md"],
+  "errors": [],
+  "dry_run": false
+}
+```
+
+**`self_simplification[]`** (deep mode, self-recursive only): a list of proactive simplification findings for build-loop's own code. Each entry has the shape:
+
+```json
+{
+  "target": "self",
+  "file": "<relative path>",
+  "finding": "<one-line description>",
+  "classify_hint": "SAFE|RISKY|DECISION",
+  "proposed_action": "<what to do>"
+}
+```
+
+`target: self` marks a proposal as targeting build-loop's own code (plugin repo or `build-loop-memory`). These proposals are subject to the SELF-MODIFICATION SAFETY GATE (see §"Self-modification of the restricted repo" below) — they are never processed by the standard reactive-fix path.
+
+Deep mode digests include an `## Apply plan` section that separates SAFE-to-auto-apply items from RISKY-to-surface items. When `self_simplification[]` is non-empty, the digest also includes a `## Self-simplification proposals` section listing each `target: self` finding.
+
+### Scheduling layer (launchd)
+
+`python3 scripts/install_self_review.py install` writes two plists to `~/Library/LaunchAgents/`:
+
+- `com.tyroneross.buildloop.selfreview-light.plist` — daily at 09:00, invokes `scripts/self_review_run.sh light`
+- `com.tyroneross.buildloop.selfreview-deep.plist` — weekly Sunday at 03:00, invokes `scripts/self_review_run.sh deep`
+
+Both jobs write output to `.build-loop/self-review/launchd-{light,deep}.log`.
+
+### Wrapper layer (scripts/self_review_run.sh)
+
+Invoked by launchd (or manually). Runs the gatherer, saves the JSON snapshot to `.build-loop/self-review/last-<mode>.json`, appends a timestamped line to `.build-loop/self-review/run.log`, and (for deep mode with `autonomy` in `{apply_push, apply_local}`) invokes the headless apply prompt via `claude -p`.
+
+---
+
+## Install / uninstall / status
+
+```bash
+# Install both launchd jobs
+python3 scripts/install_self_review.py install
+
+# Remove launchd jobs and plists
+python3 scripts/install_self_review.py uninstall
+
+# Check loaded/not-loaded
+python3 scripts/install_self_review.py status
+
+# JSON output for any subcommand
+python3 scripts/install_self_review.py status --json
+```
+
+Or via the slash command: `/build-loop:self-review --install` / `--uninstall` / `--status`.
+
+---
+
+## Graceful degradation
+
+If the `claude` CLI is not installed or not on PATH when the deep wrapper fires, the wrapper logs the skip reason and exits 0. The digest and queued proposals are still produced — the user can process them manually via `/build-loop:run` or `/build-loop:self-review deep`.
+
+The queue accumulates across skipped deep runs. On the next successful headless invocation, all queued SAFE proposals are processed.
+
+---
+
+---
+
+## Self-modification of the restricted repo
+
+The self-review/self-heal loop is authorized to write to the restricted repo — build-loop's own plugin repo and the `build-loop-memory` durable repo (lessons and skills). This is normally a guarded action because it edits the running runtime.
+
+**The SELF-MODIFICATION SAFETY GATE is MANDATORY and non-negotiable for ANY change to build-loop's own code.** It is the load-bearing safety for this authorization.
+
+### Gate protocol (every self-modification commit must pass all steps)
+
+**Step 1 — Bundle first (reversibility):**
+```bash
+git bundle create .build-loop/bundles/pre-selfmod-$(date +%Y%m%dT%H%M%S).bundle --all
+```
+Always bundle before any self-modification. This is the rollback point.
+
+**Step 2 — Self-recursive / per-commit mode:**
+Self-modifications use the existing per-commit mode machinery (one commit at a time, reviewed before the next). `selfRecursive.enabled` is `true` when the working directory IS build-loop's own repo. Do not batch multiple self-modification commits without a gate pass between each.
+
+**Step 3 — Verify gate (MANDATORY before commit):**
+```bash
+python3 scripts/self_mod_verify.py \
+  --workdir "$PWD" \
+  --scope auto \
+  --changed-files <space-separated file list> \
+  --auto-revert \
+  --json
+```
+`--scope auto` runs mapped tests for small changes and broader tests for multi-file/core changes (practical default). Use `--scope full` for the slow exhaustive option (900s, parallel when pytest-xdist is present).
+
+`verdict: pass` → the self-modification may commit.
+`verdict: fail` → the gate AUTO-REVERTS the change and writes the finding to `.build-loop/proposals/failed-gate/`. The change is NEVER committed. Do not retry a failed gate verdict without diagnosing the root cause.
+
+**Self-modifications execute — they do not stop the loop.** A self-modification that is part of the accepted plan (including edits to the gate, tests, or the self-improvement loop) executes behind the test-suite gate: `self_mod_verify.py --scope auto --auto-revert` must return `verdict: pass` (tests are the oracle; a failed gate auto-reverts the change). Build-loop never halts a planned self-modification for human approval. Oversight is post-hoc, not a gate: (a) self-modifying runs trigger an ADDITIONAL adversarial review (independent-auditor at build scope; the periodic deep self-review re-audits recent self-modifications) — non-blocking; (b) the end-of-run readback reports every self-modification and the additional-review findings so the human sees results at the end. The loop stays on task and reports once, at the end.
+
+**Step 4 — SAFE-only auto-apply:**
+Only changes that `classify_action.py` classifies as SAFE auto-apply through this path. Structural or architectural self-modifications — new phase, changed dispatch contract, agent-role change — surface as DECISION and are never auto-applied. They are queued to `.build-loop/proposals/needs-decision/` for explicit user action.
+
+### Authorized targets
+
+- Build-loop's own plugin repo (files under the build-loop working directory when `selfRecursive.enabled`)
+- `build-loop-memory` durable repo: lessons, skills, and project-scoped memory entries written via `scripts/memory_writer.py`
+
+### What is NOT authorized without user confirmation
+
+- Promotion of project-local skills to `~/.claude/skills/` (global scope — confirm first)
+- Changes to `agents/build-orchestrator.md` phase contracts or MECE ownership rules (structural — DECISION; surface as DECISION, never auto-apply)
+
+---
+
+## APPLY PROMPT
+
+This is the exact prompt text fed to `claude -p` by `scripts/self_review_run.sh` for deep auto-apply. Do not paraphrase — the wrapper reads this file and extracts the block between the `BEGIN_APPLY_PROMPT` and `END_APPLY_PROMPT` markers.
+
+<!-- BEGIN_APPLY_PROMPT -->
+You are running headlessly as part of a scheduled build-loop self-review. Your job is to apply safe improvements identified by the periodic self-review.
+
+Step 1 — Read the context:
+- Read `.build-loop/self-review/last-deep.json` (the data-gatherer output).
+- For each path listed in `queued[]`, read the proposal file. Take only proposals where `classify_hint: SAFE`.
+- Skip any proposal where `classify_hint` is `RISKY` or `DECISION` — leave those files untouched.
+- Separately, collect every entry in `self_simplification[]` where `classify_hint: SAFE` AND `target: self`. These are proactive self-simplifications of build-loop's own code and require the SELF-MODIFICATION SAFETY GATE in Step 2b.
+
+Step 2a — Apply each SAFE non-self proposal:
+For each SAFE proposal without `target: self`, route it through `/build-loop:run` with a goal derived from the proposal's title and body. Build-loop handles apply + commit + collapse. Its own autonomy gate and deployment policy govern what lands — do not bypass them.
+
+Step 2b — Apply SAFE `target: self` proposals (self-modification path):
+Self-modifications execute — they do not stop the loop. For each SAFE `target: self` proposal, apply the change, then — BEFORE committing — run the MANDATORY SAFETY GATE:
+```bash
+python3 scripts/self_mod_verify.py \
+  --workdir "$PWD" \
+  --scope auto \
+  --changed-files <the files you changed> \
+  --auto-revert \
+  --json
+```
+- `verdict: pass` → commit the change via the normal per-commit mode (one commit per self-modification; do not batch). The self-modification is recorded for the end-of-run readback.
+- `verdict: fail` → the gate has already auto-reverted the change. Move the proposal to `.build-loop/proposals/failed-gate/` and continue with the next proposal. NEVER commit a failed-gate self-modification.
+- Skip any `target: self` proposal that `classify_action.py` does not classify as SAFE (RISKY → isolate to worktree-branch + log; DECISION → queue to `.build-loop/proposals/needs-decision/`, do not apply).
+
+Do NOT stop the loop for any self-modification, including those that touch the gate scripts, tests, or the self-improvement loop. The test-suite gate is the oracle; if it passes, the change commits and is reported at the end.
+
+Step 3 — Determine push behavior:
+Read `.build-loop/config.json` key `selfReview.autonomy` (default `apply_push`).
+- If `apply_push`: after all SAFE proposals have been routed and landed, run `git push origin main` for the accumulated commits. Build-loop's deployment_policy still gates this; if the push is blocked by policy, log the block and exit 0 — do not force.
+- If `apply_local`: do not push. Commits land locally; the user pushes manually.
+
+Step 4 — Report:
+Print a short summary: how many SAFE proposals were processed (split: standard vs `target: self`), how many RISKY/DECISION items were left queued, how many `target: self` proposals were gated/reverted by a failed test gate, and the push status (pushed / local-only / skipped by policy / n/a).
+
+Include a `## Self-modifications (readback)` section listing every self-modification that landed this run: file, one-line what/why, test-gate verdict, and the additional-review finding (pass/flag). If no self-modifications occurred, omit the section.
+
+Constraints:
+- Never apply a RISKY or DECISION proposal autonomously.
+- Never apply a `target: self` proposal without running `self_mod_verify.py` first.
+- Never commit a change that `self_mod_verify.py` returned `verdict: fail` for.
+- Never stop the loop for a self-modification — including those that touch the gate, tests, or self-improvement loop scripts. The test gate is the oracle; pass → commit and continue; fail → auto-revert and continue. Report at the end.
+- Never bypass build-loop's commit auditor or autonomy gate.
+- If build-loop is not available as a slash command, log the unavailability and exit 0 — the queue stays intact.
+- This is a local developer tool; there are no users to protect other than the repo owner.
+<!-- END_APPLY_PROMPT -->

package/skills/build-loop/references/ui-io-contract.md

@@ -0,0 +1,116 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# UI Input/Output Contract
+
+Use this contract for any build-loop task that adds, modifies, or validates a user-facing UI surface. It turns "build the component" into an explicit inventory of what the user can provide, what the system returns, and which UI pattern must handle each data shape.
+
+## When It Applies
+
+Apply this when `uiTarget != null` and the task changes any screen, component, form, table, chart, voice/audio affordance, file workflow, generated output, or streamed response. Skip only for copy-only changes that do not alter the available inputs, outputs, states, or operations.
+
+## Required Plan Section
+
+Every UI plan must include a `## UI Input/Output Contract` section before implementation. Use one row per affected screen or component, and keep each field concrete.
+
+| Field | Required Answer |
+|---|---|
+| Surface | Screen/component name plus file path |
+| User inputs | Every value the user can provide |
+| System outputs | Every value the user receives or decides from |
+| Data taxonomy | Structural type, content format, persistence intent |
+| Operation model | CRUD operation plus any domain verb |
+| Component mapping | Exact input control and output renderer |
+| State matrix | Empty, populated, focused, disabled, loading, success, error, and streaming/abort when relevant |
+| Modality | Text, voice, file, vision, chart, map, AI/generated, or streaming; include fallback |
+| Validation/security | Presentation, application, and domain validation; sanitization; auth/authz display behavior |
+| Traceability | Data schema, API endpoint/method, design-system component, and rationale |
+
+## Data Taxonomy
+
+Classify each input and output before choosing UI controls:
+
+- **Structural type**: scalar, structured object/array, binary, stream.
+- **Content format**: plain text, Markdown, rich text, HTML, JSON tree, chart data, audio, image, map/geospatial.
+- **Persistence intent**: persisted CRUD data, transient session state, real-time stream, computed/derived output.
+
+## Operation Model
+
+Name the operation the UI performs:
+
+- **Create**: POST, form, wizard, inline add.
+- **Read**: GET, table, card, detail view, chart.
+- **Update**: PUT/PATCH, edit form, inline edit, toggle.
+- **Delete**: DELETE, destructive button, confirmation.
+- **Domain verbs**: submit, approve, publish, escalate, cancel, refund, reorder, filter, sort, export, download.
+
+Do not hide domain verbs inside generic "update" language when rules, side effects, or affordances differ.
+
+## Component Mapping
+
+Choose components from the data shape, not habit.
+
+| Data Shape | Input Control | Output Renderer |
+|---|---|---|
+| Short string | Single-line input | Text with overflow/copy behavior |
+| Long plain text | Textarea with sizing policy | Paragraph or preformatted text |
+| Markdown | Split write/preview editor | Sanitized Markdown renderer |
+| Rich text | Schema-backed editor | Paired rich-text viewer |
+| JSON/object | Schema-aware JSON editor/tree | Collapsible tree or raw/parsed toggle |
+| Number | Number input, slider, or stepper | Locale-aware number display |
+| Boolean | Toggle, checkbox, or yes/no radio | Explicit state label |
+| Date/time | Date/time/range picker | Locale/timezone-aware display |
+| Enum | Select, radio group, or searchable select when options exceed seven | Label/chip/list value |
+| File/binary | Upload/dropzone with progress | Preview/download with file metadata |
+| Voice/audio | Mic button with waveform and text fallback | Audio player/TTS plus transcript |
+| Tabular data | Filters/search feeding table | Sort/filter/paginated table |
+| Chart data | Form/filter inputs feeding visualization | Named chart type plus table fallback |
+| Streaming/AI output | Prompt or structured input | Token/partial renderer with abort and retry |
+| Geospatial | Address/map controls | Map with markers/clusters and fallback text |
+
+## State Matrix
+
+Document the states each component must render:
+
+- Default/empty.
+- Populated/filled.
+- Focused.
+- Hover on pointer devices.
+- Active/pressed.
+- Disabled/permission-blocked.
+- Loading.
+- Success.
+- Error/invalid.
+- Empty result.
+- Streaming/partial with abort and retry behavior when relevant.
+
+## Modalities
+
+When a modality exists, it needs its own UI and failure path:
+
+- **Text**: text input, textarea, rich text, text/Markdown renderer.
+- **Voice**: push-to-talk or wake-word trigger, ASR provider/threshold if known, transcript fallback, TTS controls.
+- **File**: upload control, MIME/size rules, preview/download, copy-text fallback.
+- **Vision/image**: image upload/camera, viewer/annotation, alt-text fallback.
+- **Chart/graph**: chart type, data schema, axis labels, colorblind-safe palette, table fallback.
+- **AI/generated output**: output type contract, response schema/template, streaming vs complete mode, abort/retry behavior.
+
+## Validation And Security
+
+Validation must be named by layer:
+
+- **Presentation**: required fields, max length, pattern, type, inline field errors.
+- **Application**: cross-field and business-rule errors, form-level/toast surface.
+- **Domain**: invariant failures, system-error surface, and whether repeated domain failures indicate a spec gap.
+- **Sanitization**: allowed subset for Markdown, rich text, HTML, JSON, and generated content.
+- **Auth/authz**: permission required for create/update/delete/domain verbs, and UI behavior when denied: hidden, disabled, or 403/empty view.
+
+## Traceability
+
+Each UI element that accepts or returns data must trace to:
+
+- Data model or schema version.
+- API endpoint/method or local data source.
+- Design-system component or explicit net-new rationale.
+- Test or validation evidence.
+
+If the trace cannot be named, the plan is incomplete.