@tyroneross/build-loop 0.30.3 → 0.35.0

package/plugin-artifacts/codex/references/recent-design-structures.md

@@ -0,0 +1,274 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Recent Design Structures
+
+Runtime reference for `design-contract-specialist` when choosing UI design direction. This file is a compact structure library, not a style mandate.
+
+## Use Rule
+
+Pick the structure that fits the current product job, workflow frequency, information density, data shape, platform, and risk. Do not apply a structure because it is recent, rated well, visually attractive, or available in this file.
+
+Every Phase 2 `## Design Direction` should record:
+
+1. `selected_structure`
+2. `why_it_fits`
+3. `rejected_structure`
+4. `why_rejected`
+5. `source_refs`
+6. `validation_implications`
+
+## Selection Axes
+
+Classify the surface before choosing structure:
+
+| Axis | Questions |
+|---|---|
+| Product job | Is the user operating, deciding, conversing, building, analyzing, configuring, recovering, or learning? |
+| Workflow frequency | Is this a repeated work surface, a one-time onboarding path, or an occasional settings/detail surface? |
+| Data shape | Is the core object a message, list, table, step sequence, chart, document, graph, timeline, or media artifact? |
+| Density | Does the user need scan, compare, decide, or deeply read? |
+| Platform | Web desktop, mobile web, native iOS, macOS, watchOS, or cross-platform? |
+| Risk | Could a wrong click, fake affordance, hidden source, or misleading chart cause harm? |
+
+## Structures
+
+### 1. Conversational Command Surface
+
+Use when the product starts from user intent in natural language but must produce a concrete artifact, decision, skill, or task output.
+
+Structure:
+- Header with product identity and one primary action.
+- Two-lane layout: conversation/input lane plus outcome/status lane.
+- Composer is prominent but not the whole product when outputs matter.
+- Suggested prompts are subordinate; they are accelerators, not competing primary actions.
+- Output cards show concrete value, feasibility, or next step.
+
+Good fit:
+- AI assistants that build artifacts.
+- Intake-to-plan flows.
+- "Tell me the problem, then ship the output" products.
+
+Reject when:
+- The user primarily monitors many standing objects.
+- The user needs direct table/list management more than conversation.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-01-sunrise-hero.html`
+- `UI Guidance/mockups/evaluation-workbench--v2-02-electric-mint.html`
+- `UI Guidance/mockups/evaluation-workbench--v2-05-bloom-organic.html`
+
+### 2. Bento Operating Dashboard
+
+Use when the product is a repeated home base with multiple live objects, one central creation/ask action, and several scannable operational tiles.
+
+Structure:
+- Hero ask/action tile dominates.
+- Secondary tiles show ledger, active objects, queue, and quick decisions.
+- Use a 12-column grid on desktop; cards span according to importance.
+- Keep the chat/action as one tile, not the whole app.
+- The dashboard should answer: what is active, what changed, what is next, what can I do now?
+
+Good fit:
+- Personal operating systems.
+- Product home screens where the user returns often.
+- Workflow dashboards with useful standing state.
+
+Reject when:
+- The user has one linear task.
+- The product has no real standing data.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-04-bento-dashboard.html` (rated yay)
+
+### 3. Pipeline Wizard
+
+Use when a multi-step process needs visible progress, traceable decisions, and contextual input for each step.
+
+Structure:
+- Top stepper with 3-5 named steps.
+- Current step panel owns the main content.
+- Contextual chat/input lives beside or below the current step.
+- Each step exposes criteria, intermediate output, and next action.
+- Final step produces a concrete artifact or decision.
+
+Good fit:
+- MCDA, evaluation, diagnosis, onboarding, build pipelines.
+- Workflows where the user should understand why the next step exists.
+
+Reject when:
+- Steps are decorative or could be one form.
+- The user needs fast repeated scanning instead of guidance.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-03-pipeline-wizard.html`
+
+### 4. Outcome Ledger List
+
+Use when the user needs to scan a collection of prior decisions, jobs, skills, or outcomes and understand value quickly.
+
+Structure:
+- Summary/ledger hero at top.
+- Filter chips directly below the hero.
+- List cards include title, category/status, primary outcome metric, and next affordance.
+- Rows must be scannable in about 2 seconds.
+- Empty state preserves layout height and names what will appear.
+
+Good fit:
+- Decision history, saved automations, skill libraries, task queues, project ledgers.
+
+Reject when:
+- The collection has no reliable outcome metric.
+- Detail reading is more important than list scanning.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-06-decisions-list-fun.html`
+
+### 5. Pyramid Detail Page
+
+Use when a detail view must replace a wall of text with a decision-first hierarchy.
+
+Structure:
+- Hero states the primary outcome in plain language.
+- Three MECE supporting cards explain why.
+- This-week/current-impact section makes near-term value concrete.
+- Paired paths section shows viable alternatives without nudging.
+- MCDA/math/provenance sit under disclosure.
+- Keep no more than 5 major chunks visible at once.
+
+Good fit:
+- Decision details, recommendation details, audit explanations, strategy outputs.
+
+Reject when:
+- The user needs raw source review as the primary job.
+- There is no actual decision, outcome, or rationale to explain.
+
+Recent refs:
+- `UI Guidance/mockups/evaluation-workbench--v2-07-detail-fun.html`
+
+### 6. Glass Workspace
+
+Use for data-rich professional tools where the user manages structured information and needs craft without losing density.
+
+Structure:
+- Sidebar or stable navigation when object count is high.
+- Left-border accent as category/status signal.
+- Source dot plus text metadata, not separate badge clutter.
+- Card grid uses `repeat(auto-fill, minmax(300-320px, 1fr))` at desktop.
+- Optional third detail pane at 280-320px for focused review.
+
+Good fit:
+- Developer tools, knowledge bases, dashboards, pipeline monitors.
+
+Reject when:
+- The surface is mobile-first, reading-heavy, or calm/clinical.
+- Glass effects would reduce contrast or obscure content.
+
+Recent refs:
+- `UI Guidance/cross-platform-design-patterns.md`
+- `UI Guidance/aurora-deep.md`
+- `UI Guidance/aurora-glass.md`
+
+### 7. Warm Craft Workbench
+
+Use for reflective writing, document work, knowledge organization, or human-feeling tools where warmth helps trust and comprehension.
+
+Structure:
+- Warm neutral base with restrained amber/coral accents.
+- Left accent bar connects cards, navigation, and section headers.
+- Sectioned sidebar or grouped content blocks.
+- Generous but structured spacing.
+- Texture is enhancement only; content structure must work without it.
+
+Good fit:
+- Writing tools, personal knowledge systems, review surfaces, human-in-the-loop planning.
+
+Reject when:
+- The user needs dense operational monitoring.
+- Warm palette could make risk, status, or urgency ambiguous.
+
+Recent refs:
+- `UI Guidance/warm-craft.md`
+- `UI Guidance/cross-platform-design-patterns.md`
+
+### 8. Data Narrative
+
+Use when the UI presents research, trends, news, benchmarks, or evidence and needs to tell the user what matters before showing the raw data.
+
+Structure:
+- Decision-first title or subtitle above every chart.
+- Dark atmospheric hero is allowed only when it introduces the domain; dense content should move to a readable light or neutral area.
+- Bento/grid sections can organize evidence, but every chart needs a reason to exist.
+- Source attribution is visible near the chart or section.
+
+Good fit:
+- Market research, briefing, analytics, trend reporting, intelligence products.
+
+Reject when:
+- The data is too sparse or unreliable.
+- A sentence would communicate the answer better than a chart.
+
+Recent refs:
+- `UI Guidance/data-visualization-patterns.md`
+- `UI Guidance/cross-platform-design-patterns.md`
+
+### 9. Native Mobile Action System
+
+Use for native or mobile-web surfaces where touch certainty, safe areas, and progressive disclosure matter more than desktop density.
+
+Structure:
+- One hero CTA per home screen.
+- Touch targets: 44pt/px minimum; primary capture actions can be larger.
+- Every mobile-web touchable has a visible resting container; do not rely on hover/cursor.
+- Expandable cards beat sheets/modals when comparison and context retention matter.
+- Design tokens cover colors, radius, elevation, and typography; raw numbers are exceptions.
+- Haptics, button spring physics, and elevation communicate action feedback on native platforms.
+- Liquid Glass belongs on navigation-layer controls only, availability-gated for iOS 26+, not stacked on content cards.
+
+Good fit:
+- Native iOS/macOS companion apps, mobile web tools, timer/voice/drill/session surfaces.
+
+Reject when:
+- The app is desktop-primary and comparison density is the core job.
+- Touch affordance choices would add visual noise to a pointer-first surface.
+
+Recent refs:
+- `interface-built-right/mobile-ui/patterns/expandable-card-pattern.md`
+- `interface-built-right/mobile-ui/patterns/design-token-architecture.md`
+- `interface-built-right/mobile-ui/patterns/liquid-glass-ios26.md`
+- `interface-built-right/mobile-ui/lessons/mobile-web-action-affordance.md`
+- `interface-built-right/mobile-ui/lessons/home-screen-simplification.md`
+
+### 10. AI Artifact Canvas
+
+Use when the user is generating or editing a durable artifact, not just receiving a chat answer.
+
+Structure:
+- Split input/control lane from artifact canvas.
+- Artifact gets stable identity, autosave, status, and version/undo affordance.
+- Regeneration is scoped per section/block when possible.
+- Loading states preserve layout and show phase, not generic spinners.
+- Source/citation/provenance spine stays visible when claims matter.
+
+Good fit:
+- Document generation, research briefs, reports, code/spec generation, design drafts.
+
+Reject when:
+- Output is disposable or single-turn.
+- The product has no artifact lifecycle.
+
+Recent refs:
+- UI-guidance memory family: AI-generation UX additions, source-grounded trust, semantic zoom.
+
+## Cross-Cutting Rules
+
+- Typography and text hierarchy come before surface treatment.
+- Color tokens come before gradients, shadows, texture, or glass.
+- Left-border accents are useful categorical structure, but not mandatory on every product.
+- Status should not be a decorative pill by default; use text, weight, and placement unless a platform/system component requires a badge.
+- Charts require a confidence gate: at least 3 comparable points, trustworthy source, and a pattern/comparison/trend that text alone would not communicate as well.
+- Motion is final polish and must respect reduced-motion settings.
+- Empty, loading, error, disabled, success, permission, and overflow states are part of the structure, not afterthoughts.
+
+## Long-Term Memory Boundary
+
+This file is the short-horizon runtime reference. Durable cross-project lessons, rating history, and changes over time live in `build-loop-memory`, especially decisions under `decisions/build-loop/`. Update build-loop-memory when a new structure is repeatedly used, explicitly selected/rejected, or materially changes build-loop's design-selection policy.

package/plugin-artifacts/codex/references/research-trigger-policy.md

@@ -0,0 +1,140 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Research Trigger Policy
+
+Build-loop uses Research deliberately when a task depends on current,
+external, novel, reusable, or decision-grade information. The classifier of
+record is:
+
+```bash
+python3 scripts/research_trigger.py \
+  --workdir "$PWD" \
+  --task "<goal text>" \
+  --effort "<XS|S|M|L|XL>" \
+  --cache-into-state \
+  --json
+```
+
+The output is written to `.build-loop/state.json.researchGate` when
+`--cache-into-state` is passed.
+
+## When It Fires
+
+Run the classifier during Phase 1 Assess, after memory load and before the
+plan is accepted. Research is required when the task includes any of these
+signals:
+
+- Explicit research language: research, investigate, evaluate, compare, latest,
+  current, look up, should I, recommendation.
+- A new API, provider, package, model, framework, standard, deployment target,
+  database, webhook, auth provider, or external service.
+- Current external claims: versions, pricing, release notes, deprecations,
+  laws/regulations/standards, official-doc behavior.
+- Architecture boundary decisions where prior art matters: persistence,
+  protocol, schema, deployment, security, memory/retrieval, Rally, plugin/hook,
+  or cross-layer behavior.
+- Reusable findings that should become a packet in `.build-loop/research/` or
+  durable memory.
+
+No trigger means no Research plugin run by default. A large T-shirt size alone
+does not make a local mechanical edit research-worthy.
+
+## Source tiering & claim verification
+
+When a packet makes external claims, the host LLM tiers its sources and grades
+corroboration before stating anything as fact — self-contained, no external
+tool required. The rubric lives with packet generation in
+`skills/research/SKILL.md` § Confidence: tier each source T1–T4, classify each
+claim's corroboration (✅ ≥2 independent T1/T2 · ⚠️ one T1/T2 or T3/T4-only ·
+❓ single/T4/inferred), and never let a claim's confidence exceed its
+corroboration. High-risk and `max_accuracy` packets decompose claims into
+atomic facts and verify each before stating it. This is the cite-or-block rule
+below applied claim-by-claim.
+
+## Depth Rules
+
+The Research plugin's own depth classifier remains authoritative when
+available. `research_trigger.py` is the deterministic lower-bound and state
+contract for the orchestrator.
+
+| Effort | Default if a trigger fires | Memory recall depth |
+|---|---|---|
+| `XS` | `light` | compact |
+| `S` | `light`, or `standard` for current/external work | focused |
+| `M` | `standard` | standard |
+| `L` | `standard`; `deep` for architecture/decision-grade work | deep |
+| `XL` | `standard`; `deep` for architecture/decision-grade work | deep |
+
+Risk and currentness override effort. Security, auth, privacy, payment,
+billing, compliance, legal, medical, finance, production, and deep/thorough
+user wording escalate to `deep` unless the work is explicitly scoped to a
+local mechanical check.
+
+Depth maps to build-loop research modes:
+
+| Depth | Research mode | Expected output |
+|---|---|---|
+| `light` | `quick` | Local/source-of-truth scan; 0-2 sources; persist only if reusable |
+| `standard` | `balanced` | Local plus official docs/web as needed; 2-5 sources; packet path required |
+| `deep` | `max_accuracy` | Decision-grade multi-source work; 4-10 sources; persist by default |
+
+## Enforcement
+
+If `researchGate.blocks_final_claims == true` or
+`researchGate.requires_citations_or_unavailable_note == true`, the final report
+must not state current/external/API/package claims as facts until one of these
+is true:
+
+- The report cites the research packet and the packet cites source paths/URLs.
+- The report says the current/external evidence was unavailable and labels the
+  claim as unverified.
+- The claim is removed from the final report.
+
+If `researchGate.packet_path` is non-null, Phase 2 records it in the plan under
+`## Research Context`, and Phase 4-G cites whether it was created, reused, or
+explicitly skipped with rationale.
+
+## Reference Capture (default-on corpus)
+
+Whenever build-loop fetches external information **in any phase or mode** —
+WebSearch, WebFetch, Context7, api-registry, or an official-docs read — and that
+information **informs a decision in the run**, capture the EXTRACTED findings as a
+dated reference file. This is not gated to research-run mode; it fires in normal
+build/fix/refactor runs the moment a web/doc fetch feeds a decision.
+
+Capture is routed through the canonical memory writer, never an ad-hoc Write:
+
+```bash
+python3 scripts/reference_capture.py capture \
+  --workdir "$PWD" --run-id "$RUN_ID" \
+  --topic "<short topic>" \
+  --findings "<distilled findings — not raw HTML>" \
+  --source "<url>|<T1|T2|T3|T4>" \
+  --decision "<what this informed>" --json
+```
+
+This writes `<YYYY-MM-DD>-reference-<slug>.md` into the central store's
+project `research` lane with `retrieved_at`, a per-content-class `refresh_after`
+horizon (api-docs/pricing age in days; ecosystem surveys hold for a quarter;
+specs for half a year), `content_class`, `source_urls` (each tier-tagged), and
+`informed_decision`. The store stays uncommitted by default — the corpus grows
+without touching the consumer repo's git.
+
+**When to capture (do, not ask):**
+
+- A `researchGate.research_required == true` run that actually consulted an
+  external source → capture each distinct finding that fed a decision.
+- Any phase that ran WebSearch/WebFetch/Context7/api-registry and used the result
+  (method signature, pricing, version/release fact, library syntax, model ID).
+
+**Freshness on read:** `context_bootstrap.py` scans the reference lane at Phase 1
+and flags any reference past its horizon as `stale-needs-refresh` in the agent
+brief (`packet.reference_freshness`). This is advisory — it routes to the run
+report/notes, never an `AskUserQuestion` and never a block. A stale reference is
+a signal to re-fetch when the topic is back in scope, not a gate.
+
+**Anti-dormancy:** capture is a default behavior, not a dormant feature. The
+activation test (`scripts/reference_capture/test_reference_capture.py` +
+`scripts/test_context_bootstrap.py::ReferenceFreshnessTests`) proves the default
+path writes a dated reference with the required fields and that the read path
+flags a backdated one as stale.

package/plugin-artifacts/codex/references/runtime-smoke-triggers.md

@@ -0,0 +1,42 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Runtime Smoke Triggers
+
+## What triggers a runtime smoke and why
+
+A runtime smoke test fires when a build changes a file that is directly responsible for rendering a user-facing route, handling an API request, or booting a server. The test catches the class of failure that static analysis misses: a component that imports cleanly but throws at mount time, a page that returns HTTP 200 with an Application Error body, or a dev-server that refuses to start after a middleware change. It is placed **after** code-based graders (type-check, lint, unit tests) and **before** LLM judges, so it acts as a cheap binary gate on the most common live-render failure mode.
+
+## Trigger patterns
+
+| Pattern | Match | Reason |
+|---|---|---|
+| `app/**/page.{tsx,jsx,ts,js}` | App Router page | Renders to user — verify mount |
+| `app/**/route.{ts,js}` | App Router API handler | Verify handler responds |
+| `pages/**/*.{tsx,jsx,ts,js}` | Pages Router page | Same as App Router page |
+| `app/**/middleware.{ts,js}` and `middleware.{ts,js}` | Routing middleware | Edge runtime; verify no middleware crash |
+| `**/server.{ts,js}` | Custom Express/Fastify/Node server entry | Verify boot |
+| `**/sse-*.{ts,js}` and any file containing `EventSource` or `text/event-stream` | SSE producer/consumer | Verify event taxonomy parses |
+| `app/**/layout.{tsx,jsx,ts,js}` | Layout component | Affects all child routes — verify hydration |
+| Files containing `'use client'` directive on line 1 | Client component | Verify hydration |
+
+**Note on content-based patterns**: the `'use client'` and `EventSource`/`text/event-stream` patterns require reading file contents, not just matching paths. The current implementation in `scripts/runtime_smoke.py` handles path-based patterns only; content-based detection is deferred to the adapter layer or a future enhancement.
+
+## Future adapter slots
+
+| Adapter | Status | Triggered by | Maintainer notes |
+|---|---|---|---|
+| `nextjs` | shipped | App/Pages Router files, root layout, root middleware | `scripts/runtime_smoke_adapters/nextjs.py` |
+| `sse_consumer` | **shipped 2026-05-09** | `state.json.triggers.runtimeServer == true` AND `runtimeServerInfo.sse_route` non-null AND diff touches `server_module` / `embedded_ui_module` | `scripts/runtime_smoke_adapters/sse_consumer.py`. Implements the 5-step procedure (restart → wait → curl 5s → parse handlers → fail on missing arm). Closes silent-server / ignored-client bug class observed in example-app 2026-05-08. Stack-agnostic — uses `runtimeServerInfo.start_command` if present, else `uv run <package> --serve --port` from pyproject, else `python3 -m <module>`. |
+| `fastapi` | TODO | `app/main.py` with `FastAPI()` import; route decorators (`@app.get`, etc.) | Skip cleanly when uvicorn unavailable; return `status: skipped, reason: uvicorn_not_installed` |
+| `express` | TODO | `package.json` has `express`; `**/server.{ts,js}` pattern | Detect port from server source or default to 3000; verify `/` returns non-5xx |
+
+## When to add an adapter
+
+An adapter is worth shipping when all of the following hold:
+
+1. The project stack hits a runtime-smoke trigger at least 3 times across build history (i.e., the gate would have fired repeatedly for this stack).
+2. The adapter can detect the live-render failure class that static analysis misses for that stack.
+3. A clean skip path exists for environments where the server tooling is unavailable (no hard failure on missing binaries).
+4. The user explicitly requests coverage for this stack, OR the build history shows a repeated "tests passed, page broken" failure pattern for it.
+
+A new adapter should return `status: skipped` with a descriptive `reason` when its required runtime is missing — it must never return `status: fail` solely because the adapter's own tooling is absent.