mandrel 2.7.0 → 2.9.0

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -10,70 +10,24 @@ description:
 ## Policy Capsule
 
 - Drive the three-phase loop in order: **Understand & Expand → Evaluate & Converge (grill) → Sharpen & Ship**. Never jump straight to Phase 3 output.
-- Phase 1 MUST restate the idea as a "How Might We" statement, ask 3–5 sharpening questions via `AskUserQuestion`, and generate 5–8 variations (not 20+ shallow ones); do not proceed until target user and success criteria are explicit.
+- Phase 1 MUST restate the idea as a "How Might We" statement, ask 3–5 sharpening questions via `AskUserQuestion`, and generate 5–8 variations (never 20+ shallow ones) — each carrying a reason it exists, told as a short story, not a bare bullet. Do not proceed until target user and success criteria are explicit.
 - Phase 2 grill loop poses **one** question at a time, each with a recommended answer + one-line rationale grounded in user input / codebase / first principles; never batch questions and never omit the recommendation.
-- Re-enumerate open branches after every grill answer; stop only when no unresolved decisions remain. Take the off-ramp directly to Phase 3 when the idea is already crisply scoped.
+- Re-enumerate open branches after every grill answer; stop only when no unresolved decisions remain. Take the off-ramp directly to Phase 3 when the idea is already crisply scoped. A branch consciously deferred rather than resolved records its deferral reason.
 - Phase 3 emits a markdown one-pager with the canonical five planning headings exactly: `## Context`, `## Goal`, `## Non-Goals`, `## Scope`, `## Acceptance Criteria` (plus optional `## Open Questions`). No alternate heading text — the `/plan` clarity gate depends on this verbatim.
 - Surface every key assumption inside `## Context` (or `## Scope`); assumptions do not get their own heading. Unresolved decisions MUST NOT carry into the one-pager.
 - The `## Non-Goals` list is mandatory and each entry includes a reason — focus is created by explicit exclusion.
 - Be honest, not supportive: push back on weak ideas with kindness; never function as a yes-machine.
-- Save the one-pager to `docs/ideas/[idea-name].md` **only after** the user explicitly confirms; never write to disk silently.
+- Save the one-pager to `docs/ideas/[idea-name].md` **only after** the user explicitly confirms the direction; never write to disk silently.
 - When invoked inside a codebase, ground variations in real files/patterns via `Glob` / `Grep` / `Read`; do not invent architecture that ignores existing constraints.
 
-Refines raw ideas into sharp, actionable concepts worth building through
-structured divergent and convergent thinking.
-
-## How It Works
-
-1.  **Understand & Expand (Divergent):** Restate the idea, ask sharpening
-    questions, and generate variations.
-2.  **Evaluate & Converge (Grill):** Cluster the resonant directions, then
-    walk each unresolved decision branch — one question at a time, with a
-    recommended answer — until no branches remain.
-3.  **Sharpen & Ship:** Produce a concrete markdown one-pager moving work
-    forward.
-
 ## Activation
 
 Called from [`/plan`](../../../workflows/plan.md) during ideation when the
-operator supplies `--seed "<text>"` (or runs ideation with no seed and
-the host collects one interactively). The skill sharpens freeform intent
-into canonical planning sections that `/plan` then folds into a Story.
-There is no separate Epic Clarity Gate path in v2 — N=1 Story authoring
-with a folded `## Spec` is the lean default.
-
-## Usage
-
-This skill is primarily an interactive dialogue. Invoke it with an idea, and the
-agent will guide you through the process.
-
-```bash
-# Optional: Initialize the ideas directory
-bash /mnt/skills/user/idea-refine/scripts/idea-refine.sh
-```
-
-**Trigger Phrases:**
-
-- "Help me refine this idea"
-- "Ideate on [concept]"
-- "Stress-test my plan"
-- "Grill me on this"
-- "Walk me through the decision tree"
-
-## Output
-
-The final output is a markdown one-pager saved to `docs/ideas/[idea-name].md`
-(after user confirmation), containing the five canonical planning sections:
-
-- Context (problem framing + current state)
-- Goal (desired outcome)
-- Non-Goals (explicit exclusions)
-- Scope (the in-scope MVP and how it tests the core assumption)
-- Acceptance Criteria (how we'll know it worked)
-
-Assumptions and open questions are recorded in the body of the relevant
-section (typically under Context or Scope) rather than carved into their
-own headings — the canonical five drive the `/plan` clarity gate.
+operator supplies `--seed "<text>"` (or runs ideation with no seed and the host
+collects one interactively). The skill sharpens freeform intent into the
+canonical planning sections that `/plan` then folds into a Story. There is no
+separate Epic Clarity Gate path in v2 — N=1 Story authoring with a folded
+`## Spec` is the lean default.
 
 ## Detailed Instructions
 
@@ -88,7 +42,6 @@ actionable concepts worth building.
 - Say no to 1,000 things. Focus beats breadth.
 - Challenge every assumption. "How it's usually done" is not a reason.
 - Show people the future — don't just give them better horses.
-- The parts you can't see should be as beautiful as the parts you can.
 
 ### Process
 
@@ -103,103 +56,75 @@ conversation, not a template.
 1. **Restate the idea** as a crisp "How Might We" problem statement. This forces
    clarity on what's actually being solved.
 
-2. **Ask 3-5 sharpening questions** — no more. Focus on:
-   - Who is this for, specifically?
-   - What does success look like?
-   - What are the real constraints (time, tech, resources)?
-   - What's been tried before?
-   - Why now?
-
-   Use the `AskUserQuestion` tool to gather this input. Do NOT proceed until you
-   understand who this is for and what success looks like.
-
-3. **Generate 5-8 idea variations** using these lenses:
-   - **Inversion:** "What if we did the opposite?"
-   - **Constraint removal:** "What if budget/time/tech weren't factors?"
-   - **Audience shift:** "What if this were for [different user]?"
-   - **Combination:** "What if we merged this with [adjacent idea]?"
-   - **Simplification:** "What's the version that's 10x simpler?"
-   - **10x version:** "What would this look like at massive scale?"
-   - **Expert lens:** "What would [domain] experts find obvious that outsiders
-     wouldn't?"
-
-   Push beyond what the user initially asked for. Create products people don't
-   know they need yet. Pick the lens that fits the idea — don't run every one
-   mechanically.
+2. **Ask 3-5 sharpening questions** — no more — via the `AskUserQuestion` tool.
+   Focus on: who this is for specifically, what success looks like, the real
+   constraints (time, tech, resources), what's been tried, and why now. Do NOT
+   proceed until you understand who this is for and what success looks like.
+
+3. **Generate 5-8 idea variations** using lenses that fit the idea — inversion,
+   constraint removal, audience shift, combination, simplification, 10x
+   version, expert lens. Push beyond what the user initially asked for; each
+   variation should have a reason it exists, not just be a bullet point. Don't
+   run every lens mechanically.
 
 **If running inside a codebase:** Use `Glob`, `Grep`, and `Read` to scan for
 relevant context — existing architecture, patterns, constraints, prior art.
-Ground your variations in what actually exists. Reference specific files and
-patterns when relevant.
+Ground your variations in what actually exists, and reference specific files
+when relevant.
 
 #### Phase 2: Evaluate & Converge (Grill)
 
-After the user reacts to Phase 1 (indicates which ideas resonate, pushes back,
-adds context), shift to convergent mode. The job here is not just to *list*
-open questions — it is to **resolve** them, one at a time, before anything
-lands in the Phase 3 one-pager.
+After the user reacts to Phase 1, shift to convergent mode. The job here is not
+just to *list* open questions — it is to **resolve** them, one at a time,
+before anything lands in the Phase 3 one-pager.
 
-> **Off-ramp.** Before starting the grill loop, restate the chosen direction
-> in one sentence and check whether any decision branches remain unresolved.
-> If the idea is already crisply scoped — target user clear, MVP boundary
-> obvious, no architectural forks, no hidden assumptions — skip directly to
-> Phase 3. Don't grill trivial ideas for the sake of process.
+> **Off-ramp.** Before starting the grill loop, restate the chosen direction in
+> one sentence and check whether any decision branches remain unresolved. If the
+> idea is already crisply scoped — target user clear, MVP boundary obvious, no
+> architectural forks, no hidden assumptions — skip directly to Phase 3. Don't
+> grill trivial ideas for the sake of process.
 
-1. **Cluster** the ideas that resonated into 2-3 distinct directions. Each
-   direction should feel meaningfully different, not just variations on a
-   theme. Get the user's pick (or a tentative lean) before enumerating
-   branches — the grill loop runs against the *chosen* direction, not the
-   full set.
+1. **Cluster** the ideas that resonated into 2-3 distinct directions. Get the
+   user's pick (or a tentative lean) before enumerating branches — the grill
+   loop runs against the *chosen* direction, not the full set.
 
 2. **Enumerate open branches.** List every unresolved decision the chosen
-   direction depends on. Use the stress-test rubric and the assumption
-   surfaces below as your source material:
-
-   - **User value branches.** Who benefits and how much? Painkiller or
-     vitamin? Which segment first?
-   - **Feasibility branches.** Technical/resource cost. Hardest part. Build
-     vs. buy. Sequencing.
-   - **Differentiation branches.** What makes this genuinely different?
-     Why would someone switch?
-   - **Hidden assumptions.** What you're betting is true (but haven't
-     validated). What could kill this. What you're choosing to ignore (and
-     why that's okay for now).
-
-   Read `refinement-criteria.md` in this skill directory for the full
-   evaluation rubric. Treat each unresolved item as a branch to grill on.
-   If the list is empty after enumeration, take the off-ramp.
+   direction depends on: user-value branches (who benefits, painkiller vs.
+   vitamin), feasibility branches (cost, hardest part, build vs. buy,
+   sequencing), differentiation branches (why switch), and hidden assumptions
+   (what you're betting is true, what could kill this, what you're ignoring and
+   why that's okay for now). Read `refinement-criteria.md` in this skill
+   directory for the full evaluation rubric. If the list is empty after
+   enumeration, take the off-ramp.
 
 3. **Interrogate sequentially.** For each branch, in priority order
    (highest-leverage / most blocking first):
 
    - Pose **one** question at a time. Never batch.
-   - State your **recommended answer** with a one-line rationale grounded
-     in what the user has already told you, the codebase if you're inside
-     one, or first-principles reasoning. The recommendation is a forcing
-     function — accepting it should be the easy path; the user pushes back
-     only when they actually disagree.
-   - Use the `AskUserQuestion` tool so the recommendation surfaces as the
-     first option.
+   - State your **recommended answer** with a one-line rationale grounded in
+     what the user has told you, the codebase if you're inside one, or
+     first-principles reasoning. The recommendation is a forcing function —
+     accepting it should be the easy path; the user pushes back only when they
+     actually disagree.
+   - Use `AskUserQuestion` so the recommendation surfaces as the first option.
    - **Wait for the response** (accept, modify, or reject) before moving on.
      Record the resolution inline so it's available when you author Phase 3.
 
 4. **Re-enumerate after each answer.** A resolved branch may collapse other
-   branches (a "build" decision moots the "buy" follow-ups) or expand the
-   tree (a new constraint surfaces fresh forks). Don't pre-compute the full
-   question list — re-derive it after each answer and pick the next
-   highest-leverage branch.
+   branches (a "build" decision moots the "buy" follow-ups) or expand the tree
+   (a new constraint surfaces fresh forks). Re-derive the list after each
+   answer and pick the next highest-leverage branch.
 
 5. **Stop condition.** Phase 2 ends when no branches remain unresolved.
-   Resolutions feed directly into the Phase 3 one-pager: confirmed bets
-   land in the **Context** section with their validation strategy
-   inline; rejected branches become **Non-Goals** entries with the
-   reason; chosen scope becomes the **Scope** section; verifiable
-   outcomes from the resolved decisions become **Acceptance Criteria**.
+   Resolutions feed the Phase 3 one-pager: confirmed bets land in **Context**
+   with their validation strategy inline; rejected branches become **Non-Goals**
+   entries with the reason; chosen scope becomes the **Scope** section;
+   verifiable outcomes become **Acceptance Criteria**. A branch consciously
+   deferred rather than resolved records the deferral reason.
 
-**Be honest, not supportive.** If an idea is weak, say so with kindness. A
-good ideation partner is not a yes-machine. Push back on complexity,
-question real value, and point out when the emperor has no clothes — and do
-it inside the grill loop, not after the one-pager is already written.
+**Be honest, not supportive.** If an idea is weak, say so with kindness. Push
+back on complexity, question real value, and point out when the emperor has no
+clothes — inside the grill loop, not after the one-pager is written.
 
 > The Phase 2 interrogation discipline is inspired by Matt Pocock's
 > [`grill-me`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md)
@@ -208,43 +133,39 @@ it inside the grill loop, not after the one-pager is already written.
 
 #### Phase 3: Sharpen & Ship
 
-Produce a concrete artifact — a markdown one-pager that moves work forward.
-The five canonical headings below match `.agents/templates/epic-from-idea.md`
-and the `/plan` clarity gate; emit them verbatim so the renderer can
-substitute the body into a `/plan` Story seed without translation.
+Produce a markdown one-pager that moves work forward. The five canonical
+headings below match `.agents/templates/epic-from-idea.md` and the `/plan`
+clarity gate; emit them verbatim so the renderer can substitute the body into a
+`/plan` Story seed without translation.
 
 ```markdown
 # [Idea Name]
 
 ## Context
 
-[One-sentence "How Might We" framing followed by the current-state pain
-or motivation in 1-2 short paragraphs. Surface the key assumptions you
-are betting on inline — assumptions live here, not in a separate
-heading.]
+[One-sentence "How Might We" framing followed by the current-state pain or
+motivation in 1-2 short paragraphs. Surface the key assumptions you are betting
+on inline — assumptions live here, not in a separate heading.]
 
 ## Goal
 
-[The chosen direction and the outcome it produces — 2-3 paragraphs max.
-Frame in terms of the end-state the user reaches, not the implementation
-path.]
+[The chosen direction and the outcome it produces — 2-3 paragraphs max. Frame in
+terms of the end-state the user reaches, not the implementation path.]
 
 ## Non-Goals
 
 - [Thing 1] — [reason]
 - [Thing 2] — [reason]
-- [Thing 3] — [reason]
 
 ## Scope
 
-[The minimum version that tests the core assumption. What's in, what's
-out, and how it sequences into stories.]
+[The minimum version that tests the core assumption. What's in, what's out, and
+how it sequences into stories.]
 
 ## Acceptance Criteria
 
 - [ ] [Verifiable outcome 1 — phrased so a reviewer can check it]
 - [ ] [Verifiable outcome 2]
-- [ ] [Verifiable outcome 3]
 
 ## Open Questions
 
@@ -257,55 +178,8 @@ saying no to good ideas. Make the trade-offs explicit.
 Ask the user if they'd like to save this to `docs/ideas/[idea-name].md` (or a
 location of their choosing). Only save if they confirm.
 
-### Anti-patterns to Avoid
-
-- **Don't generate 20+ ideas.** Quality over quantity. 5-8 well-considered
-  variations beat 20 shallow ones.
-- **Don't be a yes-machine.** Push back on weak ideas with specificity and
-  kindness.
-- **Don't skip "who is this for."** Every good idea starts with a person and
-  their problem.
-- **Don't produce a plan without surfacing assumptions.** Untested assumptions
-  are the #1 killer of good ideas.
-- **Don't over-engineer the process.** Three phases, each doing one thing well.
-  Resist adding steps.
-- **Don't just list ideas — tell a story.** Each variation should have a reason
-  it exists, not just be a bullet point.
-- **Don't ignore the codebase.** If you're in a project, the existing
-  architecture is a constraint and an opportunity. Use it.
-
 ### Tone
 
 Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a
 facilitator reading from a script. Channel the energy of "that's interesting,
-but what if..." -- always pushing one step further without being exhausting.
-
-## Red Flags
-
-- Generating 20+ shallow variations instead of 5-8 considered ones
-- Skipping the "who is this for" question
-- No assumptions surfaced before committing to a direction
-- Yes-machining weak ideas instead of pushing back with specificity
-- Producing a plan without a "Non-Goals" list
-- Ignoring existing codebase constraints when ideating inside a project
-- Jumping straight to Phase 3 output without running Phases 1 and 2
-- Batching grill-loop questions (asking 3+ at once) instead of one at a time
-- Posing grill questions without a recommended answer — the recommendation
-  is the forcing function, not optional
-- Carrying unresolved branches into the Phase 3 one-pager (assumptions are
-  fine; *unresolved decisions* are not)
-
-## Verification
-
-After completing an ideation session:
-
-- [ ] A clear "How Might We" problem statement exists
-- [ ] The target user and success criteria are defined
-- [ ] Multiple directions were explored, not just the first idea
-- [ ] Hidden assumptions are explicitly listed with validation strategies
-- [ ] Every open decision branch was either resolved in the grill loop or
-      consciously deferred (with the deferral reason recorded)
-- [ ] A "Non-Goals" list makes trade-offs explicit
-- [ ] The output is a concrete artifact (markdown one-pager), not just
-      conversation
-- [ ] The user confirmed the final direction before any implementation work
+but what if…" — always pushing one step further without being exhausting.

package/.agents/skills/core/security-and-hardening/SKILL.md

@@ -4,52 +4,36 @@ description:
   Hardens code against vulnerabilities. Use when handling user input,
   authentication, data storage, or external integrations. The non-negotiable
   security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows
-  how to apply them with code patterns, decision trees, and review checklists.
+  how to apply them with process guidance, an audit-triage tree, and a review
+  checklist.
 ---
 
 # Security and Hardening
 
 ## Policy Capsule
 
-- The non-negotiable MUSTs live in `.agents/rules/security-baseline.md`; that rule wins on conflict. Open a PR against the rule rather than working around it in this skill.
-- Validate ALL client input (body, query, headers, path params) at the edge with a strict schema (e.g., Zod). Never trust client-side validation as a security boundary.
-- Parameterize every database query. Never concatenate user input into SQL/NoSQL filters or shell commands.
-- Hash passwords with bcrypt (≥12 rounds), scrypt, or argon2; plaintext storage is forbidden. Session cookies MUST be `httpOnly`, `secure`, and carry an explicit `sameSite`. Never put auth tokens in `localStorage`/`sessionStorage`.
-- Every protected endpoint checks **authorization**, not just authentication; verify resource ownership server-side before any state change and never trust client-asserted roles.
-- Encode HTML output via the framework's auto-escaping; sanitize any unavoidable raw HTML with a vetted library (e.g., DOMPurify). Never feed user data to `eval()`, `Function()`, or `innerHTML`/`dangerouslySetInnerHTML` unsanitized.
-- Exclude sensitive fields (password hashes, reset tokens, internal IDs) from API responses and never expose stack traces or internal error details to clients.
-- Never log PII (emails, full credit cards, session tokens, phone numbers). Destructure safe properties; don't log whole objects.
-- Configure security headers (`Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`, `X-Content-Type-Options`) and restrict CORS to an explicit allowlist — wildcard `*` is forbidden on credentialed endpoints.
-- Pull all secrets from environment variables; never commit `.env`, default API keys, or fallback secrets. `.env.example` (placeholders only) is the committed shape.
-- Surface security-expanding changes (new auth flows, new PII categories, new integrations, CORS / rate-limit changes, file uploads, elevated permissions) under a "Security surface" section in the PR body and on the ticket, label `risk::high`, and link the relevant baseline MUST. This documents the surface — it does not pause execution. `agent::blocked` is only for unrecoverable runtime blockers.
+- The non-negotiable security MUSTs — input validation, authentication, authorization, output/rendering, data-leakage & logging, transport & headers, secrets, dependency hygiene, and forbidden practices — live in [`.agents/rules/security-baseline.md`](../../../rules/security-baseline.md); that rule is the SSOT and wins on conflict. Read it for the **what**; this skill is the **how** and the process.
+- Do **not** restate a baseline MUST here or work around one in code — open a PR against the rule instead. The baseline is inviolable ([`instructions.md` § 1.K](../../../instructions.md)); no skill relaxes it.
+- Surface security-expanding changes — new auth flows, new PII categories, new external integrations, CORS / rate-limit changes, file uploads, elevated permissions — under a "Security surface" section in the PR body and on the ticket, label the change `risk::high`, and link the relevant baseline MUST.
+- Surfacing **documents** the surface; it does **not** pause execution. `agent::blocked` is the only runtime pause label, reserved for unrecoverable blockers — never for "this change is sensitive."
+- For validation-error responses (status code and envelope), cite [`.agents/rules/api-conventions.md`](../../../rules/api-conventions.md) — validation failures return **400** `VALIDATION_ERROR` in the canonical envelope. Do not carry a divergent inline status here.
+- Open a `reference.md` section only when the task actually engages it (index below).
 
-The non-negotiable MUSTs — input validation, authentication, authorization,
-output encoding, transport, headers, secrets, forbidden practices — live in
-[`.agents/rules/security-baseline.md`](../../../rules/security-baseline.md),
-which is the SSOT. This skill shows **how** to apply those MUSTs with code
-patterns and process guidance; read the rule for the **what**. When the rule
-and this skill diverge, the rule wins — open a PR against the rule rather
-than working around it here.
+The MUSTs themselves are the SSOT in
+[`security-baseline.md`](../../../rules/security-baseline.md). When the rule and
+this skill diverge, the rule wins.
 
 ## Long-form reference — read on demand
 
 The capsule above is the contract and the whole always-read surface of this
-skill. The long-form material behind it — patterns, worked examples,
-checklists, and rationalizations — lives in the on-demand sibling
-[`reference.md`](reference.md), matching the split the always-on rules already
+skill. The project-specific process material behind it lives in the on-demand
+sibling [`reference.md`](reference.md), matching the split the always-on rules
 use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
 [`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
 Activating this skill costs the capsule; open a section below only when the
-task actually engages it.
+task engages it.
 
-- [When to Use](reference.md#when-to-use)
 - [Security Surfacing, Not Runtime Pause](reference.md#security-surfacing-not-runtime-pause)
-- [OWASP Top 10 Prevention Patterns](reference.md#owasp-top-10-prevention-patterns)
-- [Input Validation Patterns](reference.md#input-validation-patterns)
+- [Validation-Error Responses](reference.md#validation-error-responses)
 - [Triaging npm audit Results](reference.md#triaging-npm-audit-results)
-- [Rate Limiting](reference.md#rate-limiting)
-- [Secrets Management Layout](reference.md#secrets-management-layout)
 - [Security Review Checklist](reference.md#security-review-checklist)
-- [Common Rationalizations](reference.md#common-rationalizations)
-- [Red Flags](reference.md#red-flags)
-- [Verification](reference.md#verification)