@tyroneross/build-loop 0.30.3 → 0.34.0

package/skills/build-loop/references/memory.md

@@ -8,6 +8,19 @@
 
 Build-loop maintains one canonical long-term memory store at `~/dev/git-folder/build-loop-memory/`. Every build reads canonical indexes/folders; writes go to exactly one lane based on scope.
 
+### Recall-optimized memory discipline
+
+Canonical reference: `build-loop-memory/references/2026-06-11-memory-discipline-prompt.md` (`version: 2026-06-11.1`). Apply it to every non-trivial memory-relevant read or write.
+
+Operational contract:
+
+- Recall first for significant repo work, debugging, planning, and any memory write. Read the store-root `INDEX.md` first, then project context such as `projects/<slug>/context/CONTEXT.md` and generated `CURRENT.*`, plus `constitution.md` / `MEMORY.md` where present. Search `indexes/INDEX.jsonl`, scan `chronology.jsonl`, read the matching lane, and verify any remembered file/flag/API/script still exists before relying on it.
+- Write only durable facts that aid future recall: decisions + rationale, lessons, reusable references, gotchas, experiment results, product opportunities, and durable operational patterns. Do not write restated code, git-derivable facts, transient status, or handoff-only state.
+- Before writing, search `indexes/INDEX.jsonl` for an existing slug/title, update instead of duplicating, then check `indexes/duplicates.jsonl` after indexing. Use title and `description` as the recall hooks.
+- Do not hand-write project decisions. Use `scripts/write_decision/__main__.py`; it writes the decision lane and updates that lane's `INDEX.md` / update ledger. Generated master-index reachability is still incomplete for new `projects/<slug>/decisions/` files, so verify decisions through `memory_facade` or the decision lane until the scanner/map split is reconciled.
+- Current reference gap: `memory_writer.py` has `research` as a project sublane but not `references`; `reference_capture` writes to `projects/<slug>/research/`, while `build-loop-memory/scripts/rebuild_memory_indexes.py` scans `references/` and not `research/`. For generated-index recall today, write `type: reference` content under `projects/<slug>/lessons/references/`, or update both writer and indexer to agree on `references` or `research`.
+- After any memory write, run the relevant host index/check step when mutation is in scope and verify the entry is reachable from the proper recall surface: `INDEX.jsonl` for generated-index lanes, decision lane/index or `memory_facade` for decisions, or the host system's equivalent.
+
 **Cross-project memory**: `build-loop-memory/lessons/` plus the sibling top-level lanes `design/`, `debugging/`, and `product/`
 
 - Applies across every project this user builds.
@@ -87,7 +100,7 @@ last_updated_at: "ISO8601 UTC"
 ---
 ```
 
-### Writer side — use memory_writer.py, never write memory files directly
+### Writer side — use the canonical writer for normal memory writes
 
 **Top-level (cross-project) write** — `--scope top-level` routes to `build-loop-memory/lessons/` (or a sibling lane when `--file <lane>/x.md` is used):
 
@@ -121,7 +134,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/memory_writer.py \
   --body-file /tmp/memory-body.md
 ```
 
-The writer auto-detects `source_repo` from the workdir's git remote, appends a row to the lane-local `INDEX.jsonl`, appends a row to the global update ledger at `indexes/updates.jsonl`, and (on update) preserves `created_at` + `applied_in_repos` so cross-repo validation history survives edits.
+The writer auto-detects `source_repo` from the workdir's git remote, appends a row to the lane-local `INDEX.jsonl`, appends a row to the global update ledger at `indexes/updates.jsonl`, and (on update) preserves `created_at` + `applied_in_repos` so cross-repo validation history survives edits. Direct writes are repair/fallback work only: use them only when no canonical writer exists or the current task is explicitly a memory-system repair, then run the host index/check step and verify reachability.
 
 ### Reader side — surface peer writes via INDEX.jsonl
 
@@ -233,6 +246,8 @@ Run once after this version of build-loop is installed; the migration completes
 
 Every build-loop run appends a single milestone record at **Review-G** via `scripts/append_milestone.py`. Each record captures what shipped and the repo HEAD sha at write time.
 
+The milestone (durable `milestones.jsonl` in build-loop-memory) is **distinct from** `state.json.runs[]`, which Phase 6 Learn scans for pain signals. The orchestrator's Review-G writes both; an **inline run or the closeout** writes neither unless it calls them explicitly. So at run-close, in addition to the milestone, record the run for Learn with `python3 scripts/append_run.py --workdir "$PWD" --run-id <id> --goal "..." --outcome <done|partial|blocked>` (append-only, idempotent on `run_id`; capture `--manual-intervention "<phase>:<note>"` for any step the user had to re-prompt). Without it, inline work never reaches the `runs[] >= 3` Learn threshold. See `references/phase-6-learn.md` §Detect.
+
 JSONL contract (frozen — sibling staleness-check reads this):
 
 ```

package/skills/build-loop/references/phase-1-assess.md

@@ -152,6 +152,19 @@
    returned depth (`light`/`standard`/`deep`) or record why it was unavailable.
    If `blocks_final_claims: true`, final current/external/API claims need
    citations or an explicit unavailable/unverified note.
+
+   **Reference capture (default-on, any phase/mode):** whenever this run fetches
+   external info (WebSearch/WebFetch/Context7/api-registry/official docs) AND uses
+   it in a decision, persist the EXTRACTED findings (not raw HTML) via
+   `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/reference_capture.py" capture --workdir
+   "$PWD" --run-id "<run_id>" --topic "<topic>" --findings "<distilled>" --source
+   "<url>|<T1..T4>" --decision "<what it informed>" --json`. Routes through the
+   canonical memory writer into the project `research` lane with `retrieved_at` +
+   a per-content-class `refresh_after` horizon; the store is uncommitted by
+   default. `context_bootstrap.py` flags references past their horizon as
+   `stale-needs-refresh` in the brief (`packet.reference_freshness`, advisory).
+   Do not ask — capture is a default. Policy: `references/research-trigger-policy.md`
+   §"Reference Capture".
 14a. **Active task surface**: when the user asks what remains, when Phase 1
    surfaces open work, or before queue-continuation decisions, run:
 

package/skills/build-loop/references/phase-2-plan.md

@@ -70,7 +70,7 @@ Readback format (one line, mandatory, before the plan body):
    - Exit 2 → treat as verifier outage; log and proceed with `plan-critic` alone plus a state.json warning.
    - `parallel-decision-record` is a BLOCKER: plans that name independent / parallel-safe multi-chunk work must include `parallel_batch:` or `parallel_skipped_reason:`.
    - Full rule list and contract: `${CLAUDE_PLUGIN_ROOT}/skills/plan-verify/SKILL.md`.
-9. **Dispatch `plan-critic` agent** (non-deterministic checks): pass the plan + the JSON from step 8 so the critic doesn't re-derive deterministic findings. Critic surfaces alternatives-considered, MECE scope, marker adequacy, headline drift. Severity capped at WARN — does not block.
+9. **Dispatch `plan-critic` agent** (non-deterministic checks): pass the plan + the JSON from step 8 so the critic doesn't re-derive deterministic findings. Critic surfaces alternatives-considered, MECE scope, marker adequacy, headline drift. The critic's emitted severity caps at WARN. **Gating is stakes-conditional (decided by the orchestrator, not the critic):** on high-stakes plans (`synthesisDensity > 5`, `triggers.riskSurfaceChange`, `stakes >= medium`, or `dispatch_tier: frontier`) those WARNs are **blocking** — Phase 2 does not finish until each is revised or explicitly overridden; otherwise they are **advisory** (today's behavior). The gate advances on objective signals only, never self-reported confidence. See `references/advisor-dispatch-ladder.md`.
 10. **Emit gaps-readback** using the combined output of steps 8–9. Populate the one-line readback prefix before presenting the plan. Both passes must complete before the plan is shown to the user — never present a plan without the readback line.
 11. **Dispatch `scope-auditor` agent** (Plan→Execute boundary): pass the plan + extracted commit table (with `modifies_api` per commit). The auditor is Opus + read-only; it traces every caller-site of every modified-API symbol via project-wide grep, classifies callers as in-scope / out-of-scope, and emits a `## Caller Audit (Scope Auditor)` JSON section appended to the plan. Verdict `scope_gap_found` requires plan revision (absorb missing callers into the right commit's owned-files) before Phase 3, OR explicit acceptance in `state.json.scopeGapAccepted[]` with rationale. Skip ONLY when the plan has zero `modifies_api` entries (doc-only commits). Prevents the fan-out scope-blindness defect class — see `agents/scope-auditor.md`.
 

package/skills/build-loop/references/phase-4-review.md

@@ -242,6 +242,8 @@ Runs only when all prior sub-steps pass OR when iteration cap is hit. Writes fin
 
 **No-critical/high exit gate (QM v0.13.0 Piece 3, BLOCKING).** Before this final pass may report `pass`, collect every reviewer findings JSON produced this run (independent-auditor + security-reviewer) and run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/review_finding_gate.py --findings-json <each.json> --json`. It normalizes legacy (`major→high`, `minor→medium`, `info→low`; security `CRITICAL|HIGH|MEDIUM|LOW` case-insensitively; ambiguous→`high`) and returns `{pass, blocking_count, ...}`, exit 1 when any `critical`/`high` finding is open (not `closed` + `closure_proof`). **Exit 1 → the final pass is blocked; route the blocking findings to Phase 5 Iterate** (the fixed 5-iteration cap cannot finalize with an open critical/high). Exit 0 → proceed. Medium/low never block here — they route through the ux-queue/followup with explicit disposition; they are never silently skipped.
 
+**Judgment-dispatch gate (BLOCKING on stakes-gated runs).** The advisor/auditor ladders RECORD which rung fired but nothing ENFORCED it, so an inline run (skill-as-methodology, no orchestrator dispatch) silently sat at the inline-Opus floor and the Frontier judgment never happened (observed: agent-rally-point v0.1.2 ran 16 commits with 0 Fable dispatches until the user asked why). Before this final pass may report `pass`, run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/judgment_gate.py --workdir "$PWD" --run-id <this run> --agent-tool-available <true|false> --json`. Pass `--run-id` so stakes/statuses/ledger are scoped to THIS run only (never a stale top-level trigger or a prior run's ledger row — the gate reads stakes from the run record); omit it to default to the latest `runs[]` entry. Pass `--agent-tool-available false` only for a nested orchestrator / no-Agent-tool context. Stakes-conditional (mirrors the ladders): no stakes trigger → `pass`; stakes fired + `auditor_status`/`advisor_status` shows a real Frontier/peer dispatch → `pass`; stakes fired + the inline floor (`fallback:inline-opus` / `not-run:parent-must-dispatch` / unrecorded) with the Agent tool reachable → **exit 1, `fail`**. **Exit 1 → the run is NOT review-complete: dispatch the independent-auditor (and, for a stakes-gated Phase 2, the advisor) to Frontier, then re-run.** Also fails on an `agent-ledger.jsonl` `verify`/`author` action recorded at a non-frontier tier. This closes the inline-substitution hole — the same class as the inline self-audit masquerading as the independent auditor.
+
 Final report sections, in this order:
 
 - `## Done` — every verified pass + every Auto-Resolve `auto` item, with one-line evidence each.
@@ -256,6 +258,16 @@ or explicitly say the evidence was unavailable and the claim is unverified. If
 `packet_path` is non-null, add a compact `research_packet:` evidence item to
 `## Done` or `## Status markers`.
 
+Reference-capture report field (mirrors the researchGate citation contract):
+every run reports one `references captured:` line in `## Done` or `## Status
+markers` — `references captured: N (<files>)` when one or more external fetches
+informed a decision and were captured via the canonical writer, `none — no
+external fetch informed a decision` when no web/doc fetch fed a decision, or
+`skipped: <rationale>` when a fetch informed a decision but capture was
+intentionally not run. This makes the default-on capture trigger
+(`references/research-trigger-policy.md` §"Reference Capture") accountable in the
+run report instead of advisory-only.
+
 Before emitting the final report, write the draft to a temp file and run BOTH linters (orthogonal — structural vs style):
 
 ```bash

package/skills/build-loop/references/phase-6-learn.md

@@ -15,7 +15,7 @@
 Quick flow:
 
 1. **Detect** — dispatch `recurring-pattern-detector` (Haiku). Reads **two signal sources**:
-   - **Signal 1**: `.build-loop/state.json.runs[]` — emits `phase_failure`, `manual_intervention`, and `security_finding` patterns (real pain signals; `diagnostic_repeat` and `file_churn` were removed to prevent skill sprawl).
+   - **Signal 1**: `.build-loop/state.json.runs[]` — emits `phase_failure`, `manual_intervention`, and `security_finding` patterns (real pain signals; `diagnostic_repeat` and `file_churn` were removed to prevent skill sprawl). **`runs[]` is written by the orchestrator's Review-G, so an INLINE run (skill-as-methodology, no orchestrator dispatch) records nothing and is invisible to Learn.** Any run-close path that did not go through Review-G — inline runs, the memory closeout — MUST record the run with `python3 scripts/append_run.py --workdir "$PWD" --run-id <id> --goal "..." --outcome <done|partial|blocked> [--manual-intervention "<phase>:<note>"] [--phase "<id>:<status>"]` (append-only, idempotent on `run_id`). Without it, inline work never accrues toward the `runs[] >= 3` threshold and recurring inline pain (e.g. the user re-prompting for a skipped step) never becomes a `manual_intervention` pattern.
    - **Signal 2**: `.build-loop/proposals/enforce-from-retro/*.md` (the post-push retrospective's enforce-candidates) — emits `enforce_recurrence` patterns when the same normalized candidate signature appears across ≥ 2 distinct run-ids. The orchestrator may cite `python3 scripts/enforce_retro_signals.py --workdir "$PWD" --json` as pre-computed input to the agent. This delivers "anything prompted/needed repeatedly → enforce" **across** sessions, not just within one.
 2. **Filter** — keep only `confidence: high` or `count >= 4`; manual interventions at lower threshold. Dedupe against existing active/experimental skill names. Cap 2 artifacts per scan.
 3. **Draft** — for each kept pattern, dispatch `self-improvement-architect` (Sonnet). Writes to `.build-loop/skills/experimental/<name>/SKILL.md` with an A/B Experiment section including `run_id` and `co_applied_experimental_artifacts[]` schema.

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

@@ -90,8 +90,10 @@ Deep mode digests include an `## Apply plan` section that separates SAFE-to-auto
 
 `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`
+- `com.build-loop.selfreview-light.plist` — daily at 09:00, invokes `scripts/self_review_run.sh light`
+- `com.build-loop.selfreview-deep.plist` — weekly Sunday at 03:00, invokes `scripts/self_review_run.sh deep`
+
+`install` and `uninstall` also unload + remove any jobs still installed under the pre-rename legacy labels (developer-prefixed `*.buildloop.selfreview-*`), so an existing machine transitions to the neutral labels on the next run.
 
 Both jobs write output to `.build-loop/self-review/launchd-{light,deep}.log`.
 

package/skills/build-loop/templates/codex-worker-prompt.md

@@ -4,48 +4,20 @@
 
 You are a Codex worker inside a Build Loop run. You are not alone in the codebase. Do not revert edits made by others; adapt around them and report conflicts.
 
-## Task
+## Static Contract
 
-<one concrete outcome>
-
-## Ownership
-
-Owns:
-- <exact files/directories this worker may edit>
-
-Does not own:
-- <files/directories/responsibilities this worker must not edit>
-
-## Context
-
-- Goal: <goal from .build-loop/goal.md>
-- Intent: <north star/update intent relevant to this task>
-- Current state: <short facts from assessment>
-- Dependencies: <upstream tasks or known constraints>
+This section is intentionally stable across Codex worker prompts. Keep it before task-specific material so repeated worker dispatches share the longest stable prefix.
 
-## Interface Contract
-
-- <function/route/schema/component/CLI/doc contract to preserve or expose>
-
-## Implementation Rules
+### Implementation Rules
 
 - Keep the change scoped to owned files.
 - Prefer the repo's existing patterns over new abstractions.
 - Do not add dependencies unless the lead explicitly assigned that.
 - Surface pre-existing issues separately from task changes.
 - If ownership is unclear, stop and report the conflict instead of broadening scope.
+- Run assigned validation when feasible; if validation is not feasible, explain why and what the lead should run.
 
-## Validation
-
-Run if feasible:
-
-```bash
-<validation command>
-```
-
-If validation is not feasible, explain why and what the lead should run.
-
-## Return Format
+### Return Format
 
 Changed files:
 - <path>: <what changed>
@@ -59,7 +31,7 @@ Integration notes:
 Unresolved risks:
 - <risk or "none known">
 
-## decision_ledger (REQUIRED when plan has synthesis_dimensions)
+### decision_ledger (REQUIRED when plan has synthesis_dimensions)
 
 When the originating plan includes a `synthesis_dimensions:` block, your return envelope MUST include a `decision_ledger` array with one entry per dimension. Each entry documents *why* the chosen value was selected — not just *what* was applied. Empty array `[]` is only valid when the plan has no `synthesis_dimensions` block.
 
@@ -87,3 +59,38 @@ Example (two entries for placement and cta_tier dimensions):
 ```
 
 Full schema: `references/implementer-envelope-schema.md` §"decision_ledger in detail".
+
+## Variable Task Packet
+
+This section changes for each dispatch. Keep it after the static contract.
+
+### Task
+
+<one concrete outcome>
+
+### Ownership
+
+Owns:
+- <exact files/directories this worker may edit>
+
+Does not own:
+- <files/directories/responsibilities this worker must not edit>
+
+### Context
+
+- Goal: <goal from .build-loop/goal.md>
+- Intent: <north star/update intent relevant to this task>
+- Current state: <short facts from assessment>
+- Dependencies: <upstream tasks or known constraints>
+
+### Interface Contract
+
+- <function/route/schema/component/CLI/doc contract to preserve or expose>
+
+### Validation
+
+Run if feasible:
+
+```bash
+<validation command>
+```

package/skills/handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: handoff
-description: "Compose a complete, durable build-loop handoff document from the current run state, and optionally launch a fresh session with it injected. Use when crossing a context boundary (context limit, planned restart, worktree GC). Triggers: 'hand off', 'handoff', 'new session', 'context limit', 'restart', 'fresh session', '/build-loop:handoff'."
+description: "Compose a complete, durable build-loop handoff document from the current run state, and optionally launch a fresh session with it injected. Use when crossing a context boundary (context limit, planned restart, worktree GC). Triggers: 'hand off', 'handoff', 'new session', 'context limit', 'restart', 'fresh session', '/build-loop:compose-handoff'."
 user-invocable: true
 ---
 
@@ -55,7 +55,7 @@ Emits a JSON envelope `{document, sources, errors, ts}` for programmatic use.
 
 ## Usage — `--launch` (fresh session)
 
-The command surface (`/build-loop:handoff --launch`) handles this. The skill provides
+The command surface (`/build-loop:compose-handoff --launch`) handles this. The skill provides
 the doc; the command layer handles host-specific launch.
 
 **What `--launch` does:**
@@ -90,5 +90,5 @@ orchestrator already writes. Tests: `scripts/handoff/test_handoff.py` (13 tests)
 
 The skill provides **structured data + instructions**. The host coding agent's LLM
 interprets and acts on the handoff doc. No vendor-specific API calls. The `--launch`
-CLI path uses the host's own CLI, isolated in `commands/handoff.md`'s conditional
+CLI path uses the host's own CLI, isolated in `commands/compose-handoff.md`'s conditional
 block — the skill logic is identical across Claude Code, Codex, and future hosts.

package/skills/loop-builder/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: loop-builder
+description: Use when the user asks to "create a custom build loop", "build a loop spec", "make a focused loop", "generate a workflow loop", "adapt a framework into a loop", or asks whether a workflow should use skill chaining. Generates declarative focused-loop specs, presets, validators, and skill-chain plans.
+version: 0.1.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# loop-builder
+
+Create declarative focused-loop specs that reuse build-loop's phase discipline outside pure coding work. The skill turns a preset or framework into a small loop pack: `loop.yaml`, `rubric.md`, report template, validator stub, and explicit skill-chain guidance.
+
+## Core Rule
+
+Keep the runner generic and the loop domain-specific. Do not create a new orchestrator for every workflow. Generate a loop spec that declares inputs, outputs, validators, gates, learn payload, and skill-chain handoffs.
+
+## Workflow
+
+1. **Classify the loop request.**
+   - Use a preset when the user asks for a known loop type: active project evidence, source ingestion, raw data audit, presentation audit, or research synthesis.
+   - Use the generic artifact lifecycle preset when the request is novel but still follows intake -> provenance -> produce -> review -> learn.
+   - Use a framework adaptation when the user provides a method such as Pyramid Principle, PRISMA, ISO 19011, GTD, DMAIC, OKR, or a company-specific workflow.
+
+2. **Define the artifact contract.**
+   - Name accepted inputs.
+   - Name target outputs.
+   - State the validator evidence required before success.
+   - State confirmation gates: external send, sensitive data exposure, money movement, legal assertion, production/customer operation, people-impacting decision, irreversible source-of-truth change.
+
+3. **Plan skill chaining.**
+   - Treat skill chaining as phase routing, not a hidden dependency.
+   - Declare the chain in `skill_chain` with phase names and fallback behavior.
+   - Prefer existing skills for specialized work: `research` for evidence gathering, Pyramid skills for presentation/storyline work, `doc` for Word documents, `build-loop:knowledge` for durable memory, and `plugin-builder` or `skill-builder` only when generating new capabilities.
+   - Every chained skill must hand back a concrete artifact path or decision record.
+
+4. **Generate the loop pack.**
+   - Run:
+     ```bash
+     python3 skills/loop-builder/scripts/loop_builder.py create <loop-id> --preset <preset-name>
+     ```
+   - Default output is `.build-loop/loops/<loop-id>/`.
+   - Use `--output <dir>` for a WorkWiki, ObsidianVault, or non-code project workspace.
+   - Use `--force` only when replacing an existing generated loop pack intentionally.
+
+5. **Review the generated spec.**
+   - Confirm `loop.yaml` has phases, validators, gates, and `skill_chain`.
+   - Confirm `rubric.md` has pass/fail checks.
+   - Confirm `templates/report.md` matches the output artifact.
+   - Run the generated validator stub:
+     ```bash
+     python3 .build-loop/loops/<loop-id>/validators/validate_loop.py
+     ```
+
+## Skill Chaining Guidance
+
+Use skill chaining when the loop has stable phase boundaries and at least one phase is better handled by an existing specialized skill.
+
+Good candidates:
+
+- Research -> synthesis -> presentation/storyline -> audit -> knowledge promotion.
+- Source ingestion -> raw-data audit -> source card -> retrieval/index check.
+- Presentation audit -> Pyramid critique -> accessibility check -> fix plan.
+- Word doc audit -> document parser -> claim verification -> redline report.
+- Interview synthesis -> quote extraction -> themes -> deck/source-card output.
+
+Avoid chaining when:
+
+- A single deterministic script can do the whole job.
+- Phase outputs are vague or untestable.
+- The chain would make ownership unclear.
+- A specialist skill would produce advice without a file, verdict, or cited evidence trail.
+
+## Presets
+
+List presets:
+
+```bash
+python3 skills/loop-builder/scripts/loop_builder.py list
+```
+
+Create a loop:
+
+```bash
+python3 skills/loop-builder/scripts/loop_builder.py create active-project-evidence --preset active-project-evidence
+```
+
+Inspect a preset:
+
+```bash
+python3 skills/loop-builder/scripts/loop_builder.py inspect presentation-audit
+```
+
+## Additional Resources
+
+- `references/spec-format.md` describes the generated loop schema and skill-chain fields.
+- `scripts/loop_builder.py` is the deterministic generator.
+- `presets/*.yaml` contains YAML-compatible preset definitions.

package/skills/loop-builder/presets/active-project-evidence.yaml

@@ -0,0 +1,97 @@
+{
+  "id": "active-project-evidence",
+  "title": "Active Project Evidence Loop",
+  "summary": "Move live project material from active workspace state into a decision artifact and canonical knowledge.",
+  "inputs": [
+    "active project folder",
+    "live log",
+    "research notes",
+    "source artifacts",
+    "generated outputs",
+    "promotion queue"
+  ],
+  "outputs": [
+    "current-state summary",
+    "evidence map",
+    "decision artifact or sponsor update",
+    "promotion candidates",
+    "retrieval test plan"
+  ],
+  "phases": {
+    "assess": {
+      "goal": "Identify the project question, audience, live state, source roots, and canonical destination.",
+      "required": ["project_goal", "audience", "source_inventory", "current_outputs", "canonical_wiki_target"]
+    },
+    "plan": {
+      "goal": "Sequence source review, artifact production, validation, and promotion.",
+      "required": ["source_priority", "artifact_type", "validator_order", "promotion_rules"]
+    },
+    "produce": {
+      "goal": "Create the current-state synthesis, evidence map, and decision artifact.",
+      "required": ["known_unknown_map", "source_backed_claims", "open_questions"]
+    },
+    "review": {
+      "goal": "Validate claim support, audience fit, source traceability, and promotion readiness.",
+      "required": ["validator_results", "gate_check", "fix_list"]
+    },
+    "learn": {
+      "goal": "Promote stable source pages, reusable assets, and retrieval aliases.",
+      "required": ["promotion_candidates", "retrieval_probes", "reusable_patterns"]
+    }
+  },
+  "validators": [
+    {
+      "id": "source_trace",
+      "pass_condition": "Every material claim cites a source path, slide, row, transcript timestamp, or explicitly marked assumption.",
+      "method": "review"
+    },
+    {
+      "id": "current_state_integrity",
+      "pass_condition": "Knowns, unknowns, contradictions, and next evidence needs are separated.",
+      "method": "review"
+    },
+    {
+      "id": "promotion_readiness",
+      "pass_condition": "Each promoted item has a target wiki layer and evidence-backed reason for promotion.",
+      "method": "review"
+    },
+    {
+      "id": "retrieval_probe",
+      "pass_condition": "At least one future retrieval query is named for each durable output.",
+      "method": "review"
+    }
+  ],
+  "gates": {
+    "confirm": ["external_send", "sensitive_data_exposure", "irreversible_source_change"],
+    "surface": ["people_impacting_decision", "legal_or_compliance_assertion"]
+  },
+  "skill_chain": {
+    "intake": {
+      "primary": ["research"],
+      "optional": ["doc"],
+      "fallback": "Manual source inventory with file paths and confidence labels.",
+      "handoff_artifact": "source_inventory.md"
+    },
+    "produce": {
+      "primary": ["pyramid-principle:pyramid-short-form", "pyramid-principle:pyramid-presentation"],
+      "optional": ["research"],
+      "fallback": "Draft the artifact from the evidence map using answer-first structure.",
+      "handoff_artifact": "decision_artifact.md"
+    },
+    "review": {
+      "primary": ["pyramid-principle:pyramid-audit"],
+      "optional": ["research"],
+      "fallback": "Run binary validators in rubric.md manually.",
+      "handoff_artifact": "review_findings.md"
+    },
+    "learn": {
+      "primary": ["build-loop:knowledge"],
+      "optional": ["research"],
+      "fallback": "Write promotion candidates and retrieval probes into the report.",
+      "handoff_artifact": "promotion_candidates.md"
+    }
+  },
+  "learn": {
+    "store": ["source_quirks", "promotion_candidates", "retrieval_aliases", "reusable_assets", "rubric_failures"]
+  }
+}

package/skills/loop-builder/presets/generic-artifact-loop.yaml

@@ -0,0 +1,95 @@
+{
+  "id": "generic-artifact-loop",
+  "title": "Generic Artifact Lifecycle Loop",
+  "summary": "Turn source material into a validated artifact, then preserve reusable lessons and retrieval handles.",
+  "inputs": [
+    "source material",
+    "artifact goal",
+    "audience",
+    "constraints",
+    "definition of done"
+  ],
+  "outputs": [
+    "artifact contract",
+    "working artifact",
+    "review report",
+    "fix list",
+    "learn payload"
+  ],
+  "phases": {
+    "assess": {
+      "goal": "Define artifact type, source materials, audience, constraints, and done condition.",
+      "required": ["artifact_type", "source_material", "audience", "constraints", "done_condition"]
+    },
+    "plan": {
+      "goal": "Sequence production, validation, confirmation gates, and learn outputs.",
+      "required": ["work_sequence", "validator_order", "gate_check"]
+    },
+    "produce": {
+      "goal": "Create or transform the artifact.",
+      "required": ["working_artifact", "source_trace"]
+    },
+    "review": {
+      "goal": "Run deterministic checks first, then judgment checks.",
+      "required": ["validator_results", "fix_list"]
+    },
+    "learn": {
+      "goal": "Store reusable patterns, templates, failure modes, and retrieval handles.",
+      "required": ["learn_payload", "retrieval_handles"]
+    }
+  },
+  "validators": [
+    {
+      "id": "artifact_contract",
+      "pass_condition": "Inputs, outputs, audience, and done condition are named before production.",
+      "method": "review"
+    },
+    {
+      "id": "source_trace",
+      "pass_condition": "Material claims or transformations trace to source material or marked assumptions.",
+      "method": "review"
+    },
+    {
+      "id": "gate_check",
+      "pass_condition": "External send, sensitive data, money, legal, production, people, and irreversible-change gates are checked.",
+      "method": "review"
+    },
+    {
+      "id": "learn_payload",
+      "pass_condition": "At least one reusable pattern, template, failure mode, or retrieval handle is captured or explicitly marked none.",
+      "method": "review"
+    }
+  ],
+  "gates": {
+    "confirm": ["external_send", "sensitive_data_exposure", "money_movement", "legal_or_compliance_assertion", "production_or_customer_operation", "people_impacting_decision", "irreversible_source_change"]
+  },
+  "skill_chain": {
+    "intake": {
+      "primary": [],
+      "optional": ["research", "doc"],
+      "fallback": "Manual artifact contract and source inventory.",
+      "handoff_artifact": "artifact_contract.md"
+    },
+    "produce": {
+      "primary": [],
+      "optional": ["pyramid-principle:pyramid-short-form", "pyramid-principle:pyramid-presentation"],
+      "fallback": "Produce the artifact directly from the contract.",
+      "handoff_artifact": "working_artifact"
+    },
+    "review": {
+      "primary": [],
+      "optional": ["pyramid-principle:pyramid-audit", "research"],
+      "fallback": "Run rubric.md validators manually.",
+      "handoff_artifact": "review_report.md"
+    },
+    "learn": {
+      "primary": ["build-loop:knowledge"],
+      "optional": [],
+      "fallback": "Write learn payload in report.",
+      "handoff_artifact": "learn_payload.md"
+    }
+  },
+  "learn": {
+    "store": ["templates", "failure_modes", "retrieval_handles", "source_quirks"]
+  }
+}

package/skills/loop-builder/presets/presentation-audit.yaml

@@ -0,0 +1,96 @@
+{
+  "id": "presentation-audit",
+  "title": "Presentation Audit Loop",
+  "summary": "Audit a deck for storyline, evidence, slide-level clarity, accessibility, and prioritized fixes.",
+  "inputs": [
+    "pptx or pdf",
+    "speaker notes",
+    "audience",
+    "meeting goal",
+    "source material"
+  ],
+  "outputs": [
+    "slide inventory",
+    "audit report",
+    "prioritized fix plan",
+    "claim/source map",
+    "reusable deck failure patterns"
+  ],
+  "phases": {
+    "assess": {
+      "goal": "Extract deck inventory and define audience, decision, timebox, and intended outcome.",
+      "required": ["deck_inventory", "audience", "decision_or_goal", "source_material"]
+    },
+    "plan": {
+      "goal": "Choose audit lenses and order deterministic checks before judgment checks.",
+      "required": ["audit_lenses", "slide_reference_scheme", "accessibility_scope"]
+    },
+    "produce": {
+      "goal": "Produce findings with slide references and ranked fixes.",
+      "required": ["slide_findings", "claim_gaps", "fix_priority"]
+    },
+    "review": {
+      "goal": "Check that findings are specific, evidenced, and separated by severity and type.",
+      "required": ["finding_evidence", "severity_ranking", "accessibility_split"]
+    },
+    "learn": {
+      "goal": "Capture recurring deck failure modes and reusable slide patterns.",
+      "required": ["failure_patterns", "template_candidates"]
+    }
+  },
+  "validators": [
+    {
+      "id": "slide_references",
+      "pass_condition": "Every finding cites a slide number, section, or notes location.",
+      "method": "review"
+    },
+    {
+      "id": "claim_support",
+      "pass_condition": "Material claims are mapped to a source or marked as unsupported/assumption.",
+      "method": "review"
+    },
+    {
+      "id": "audience_fit",
+      "pass_condition": "Recommendations are tied to the audience job and meeting decision, not taste alone.",
+      "method": "review"
+    },
+    {
+      "id": "accessibility_split",
+      "pass_condition": "Accessibility findings are separated from storyline/design judgment and labeled partial when automated extraction is limited.",
+      "method": "review"
+    }
+  ],
+  "gates": {
+    "confirm": ["external_send", "sensitive_data_exposure"],
+    "surface": ["legal_or_compliance_assertion", "people_impacting_decision"]
+  },
+  "skill_chain": {
+    "intake": {
+      "primary": [],
+      "optional": ["doc"],
+      "fallback": "Extract slide titles, notes, and visible text with available local tools.",
+      "handoff_artifact": "deck_inventory.md"
+    },
+    "produce": {
+      "primary": ["pyramid-principle:pyramid-presentation"],
+      "optional": ["research"],
+      "fallback": "Apply one-job-per-slide and answer-first storyline checks manually.",
+      "handoff_artifact": "audit_report.md"
+    },
+    "review": {
+      "primary": ["pyramid-principle:pyramid-audit"],
+      "optional": ["research"],
+      "fallback": "Run rubric.md validators against each slide finding.",
+      "handoff_artifact": "audit_verdict.md"
+    },
+    "learn": {
+      "primary": ["build-loop:knowledge"],
+      "optional": [],
+      "fallback": "Record recurring deck failure patterns in the report.",
+      "handoff_artifact": "deck_lessons.md"
+    }
+  },
+  "learn": {
+    "store": ["deck_failure_patterns", "reusable_slide_patterns", "source_quirks", "rubric_failures"]
+  }
+}