productfoo 0.0.0-stage → 1.0.1

package/skills/review-loop/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: review-loop
+description: "Use when invoking /review-loop or when the user wants to evaluate, grade, audit, or sanity-check a single loop spec, loop contract, loops.yaml entry, routine, or a plainly-described AI loop against the 'a good loop ends with proof' bar — does it have a checkable goal, a visible check, a stop condition, and a proof-bearing handoff someone could trust on a second case."
+---
+
+# Skill: Review Loop
+
+Evaluate one loop spec against the quality bar for delegated, repeated work: **a good loop ends with proof.**
+
+A loop is a standard that runs — a goal the work must reach, a check that measures progress, revision that uses the check to choose the next move, and a stop condition that bounds the work and forces a handoff. This skill judges whether a given loop actually clears that bar, or whether it is "automation theater" that returns output while pushing the hard review back onto a human.
+
+This is the **judgment** layer, not the schema layer. productfoo already ships a structural validator — `foo loop check <packet-dir>` enforces the `loops.yaml` contract shape and the B4 budget handshake. `review-loop` is complementary: it asks whether the *content* of the loop is strong enough to trust, not just whether the fields are present. Run the structural check first when the loop is a `loops.yaml` contract, then run this for quality.
+
+## Usage
+
+```
+/review-loop <loop-source> [--fix] [--json]
+```
+
+`<loop-source>` may be:
+
+- a packet dir containing `loops.yaml` (evaluate each loop, or one via `--loop <id>`)
+- a path to a `loops.yaml` or a single loop spec file
+- a prose loop: a slash-command loop, a `/loop` recurring task, a scheduled routine, or a plainly-described "keep doing X until Y" instruction
+- a pasted loop template from a public loop library or registry
+
+Examples:
+
+- `/review-loop specs/portable-routines-v0` — grade the loop contracts in a packet
+- `/review-loop specs/adaptive-spec-packet-v0 --loop L-001` — grade one loop
+- `/review-loop "keep re-running the tests and fixing failures until they pass"` — grade a prose loop
+- `/review-loop ./my-ticket-to-pr-loop.md` — grade a library loop template
+
+If no loop source is given, ask for the smallest thing that describes the loop: a `loops.yaml`, a file path, or a short description of the goal, the check, and when it stops. Do not invent the loop.
+
+Do not edit the loop unless the user passes `--fix` or explicitly asks. By default this skill returns a scorecard, observable checks, and a next action.
+
+## Core Rule
+
+**An evaluation is not done until it produces observable checks and a trust verdict, not opinions.**
+
+If the review cannot name what evidence the loop must return, which check must stay visible, or what would make its handoff untrustworthy, it has not finished. Every finding should convert into something a later run can be judged against — the same discipline the loop itself is supposed to have.
+
+## What A Good Loop Has (the bar)
+
+Map the loop onto these pieces before scoring. For a `loops.yaml` contract the field names are shown; for a prose loop, infer the same pieces from the description.
+
+| Piece | Question it answers | `loops.yaml` field |
+|-------|--------------------|--------------------|
+| Goal + standard | Where must the work land? | `goal` |
+| Check / evaluator | How is progress measured? | `verify.check`, `verify.method` |
+| Revision rule | Does the latest result choose the next move? | `choose.criteria` (uses check output) |
+| Stop conditions | When does it stop and hand back? | `stop.*`, `lifecycle.terminal_states` |
+| Proof + record | What evidence rides with the handoff? | `record.artifact`, `record.required_fields` |
+| Boundaries | What may it never do unattended? | `act.forbidden` |
+| Escalation | When must it ask a human? | `ask_user_when` |
+| Reusability | Could someone run it on a second case? | `refs`, `observe.sources`, `act.allowed`, `adapters.runtimes` |
+
+## The Practical Test
+
+Score the loop on the six questions from the standard. For each: give a verdict, cite the specific evidence in the loop (or note its absence), and — this is the point — name the failure it causes downstream when the answer is weak.
+
+Use the foo status-glyph vocabulary for the per-axis verdict on a human terminal (always pair the glyph with its word): **✅ proven** (clear, checkable, present) · **🟡 claimed** (present but weak or unverifiable) · **🚧 blocked / missing** (absent — the loop cannot clear the bar here). Never emit glyphs in `--json`.
+
+### 1. Can you tell what it is trying to achieve?
+
+The goal must name a specific target *and* a standard the loop keeps applying.
+
+- ✅ proven: "Reduce the failing test count to zero." "Produce a reviewer-ready PR." "Extract a reusable skill that works on a second case."
+- 🟡 claimed: "Improve the code." "Make it better." "Handle the tickets." — loose goals create wandering.
+- Downstream failure of a vague goal: the loop drifts and never converges; token spend climbs because there is no target to reach.
+
+### 2. Is the check visible?
+
+There must be an inspectable evaluator, and its form must fit the work.
+
+- Code loops: tests, builds, logs, diffs, benchmarks.
+- Research loops: source coverage, citation quality, confidence thresholds, missing-evidence notes.
+- Writing loops: style rules, reader questions, repetition scans, weak-claim checks.
+- Product loops: customer evidence, risk reviews, success criteria, decision quality.
+- ✅ proven: the check is named, runnable, and someone else could apply it.
+- 🟡 claimed: "the agent reviews the output" — a check the human still has to redo.
+- Downstream failure of a weak check: the hardest part of the work gets pushed back to the person receiving the output.
+
+### 3. Does the latest result decide the next attempt?
+
+This is the property that makes it a *loop* and not a checklist or a one-pass workflow. The result of the check must change what happens next.
+
+- ✅ proven: the revision rule reads the check output and picks the next move (e.g. `choose.criteria: highest-risk failing check`).
+- 🚧 missing: the "loop" just repeats the same action on a schedule and never reacts to its own last result — that is a cron, not a loop.
+- Downstream failure: repeated attempts that do not shrink the gap; motion mistaken for progress.
+
+### 4. Can you tell when the loop should stop?
+
+Stop conditions must be visible and must force a handoff — including the non-success exits.
+
+- ✅ proven: distinct terminal states for success, clean no-op, blocked/approval-needed, exhausted (no progress after N passes), stagnated. productfoo's contract enumerates these in `stop.*` and `lifecycle.terminal_states`.
+- 🟡 claimed: "stop when it's done" with no definition of done or of the give-up cases.
+- Downstream failure of fuzzy stops: wasted attempts and climbing token spend when the gap never shrinks; no clean point to hand back.
+
+### 5. Does the handoff include proof?
+
+The final handoff must let a reviewer understand it in ~2 minutes. Proof can be simple: tests passed, the issue was reproduced and fixed, sources support the claim, a second case worked, the benchmark improved, screenshots show the change.
+
+Check that the record answers the reviewer's real questions: **What changed in the latest attempt? Which source supports this claim? Did the check pass? Which risk remains? Where should I review first? How much can I trust?**
+
+- ✅ proven: the record/artifact carries the check result and the evidence behind it (productfoo: `record.required_fields` includes `verification_result`, `observed_sources`, `action_taken`).
+- 🟡 claimed: the loop returns an artifact but no evidence — confidence barely moves; the reviewer must reconstruct the reasoning. This is the automation-theater tell.
+- Downstream failure: the loop shifts uncertainty to the human instead of reducing it.
+
+### 6. Could someone else use it on a second case?
+
+A reusable loop defines its goal, inputs, context, tools, preserved state, check, proof, stop conditions, escalation rules, boundaries, handoff, and failure modes — and ideally shows second-case evidence that the method stands on its own.
+
+- ✅ proven: inputs and boundaries are explicit; the loop is runtime-portable (productfoo: `adapters.runtimes`) and has been shown to work on a second case.
+- 🟡 claimed: assumptions are trapped inside one prompt or one repo; "trust from a clever name" with no template behind it.
+- Downstream failure: the loop is dead knowledge — the result was saved but the method cannot be re-run.
+
+## Boundary And Autonomy Check (productfoo B4)
+
+For any loop that acts, not just observes, additionally check the approval surface — this is where productfoo's autonomy boundary meets the proof bar:
+
+- **Boundaries present** (`act.forbidden`): the loop names what it must never do unattended — edit canonical files, import raw private sources, take irreversible/outbound/financial actions.
+- **Escalation present** (`ask_user_when`): the loop hands back when product meaning changes, a source boundary changes, or a destructive/production/outbound action would be enabled.
+- **Budget agreed** (B4): defer to `foo loop check` / `foo loop estimate` for the budget handshake; note if an acting loop has no agreed budget, since an unbudgeted loop is a malformed contract.
+
+If an acting loop can reach an irreversible or outbound action with no human gate, that is a blocking finding regardless of how good its check is — surface it first.
+
+## Turn Findings Into Evals
+
+For each weak axis, emit at least one **observable check** the next version of the loop should be judged against — mirroring how a good loop turns repeated corrections into checks. Examples:
+
+- Goal eval: the loop's target is stated as a measurable end state, not a direction.
+- Check-visibility eval: the evaluator is runnable by someone other than the author and returns a pass/fail plus evidence.
+- Reactivity eval: given a failing check, the next attempt differs from the last in a way the check output explains.
+- Stop eval: a run that makes no progress for N passes exits via `exhausted`/`stagnated`, not indefinitely.
+- Proof eval: the handoff answers the six reviewer questions without the reviewer opening the source.
+- Second-case eval: the loop produces a trustworthy handoff on a second, independent input.
+
+## Output Format
+
+Keep it short enough to act on immediately.
+
+```text
+Loop: <id or one-line description>
+What it is trying to become: <goal in one sentence, or "unclear — see axis 1">
+
+Practical Test
+1. Checkable goal      ✅/🟡/🚧  — <evidence or gap>  → <downstream failure if weak>
+2. Visible check       ✅/🟡/🚧  — ...
+3. Latest result drives next  ✅/🟡/🚧  — ...
+4. Bounded stop        ✅/🟡/🚧  — ...
+5. Proof in handoff    ✅/🟡/🚧  — ...
+6. Second-case reuse   ✅/🟡/🚧  — ...
+
+Boundary & autonomy (acting loops): <ok / gap / BLOCKING gap>
+
+Verdict: <Ready to delegate | Not yet — pushes review burden to the human | Blocked on a safety gap>
+
+Weakest link: <the one axis that most limits trust>
+
+Candidate evals (add these to the loop):
+- ...
+
+Recommended next step: <recommendation>
+Then, if the user wants options:
+  1. <recommended option>  (recommended)
+  2. <option>
+  3. <option>
+```
+
+Lead the decision with a recommendation, then number the options so the user can answer with a single digit. Keep belief, evidence, and dissent visible — do not reduce the verdict to a bare menu.
+
+## With `--fix`
+
+Only when the user asks. Safe, in-place improvements to a `loops.yaml` loop:
+
+- Tighten a vague `goal` into a checkable target + standard (propose wording; confirm before writing).
+- Add missing `stop.*` terminal states (`exhausted`, `stagnated`, `clean_no_op`) and their conditions.
+- Add missing `record.required_fields` so the handoff carries `verification_result` and `observed_sources`.
+- Add `ask_user_when` escalation entries for irreversible/outbound actions.
+
+Never widen `act.allowed` to enable a riskier action as a "fix." Never raise a budget or weaken a boundary to make a loop pass. Changing what a loop is *allowed to do* is a product decision — surface it, do not auto-apply. After any write to a packet loop, re-run `foo loop check <packet-dir>` and, for packet-tied changes, `foo asp validate <packet-dir>`.
+
+## Integration With Other Skills And CLI
+
+- `foo loop check <packet-dir>` — structural + budget (B4) validation. Run first for `loops.yaml` loops; `review-loop` adds the quality judgment on top.
+- `foo loop status <packet-dir>` — renders the loop's current state, evidence, and approval boundary.
+- `foo loop estimate <packet-dir> --agree` — the budget handshake for an acting loop.
+- `loop-library-audit` — evaluate a whole loop library or registry; it delegates per-loop grading to this skill.
+- `foo-roast` — when the loop is embedded in a spec/prototype that also needs product-shape cuts.
+
+## Error Handling
+
+- If no loop source is available, ask for the smallest description: goal, check, and stop condition — or a `loops.yaml` path. Do not fabricate the loop.
+- If the source is a `loops.yaml` that fails `foo loop check` (schema or budget), report that structural failure first; a malformed contract cannot be meaningfully graded for quality until it parses.
+- If the loop description is too vague to locate a check or a stop condition, say so plainly and treat those axes as 🚧 missing rather than guessing a passing grade.
+- If the loop references private or sensitive source material, do not copy raw material into the review; evaluate only the loop's structure and boundaries.
+- If a claim about what the loop does depends on running it, label it an assumption or inspect the referenced sources before scoring.
+- If the user asks to change what an acting loop is permitted to do, route that decision back to the human (and to `interview-me` / `foo spec` when product meaning is at stake) rather than editing boundaries silently.

package/skills/review-spec/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: review-spec
+description: "Use when one productfoo spec packet needs a focused quality, evidence, scope, risk, or implementation-readiness review."
+---
+
+# Review Spec
+
+## Usage
+
+Review one packet in depth. Use `check-spec-health` for a portfolio roll-up.
+
+1. Read `spec.md`, `tasks.yaml`, and `events.jsonl`; preserve the append-only ledger.
+2. Run `foo asp validate <packet-dir>` and, when implementation exists, `foo asp
+   reconcile <packet-dir> --git-diff` or the approved source equivalent.
+3. Check intent, requirements, non-goals, decisions, risks, validation, task
+   dependency shape, proof, approval boundaries, and product/code drift.
+4. Inspect repo facts and approved evidence before asking questions. A connector
+   being installed is not source approval; raw private context is not packet evidence.
+5. Report findings by severity, then propose the smallest repair. Apply edits only
+   after the user approves product-meaning changes, and write packet events/tasks
+   through `foo asp event` and `foo asp task`.
+
+The report includes **Sources used**, **Sources omitted**, **Trust status**, and
+**Limits**, plus the decisions that remain the user's alone.
+
+## Error Handling
+
+- If the packet is missing or malformed, name the exact validation failure and
+  next command; do not invent missing intent.
+- If a required source approval or proof is absent, stop the affected assessment
+  with a visible nonzero handoff. Optional omissions must be named in the report.
+- Never hand-edit an old event row, renumber stable IDs, or auto-approve a risky boundary.

package/skills/review-spec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review Spec"
+  short_description: "Use when one spec needs a focused quality review and proposed human-approved repairs."
+  default_prompt: "Use $review-spec for the relevant workflow."

package/skills/rfc-from-research/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: rfc-from-research
+description: "Use when validated research should inform a strategy RFC, product RFC, opportunity memo, or sourced proposal."
+---
+
+# RFC From Research
+
+## Usage
+
+Turn validated evidence into a reviewable proposal without treating proof as an
+automatic product decision.
+
+1. Require at least one productfoo research paper and run `foo research validate
+   <paper.md>`. Continue only when it succeeds with exit 0. A signed receipt
+   binds the exact paper bytes; editing the paper invalidates that proof.
+2. Read the validated paper, packet truth, and approved sanitized evidence.
+   Distinguish source claims, repo facts, hypotheses, dissent, and unknowns.
+3. Draft: context, problem, evidence, proposal, alternatives, tradeoffs,
+   trust/privacy boundaries, rollout, validation, open decisions, and non-goals.
+4. Map every load-bearing recommendation to evidence and preserve counterevidence.
+5. Ask the human to approve promotion into a packet or decision. Validation and
+   sealing never automatically promote research into a requirement.
+
+### Source ledger
+
+- **Sources used** — paper/reference, validation result, approval, and receipt status.
+- **Sources omitted** — every optional evidence lane not used and why.
+- **Trust status** — validated research, approved sanitized evidence, repo fact, or hypothesis.
+- **Limits** — unsupported recommendations and human decisions still open.
+
+Optional omissions appear in the human summary and the RFC artifact. Write the
+RFC only to an explicitly requested local destination.
+
+## Error Handling
+
+- If `foo research validate <paper.md>` fails, a required paper is missing, or
+  source approval is absent, stop with `status: blocked`, name what did not run,
+  give the exact `next action`, and set `exit: nonzero`.
+- If an optional source is unavailable, narrow the proposal and list the
+  omission; never substitute model knowledge.
+- If the evidence does not support a recommendation, write an open decision or
+  a no-go alternative instead of forcing an RFC conclusion.

package/skills/rfc-from-research/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RFC From Research"
+  short_description: "Draft an RFC from research whose exact paper bytes validate."
+  default_prompt: "Use $rfc-from-research to turn this opportunity into a sourced RFC."

package/skills/rfc-from-research/references/rfc-pattern.md

@@ -0,0 +1,69 @@
+# RFC Pattern Reference
+
+Use this reference when the RFC needs strategic synthesis, current-system comparison, or a reusable product recommendation.
+
+## Accepted Shape
+
+The accepted example used this flow:
+
+1. **Sharp title**
+   Name the product concept and strategic tension.
+
+2. **Summary**
+   State the product opportunity in plain English. Include the "not this, this" distinction early.
+
+3. **Research Readout**
+   Group sources by system type, not by a flat source list. Each cluster should end with a short implication for the target product.
+
+   Good clusters:
+   - Horizontal AI assistants
+   - Work-management systems
+   - Product-development systems
+   - Research or academic signal
+   - Contrarian or failure-mode signal
+
+4. **Problem**
+   Describe the concrete local behavior users optimize today and why that can still fail globally.
+
+5. **Proposal**
+   Give the concept a name. Define the smallest useful product unit and the repeated review question it answers.
+
+6. **Approaches Considered**
+   Include a familiar baseline, the recommended wedge, and a higher-upside follow-on. This makes the recommendation feel chosen, not assumed.
+
+7. **Recommended Direction**
+   Make the call directly. Avoid "it depends" unless the RFC is explicitly asking for decision criteria only.
+
+8. **Experience**
+   Show where the concept appears in the product. Keep this as user-visible behavior, not implementation architecture.
+
+9. **MVP Scope**
+   Collapse the idea to one real workflow, one decision, one initiative, one customer segment, or similar.
+
+10. **Non-Goals**
+    Block adjacent-product drift.
+
+11. **Success Criteria**
+    Combine qualitative proof with measurable proxies.
+
+12. **Risks and Open Questions**
+    Surface false certainty, incentives, source completeness, and adoption overhead.
+
+13. **Source Notes**
+    List every source used with a one-line relevance note.
+
+## Moves Worth Preserving
+
+- The research readout was useful because each section said what that category implied for the product.
+- The proposal avoided a generic "AI prioritization" claim and instead named an ergonomic product surface.
+- The RFC used "one real initiative and one decision" to keep the MVP credible.
+- The risks protected against false certainty, political friction, incomplete context, metric gaming, and governance overhead.
+- The source notes made the provenance boundary explicit without turning the RFC into an academic bibliography.
+
+## Red Flags
+
+- If the RFC could apply to any SaaS company, sharpen the product wedge.
+- If the research section can be deleted without changing the proposal, rewrite the research section.
+- If the MVP needs a full platform, shrink it to a single reviewed decision.
+- If the recommendation is hidden in the middle, add a `Recommended Direction` section.
+- If sources are summarized but not linked, add source notes before finishing.