phronesis 1.0.0

package/templates/skills/onboard/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: onboard
+version: 0.2.0
+invocation:
+  explicit:
+    - "onboard me"
+    - "get me started"
+    - "set up my workspace"
+  suggested:
+    - "new Phronesis install"
+    - "first run"
+    - "empty workspace"
+  woven: false
+weight: heavy
+reads:
+  - domains/{active_domain}/AGENTS.md
+  - domains/{active_domain}/USER.md
+  - domains/{active_domain}/MEMORY.md
+  - domains/{active_domain}/raw/inbox/*
+  - domains/{active_domain}/raw/transcripts/*
+  - domains/{active_domain}/compiled/people/*
+  - domains/{active_domain}/compiled/projects/*
+  - domains/{active_domain}/compiled/decisions/*
+  - domains/{active_domain}/compiled/commitments/*
+  - domains/{active_domain}/compiled/insights/*
+  - domains/{active_domain}/compiled/organizations/*
+  - codex/INDEX.md
+  - codex/seed/*/*
+  - codex/personal/*
+writes:
+  - domains/{active_domain}/raw/inbox/*
+  - domains/{active_domain}/raw/transcripts/*
+  - domains/{active_domain}/raw/degraded/*
+  - via_action_types: []
+sub_agents: []
+requires_model_tier: frontier
+prompt_pin: claude-opus-4-8@2026-06-25
+---
+
+# Skill: Onboard
+
+Take a new operator from an empty install to a live Phronesis workspace using their
+own material. This is the V1 local first-run skill: a guided conversation, not a
+hosted wizard, not a bulk migration tool, and not a new CLI verb.
+
+**The bar this workflow is written to clear is `evals/rubric.md` - seven
+orchestration criteria, pass is >=4 on all seven.** Read the rubric before you
+run; it is the acceptance spine.
+
+## What onboard is - and is not
+
+- **Talk-first first run.** The primary path is a short conversation about the
+  operator's world. Folder import and pasted transcripts are supported, but only
+  after the operator confirms what matters.
+- **A playbook over existing primitives.** Onboard guides separate invocations:
+  stage material with `ingest`, hand off to the `compile` skill, review and
+  accept drafts, query the accepted material, then guide deliberate seed adoption.
+  It does not compose skills internally and does not introduce a `via_skills`
+  protocol.
+- **Issues no action types itself.** The frontmatter declares
+  `via_action_types: []`. The mesh is the downstream `compile` invocation's
+  responsibility. Seed adoption is a deliberate operator act through
+  `promote_to_codex`, not a hidden skill write.
+- **Small-batch, confirm-each.** Onboard never silently imports a pile. It
+  discovers, presents, asks what to stage, then stages only the confirmed subset.
+- **Local-first storage, honest model boundary.** Phronesis stores no hosted
+  telemetry or index, but the conversation is processed by the operator's chosen
+  AI surface unless they run a local model. Say that plainly before sensitive
+  material enters the interview.
+
+## Surface precondition
+
+Run only after the operator has opened a wired surface for the install. If
+`phronesis doctor` reports a failing native-hook install, or the operator is on a
+guard-wrapper/manual surface they have not wired yet, stop and point them at
+`docs/surface-setup.md` and `docs/dogfood-runbook.md`. Surface setup is a
+precondition, not one of the onboarding beats.
+
+## Expectation contract - open every beat with it
+
+Before each beat acts, state one line: **Next** - what the run will do now; and
+**Pass-shape** - the concrete evidence the operator should see if it worked (a file,
+path, event, command result, or operator-visible result). Name an honest negative as a
+valid pass-shape when the workspace has nothing to return. Keep it lean; this is
+orientation, not ceremony. It lets the operator grade reality without already knowing
+the product (rubric criterion 7).
+
+## Beat 1 - Welcome and profile
+
+> **Next:** confirm your profile (name, role) and choose how we map your world.
+> **Pass-shape:** your profile fields are confirmed or an explicit gap is named, and you
+> have picked one input mode after the model/storage boundary is stated.
+
+Read `USER.md`, `MEMORY.md`, and the domain `AGENTS.md`. Confirm the operator's
+name and role if present. If either is still a placeholder, ask for the missing
+field and write it only through the existing profile/init path when available; if
+not available, state that the profile remains incomplete and continue.
+
+Tell the operator what will happen in one breath: "We'll map your world from a
+short conversation or transcript, compile the first anchors, query them back, and
+adopt only the seed principles you choose."
+
+> **Checkpoint 1 - Consent and boundary.** Before taking material, confirm the
+> operator understands the model boundary and chooses one input mode: live
+> interview, bring-a-transcript, or confirmed folder/paste subset.
+
+## Beat 2 - Tell me about your world
+
+> **Next:** identify candidate material from your answers or files and ask what to stage.
+> **Pass-shape:** an `ingest --json` staging report with `staged >= 1` (lane named), or an
+> explicit "no real material yet" fallback to the fixed first-session sample.
+
+Use the seed library as an interview prompt bank. Read `codex/INDEX.md`, then read
+only the seed articles whose `## Interview Prompt` sections match the operator's
+energy and domain. Ask the smallest useful set of questions first:
+
+1. What product, team, or problem space are you responsible for?
+2. Who are the people or groups whose preferences shape the work?
+3. What decisions are already made, and what is still unresolved?
+4. What recurring lesson or belief guides how you operate here?
+5. What is the one pressing thing on your plate right now?
+
+If the operator has a transcript, ask them to paste or provide the file after you
+shape what to cover. If they point at a folder, list the candidate files and ask
+which subset to stage. Do not ingest unconfirmed material.
+
+Stage confirmed material as raw source:
+
+```text
+phronesis ingest <file-or-dir> --domain <active-domain> --lane inbox --json
+```
+
+Use `--lane transcripts` only when the input is a transcript. The pass signal is
+the `--json` report with `staged >= 1` and no unexpected failures.
+
+> **Checkpoint 2 - Curation.** Name what was discovered, what the operator
+> confirmed, what was staged, and what was deliberately left out. If nothing real
+> is available, fall back to the fixed first-session sample rather than inventing
+> material.
+
+## Beat 3 - Your world, mapped
+
+> **Next:** compile the staged material, then show a ranked anchor list before anything
+> becomes canonical.
+> **Pass-shape:** you see the ranking and its reasons, make an
+> accept/tighten/drop/different-slice call, and only your approved drafts become canonical
+> (`compile.accepted`).
+
+Hand off to the separate `compile` skill. Treat this as its own invocation:
+
+```text
+compile the inbox
+```
+
+Because first-run material is normally untrusted, expect drafts under
+`.phronesis/drafts/`. Do not dump every possible object at once, and do not silently
+pick one. Present a **ranked anchor list with salience reasoning**: for each top
+candidate, name why it is load-bearing, and name the lower-priority or ambiguous
+candidates you set aside and why. Then offer the operator the choice set **accept /
+tighten / drop / different-slice**, and act on their correction before accepting
+anything. The operator must approve what becomes canonical.
+
+Accept only operator-approved drafts:
+
+```text
+PHRONESIS_APPROVAL_SOURCE=operator:interactive \
+  phronesis compile accept <draft_path> --session <session-id>
+```
+
+Use the batch `compile review` path when several clean drafts are ready and the
+operator gives one rationale. Record which accepted paths now exist in
+`compiled/`.
+
+> **Checkpoint 3 - Trust beat.** State what is still raw/draft, what became
+> canonical, and which event proves it: `compile.accepted` for insight/org
+> drafts, or `action_type.committed` for deterministic typed captures. Include the
+> salience-review evidence: the ranked anchors you showed, the operator's
+> accept/tighten/drop/different-slice decision, and the accepted or rejected paths.
+
+## Beat 4 - The one pressing thing
+
+> **Next:** take your one pressing thing and query the accepted workspace for a real anchor.
+> **Pass-shape:** a real compiled path, an existing seed slug, a staged source line, a
+> concrete next step, or an honest "nothing connects yet" that names what is missing.
+
+Return value inside the same session. Ask for the one thing that matters now,
+then connect it to the freshly accepted workspace state:
+
+- Query the operator's accepted material with `phronesis query "<terms>" --json`.
+- Show one real anchor if it exists: a compiled path, a seed slug that actually
+  exists, or a source line from the staged dump.
+- If nothing connects, say the honest negative and do not fabricate a bridge.
+- Capture only warranted material. If the pressing thing is raw context, stage it
+  first. If compile or an action type is warranted, route it through the same
+  draft/action gates as above.
+
+> **Checkpoint 4 - Reciprocity.** The operator must leave with a useful response:
+> a real connection, a concrete next step, or an honest "nothing connects yet"
+> that explains what the workspace is missing.
+
+## Beat 5 - Adopt 2-3 seed principles by choice
+
+> **Next:** rank the installed seeds against your just-compiled material and recommend at
+> most three, with a redirect open before anything is adopted.
+> **Pass-shape:** you see why each seed matched (and any keyword-near distractor set
+> aside), and adopt only the ones you choose, with your rationale, via `promote_to_codex`.
+
+Seed principles are external starter material, not the operator's earned codex.
+They stay quarantined until adopted. Browse the installed seed library through
+`codex/INDEX.md` and read a few relevant seed articles. Before recommending, **show the
+ranked seed candidates**: for each, say why it matched the operator's just-compiled
+material or interview answers, name any plausible but lower-ranked distractor you set
+aside (topic-keyword nearness is not a match), and recommend at most three. Invite the
+operator to redirect to a different seed before any adoption.
+
+For each recommended seed, ask the operator whether to adopt it and why it is theirs
+now. Only then guide the existing operator-gated action:
+
+```text
+PHRONESIS_APPROVAL_SOURCE=operator:interactive \
+  phronesis act promote_to_codex --session <session-id> --domain <active-domain> \
+  --json '{"from_seed":"<collection>/<slug>","rationale":"<operator rationale>"}'
+```
+
+The payload uses `from_seed` inside `--json`. A bare `<slug>` is allowed only when
+it resolves unambiguously, but the `{collection}/{slug}` form is preferred.
+
+If no seed collection exists, say that seeds are coming and skip this beat. Do not
+fabricate a seed or copy a seed into `codex/personal/` by hand.
+
+> **Checkpoint 5 - Close the loop.** End with the accepted compiled paths, any
+> adopted seed paths, the one pressing thing's next step, and the next suggested
+> skill or doc. Include the seed salience evidence: the ranked seed recommendations,
+> the operator's rationale or redirect, the adopted paths, and any skipped seeds. Do
+> not claim a clean workspace; first-run lint may still show expected orphans.
+
+## Without the runtime
+
+The interview, curation, and synthesis still run as a plain workflow. Reads are
+unchanged: inspect `USER.md`, `MEMORY.md`, `AGENTS.md`, `codex/INDEX.md`, relevant
+seed articles, raw files, and compiled files directly.
+
+Raw-source staging stays in the raw layer. If `phronesis ingest` is unavailable,
+write confirmed operator material as Markdown under
+`domains/{domain}/raw/inbox/` or `domains/{domain}/raw/transcripts/` with
+provenance and `trust_tier: untrusted`.
+
+Any canonical write that would have gone through a later action type degrades to
+a draft capture at
+`domains/{domain}/raw/degraded/YYYY-MM-DD-onboard-{slug}.md` - never
+`compiled/`, never `codex/`, and no events emitted or back-filled. The capture
+frontmatter must carry `degraded: true`, `intended_action_type`, `skill_name:
+onboard`, `skill_version: 0.2.0`, `created`, `trust_tier: untrusted`, the exact
+payload that would have gone to the action type, and the operator approval state.
+
+Seed adoption cannot be performed runtime-free. Capture the operator's adoption
+intent in `raw/degraded/` with `intended_action_type: promote_to_codex`; reconcile
+it later through the normal operator-gated action.

package/templates/skills/onboard/evals/rubric.md

@@ -0,0 +1,60 @@
+# Onboard Rubric
+
+Score each criterion 1-5. A passing run scores at least 4 on every criterion, now
+across seven criteria. Onboard is an orchestration skill with `via_action_types: []`,
+so the rubric grades the goal-state evidence, not direct action-type firing by the
+skill. The criteria are numbered in the house format so the shared L2 judge
+(`harness/evals/judge/parse_rubric_criteria`) scores each one; everything below the
+`---` divider is a separate note, deliberately not judge-scored.
+
+1. **Consent, Boundary, And Curation —** consent and the model/storage boundary are stated before sensitive material enters, a real input mode is offered, and only the confirmed subset is staged.
+   5: Names the local-first storage and model-provider boundary before sensitive material enters the run; offers live interview, transcript, or folder/paste paths; discovers candidate material and stages only the operator-confirmed subset.
+   3: Gets consent and stages material, but the model boundary or curation record is thin.
+   1: Silently ingests or processes material without confirmation, or claims the conversation never leaves the machine.
+
+2. **World-Mapping Goal State —** a recorded run shape with staged raw material, a separate compile handoff, reviewed canonical paths, and event evidence for each accepted object.
+   5: Produces a recorded run shape with staged raw material, a separate compile handoff, reviewed/accepted canonical paths, and event evidence for each accepted object (`compile.accepted` for insight/org or `action_type.committed` for typed captures).
+   3: Produces accepted material, but the evidence trail is incomplete or mixes draft/raw/canonical states imprecisely.
+   1: Treats raw source or drafts as canonical, bypasses review, or invents accepted objects.
+
+3. **Reciprocity —** value is given back in-session by connecting the pressing thing to a real compiled path, seed slug, source line, or an honest negative.
+   5: Gives value back in-session by querying the operator's accepted material and connecting the pressing thing to a real compiled path, seed slug, source line, or an explicit honest negative.
+   3: Gives a useful response, but the anchor is weak or not recorded.
+   1: Extracts information without giving back, or fabricates a connection.
+
+4. **Seed Adoption Discipline —** at most three genuinely-matched seeds are recommended and adopted only with operator rationale through `promote_to_codex`, never copied by hand.
+   5: Uses real installed seed articles and their `## Interview Prompt` sections, recommends at most three relevant seeds, and adopts only with operator rationale through `promote_to_codex` using a `from_seed` payload; if no seeds exist, says so.
+   3: Discusses seeds accurately but adoption evidence or rationale is incomplete.
+   1: Copies seed content into `codex/personal/` by hand, fabricates seeds, or treats seed material as the operator's belief before adoption.
+
+5. **Runtime-Free And Scope Honesty —** the no-new-surface scope holds, and runtime-free canonical/adoption intents degrade to `raw/degraded/`, never `compiled/` or `codex/`.
+   5: Preserves the no-new-surface scope: no new CLI verbs, no `via_skills`, no action types issued directly by onboard, and runtime-free canonical/adoption intents degrade to `domains/{domain}/raw/degraded/YYYY-MM-DD-{skill}-{slug}.md`.
+   3: Keeps the basic scope but describes a runtime-free or adoption path loosely.
+   1: Writes `compiled/` or `codex/` directly, fabricates events, or introduces a new skill-composition/action surface.
+
+6. **Salience Judgment —** the run makes its ranking of candidate objects (Beat 3) and seed recommendations (Beat 5) visible, gives reasons grounded in the operator's own material, offers correction choices, and acts on the correction before accepting or adopting anything.
+   5: Before any compile acceptance or seed adoption, the run makes its importance-ranking explicit: what it judged most and least load-bearing, why, and where confidence is thin. It offers accept/tighten/drop/different-slice for compile anchors or accept/redirect/skip for seeds, then acts on the correction. It never silently selects one object or seed and proceeds.
+   3: Ranking is shown but the reasons are thin or the correction path is unclear; the operator can approve or reject but cannot cleanly redirect salience before the run moves on.
+   1: Conflates distinct insights, ranks a keyword-near aside above the operator's stated priority without surfacing the call, or accepts/adopts before the operator can redirect (the F0 failure).
+
+7. **Expectation-Setting —** before each beat acts, the run states what is about to happen and the concrete pass-shape, so the operator can grade reality without already knowing the product.
+   5: Every beat states, before acting, what is about to happen and the concrete pass-shape to look for: the file, path, event, command result, honest negative, or operator-visible result that means it worked. The operator can grade reality without prior product knowledge.
+   3: Previews exist but pass-shapes are vague or missing on some beats; the operator can mostly follow but is unsure what success looks like at points.
+   1: The operator learns what success looked like only after the fact, or never (the F16 failure).
+
+---
+
+## Coverage Note
+
+The core-0049 build validated loader, registry, install, docs, and runtime-free shape.
+This build (change 0035 / core-0057) ships the minimal semantic fixture the L2 judge
+scores against. That fixture must exercise a live interview or transcript/folder
+curation, a recall give-back or honest negative, seed adoption with a keyword-near
+distractor, and — the two criteria this build adds — visible salience-ranking with an
+operator correction and per-beat expectation evidence recorded before action. The
+fixture and its sanitized index ship in `skills/onboard/evals/` (see `GOLDENS.md`);
+real operator-signed goldens live in the install per `specs/eval-discipline.md`, never
+this public repo. The deterministic L1 gate (this rubric parses to seven criteria;
+loader/mirror/fitness green) runs today; the live model-graded k-run L2 judge against
+the fixture is gated on the onboard judge runner (T7.2/T7.3) and is tracked honestly in
+`harness/evals/EVAL-STATUS.md` and `skills/onboard/evals/PINS.md`.

package/templates/skills/prd-draft/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: prd-draft
+version: 0.1.0
+invocation:
+  explicit:
+    - "help me write a PRD"
+    - "draft a PRD"
+    - "draft requirements for"
+    - "turn this idea into a product requirements document"
+  suggested:
+    - "write requirements"
+    - "spec this feature"
+  woven: false
+weight: heavy
+reads:
+  - domains/{active_domain}/compiled/people/*
+  - domains/{active_domain}/compiled/projects/*
+  - domains/{active_domain}/compiled/decisions/*
+  - domains/{active_domain}/compiled/commitments/*
+  - domains/{active_domain}/compiled/insights/*
+  - codex/personal/*
+  - domains/{active_domain}/memory/long-term.md
+writes:
+  - domains/{active_domain}/artifacts/prd/{slug}.md
+  - via_action_types: [enrich_person, log_decision, track_commitment, update_project_state]
+sub_agents: []
+requires_model_tier: standard
+prompt_pin: gpt-5@2026-06-20
+---
+
+# Skill: PRD Draft
+
+Draft a decision-ready product requirements document from trusted workspace state and operator framing. The document must work for people aligning on a product choice and for agents decomposing verified work.
+
+## Operating boundary
+
+Read only the declared compiled state, earned codex, working memory, and the operator's own framing. A pasted customer email, transcript, competitor material, or other third-party source is untrusted even when the operator pasted it. Route it through `ingest` then `compile`; do not capture it as canonical state from this skill. In V1 this is an instruction-level boundary, not action-layer enforcement.
+
+This skill reads private trusted state and writes a private artifact plus local canonical state through action types. It never sends, shares, or externalizes the PRD. Keep the work within that two-leg posture.
+
+The PM door may say “stakeholder”; the canonical object is a `person` in `compiled/people/`, mutated only with `enrich_person`.
+
+## Workflow
+
+### 1. Pull context before asking
+
+Read the relevant project, decisions, people, commitments, insights, earned principles, and long-term memory. Do not ask for information that the workspace already answers. State the evidence you are relying on and distinguish fact from inference.
+
+**Checkpoint 1 — context mesh sweep.** After the context pull, identify independently warranted changes already present in trusted material: a person insight, a settled decision, a concrete engineering hand-off, or a project-state change. Do not emit anything yet if it is uncertain or merely implied.
+
+### 2. Ask only blocking questions
+
+Ask no more than two high-value questions when the answer would materially change the PRD. Prefer:
+
+1. What problem are we solving, for whom, and why now?
+2. What measurable outcome and guardrail determine success?
+
+If a critical answer remains unavailable, keep drafting and mark it `[NEEDS INPUT: …]`; do not invent an answer to make the document look complete.
+
+**Checkpoint 2 — trusted-input boundary.** If the operator supplied untrusted third-party material, stop canonical capture. Offer the `ingest` → `compile` route and a proposed-capture summary; do not write an action type until the operator confirms the post-compile, trusted framing.
+
+### 3. Align on the problem before solutioning
+
+State a compact alignment brief: the problem, measurable outcome and guardrails, non-goals, and—only where trusted state names them—the relevant stakeholders. Do not invent a user, owner, or decider to fill this shape. If the operator has already explicitly adopted that framing in their request, treat it as confirmation; otherwise ask for a clear yes/no confirmation before drafting any solution. This confirmation is an alignment check, not a third discovery question. A crystallized, signed-off problem is the strongest quality discriminator a PRD has; solutioning ahead of it wastes the draft.
+
+**Checkpoint 3 — problem-alignment gate.** Do not continue to the directional solution until the operator confirms the problem framing. The alignment brief is normally conversational: while it is under review, its lifecycle state is `Problem Review`. Do not persist a durable artifact yet unless the operator explicitly wants an incomplete review draft. After confirmation, the first complete PRD is `Solution Review`; advance it to `Launch Review` or `Launched` only through an explicit later refinement. If the confirmed framing settles an independently warranted, durable scope or priority choice, bank that choice with `log_decision`; agreement alone is not automatically a canonical decision.
+
+### 4. Produce the PRD
+
+Use this shape, adding detail only when it changes a decision. Keep the body short; push depth to an appendix.
+
+```markdown
+# <Feature or project> — PRD
+
+**Status:** Solution Review   <!-- lifecycle: Draft → Problem Review → Solution Review → Launch Review → Launched; first complete PRD is Solution Review -->
+**Date:** YYYY-MM-DD
+**Stakeholders:** <owner, deciders, builders — named from compiled/people>
+
+## Problem
+Who has which evidenced problem, why it matters now, and the cost of being wrong.
+Name the compiled decisions, insights, or people this rests on and add resolved `cites` links for those sources in artifact frontmatter; do not invent a user. The reader should be able to grasp the problem from this section alone.
+
+## Outcome and guardrails
+Few measurable success criteria with targets, plus the counter-metrics that must not regress.
+
+## Non-goals
+Explicit, co-equal exclusions that prevent scope drift — as clarifying as the goals.
+
+## Directional solution
+Enough product and technical shape to align — pass the squint test, not a premature blueprint.
+
+## Requirements
+Specific, testable requirements for people and agents. State acceptance evidence in Given/expect form.
+
+## Rollout and exit criteria
+Phases, dependencies, and the evidence required to advance or stop — not dates alone.
+
+## Launch readiness (when applicable)
+Name the domain-shaped cross-functional owners and the checks they must clear before launch; do not add a generic checklist that changes no decision.
+
+## Alternatives and tradeoffs
+Alternatives considered, decisions made, and what would invalidate the choice.
+
+## Risks and open questions
+Risks with mitigations. Use [NEEDS INPUT: …] for genuine unknowns.
+```
+
+The `Stakeholders` line and any per-role detail are contextual — include them when the work has real alignment owners (which it usually does, since you read `compiled/people`).
+
+For a probabilistic (AI/LLM) feature, the PRD is a **behavioral contract**, not a behavior description. Add a section carrying every component below — vague prose here ("should be accurate and concise") is the ambiguity the model resolves in production where you cannot see it:
+
+```markdown
+## Behavioral contract (AI features)
+
+**Behavior matrix** — one row per input class:
+
+| Input class | Target behavior | Acceptable degradation | Forbidden output |
+|---|---|---|---|
+
+**Acceptance as assertion.** Binary pass/fail per named failure mode, a % bar, and a named arbiter (e.g. "≥90% of 100 eval queries route correctly; a senior PM reviews 20 outputs/sprint, >2 failures → back to prompt iteration"). Not a Likert vibe.
+
+**Eval set + thresholds.** A named, versioned dataset, a scoring metric, and an explicit ship threshold *and* rollback threshold — defined before building.
+
+**Two-layer success metrics.** Pair model-quality measures with product outcomes and an honest user-override counter-metric; do not let a good model score hide a feature users abandon or rewrite.
+
+**Never-do constraints.** Specific, adjudicable rules ("must not cite a source absent from the retrieved context"), not "should not hallucinate."
+
+**Failure-mode catalog.** Drawn from real prototype outputs, not imagined. If those outputs do not exist yet, mark `[NEEDS INPUT: trace-review owner and due date]` as a pre-launch blocker rather than inventing a catalog.
+
+**Fallback + model strategy.** What the user sees on uncertainty/refusal/timeout; the capability profile, primary/fallback, and switch logic—not a pinned model version.
+
+**Ops readiness.** Golden-dataset owner + due date; cost-at-scale (tokens × volume × price).
+```
+
+**Checkpoint 4 — artifact plus capture sweep.** Once the draft exists, separately assess each of the four capture types below. Capture only independently warranted state; an honest zero is better than invented mesh. The coverage target counts warranted typed-write instances, not distinct action types.
+
+### 5. Self-review against the quality bar
+
+Before persisting, grade the draft against `evals/rubric.md` and apply three forcing tests. Tighten any criterion below the bar; where a gap is real, mark it honestly with `[NEEDS INPUT: …]` rather than padding. A smaller honest PRD beats a bloated one.
+
+- **Squint test** — can a reader squint and see the same product shape? If not, the directional solution is over- or under-specified.
+- **The $5,000 bet** — would you bet your own money on this? Forces value, outcome, and testability to the surface.
+- **Disappointment test** — would real users be disappointed to lose this? If the answer is soft, the problem is under-developed.
+
+**Checkpoint 5 — quality self-check.** Confirm the problem reads standalone and is evidenced; success criteria are few, targeted, and carry a counter-metric; non-goals are co-equal; each rollout phase has exit criteria, not just a date; launch readiness is named when relevant; unknowns and tradeoffs are honest, not a sales pitch. For an AI feature, confirm every component of the behavioral-contract section is present. This author-side review is not evidence that the L2 gate passed; it identifies gaps for the operator and T7.6 corpus to judge.
+
+### 6. Persist or refine the durable artifact
+
+Write the PRD directly to `domains/{active_domain}/artifacts/prd/{slug}.md`. It is a durable non-canonical artifact, not a `compiled/` object, and always carries:
+
+```yaml
+---
+kind: prd
+title: <human title>
+created: YYYY-MM-DD
+exposure: private
+# When compiled sources ground the PRD, include resolved standard links:
+links:
+  - rel: cites
+    target: decisions/<slug>
+---
+```
+
+Optional `links:` use the standard link grammar. A new `{slug}` creates a new artifact. The path is the identity: if the path exists, ask whether the operator intends an explicit refinement or wants a new slug. On explicit refinement, edit in place, set `updated` to today (never before `created`), and append `{ date, note }` to `provenance.refinements`. Never silently replace a same-slug document. The artifact is excluded from ordinary retrieval; use an explicit artifact read when reopening it.
+
+### 7. Bank warranted canonical context
+
+Use the runtime action path for trusted captures. Do not write `compiled/` or `codex/` directly.
+
+| When independently warranted | Action type | Required care |
+|---|---|---|
+| A durable scope or priority choice is made | `log_decision` | Include the decision, rationale, expected outcome, success signal, and a review prompt when the choice is high stakes. New decisions may link to the project or person they enable or are decided by. |
+| A person’s durable priority, constraint, or knowledge changes | `enrich_person` | Supply `name` and `insight`; new people also need `title` and may need approval. Do not append `links` to an existing person. |
+| An owned engineering hand-off with a due date emerges | `track_commitment` | Supply `title` and a real `due` date. New commitments may carry the spoke-to-hub link. |
+| Scope, status, or a project-level fact changes | `update_project_state` | Supply `name` and `update`; a new project also needs `title` and may need approval. Do not append `links` to an existing project. |
+
+Use links from a newly-created decision or commitment to the existing project/person hub. Existing people and projects are append-only log targets; never attempt a cross-link by mutating their frontmatter.
+
+**Checkpoint 6 — refinement sweep.** After each material refinement, reassess only newly established trusted facts. Re-run the artifact refinement procedure if the PRD changed. Do not manufacture captures to increase a count.
+
+### 8. Return a compact handoff
+
+Return the artifact path, the decisions and commitments actually banked, the open `[NEEDS INPUT]` markers, the most important unresolved tradeoff, and any quality criterion that remains below the bar. Say plainly if nothing was captured.
+
+## Without the runtime
+
+Reads and the durable artifact write continue unchanged. Write/refine the PRD directly at `domains/{active_domain}/artifacts/prd/{slug}.md`, keep it private, and obey the same explicit-refinement rule. It emits no event.
+
+Each intended canonical action becomes a separate untrusted capture in `domains/{domain}/raw/degraded/YYYY-MM-DD-prd-draft-{slug}.md`, never in `compiled/` or `codex/`. Make `{slug}` unique per capture: compose `<prd-slug>-<action-type>-<capture-slug>` (for example, `search-quality-log-decision-scope-first`) so dense captures for one PRD never collide. Its frontmatter contains `degraded: true`, `intended_action_type`, `skill: prd-draft`, `version: 0.1.0`, `created`, `trust_tier: untrusted`, and the payload the action would have received. Do not emit or back-fill events. When the runtime is available, reconcile captures only through `compile` and the normal action gates.
+
+## Evaluation status
+
+`skills/prd-draft/evals/rubric.md` defines the L2 judgment criteria. Operator-signed contrast pairs and model-run coverage, including the reactive-untrusted negative, are T7.6 work. This skill is not launch-complete until those runs pass at the reliability floor with this exact `prompt_pin`.

package/templates/skills/prd-draft/evals/rubric.md

@@ -0,0 +1,38 @@
+# PRD Draft — L2 Quality Rubric
+
+This rubric judges the **quality of the PRD document** against the discriminating principles in the Research standard (`anatomy-of-an-optimal-prd`). It is portable: it contains no operator PRDs or fabricated golden data.
+
+Score each applicable criterion 1–5, independently — a coarse single score hides exactly the discriminators that separate a senior PRD from a junior one. An excellent PRD floors **≥ 4 on every applicable row**. The criteria are numbered (house format) so the shared L2 judge (`harness/evals/judge/parse_rubric_criteria`) scores each one; everything below the `---` divider is a **separate axis**, deliberately not judge-scored. Run the model-graded suite at the reliability floor before promoting a changed `prompt_pin`.
+
+Mesh coverage and untrusted-input restraint are **separate axes**, scored elsewhere (see *Separate axes* below) — they are not quality criteria and must not dilute or be diluted by this rubric.
+
+## Tier 1 — Classic core (every PRD)
+
+1. **Problem-orientedness** — the problem is crystallized at the top, evidenced from compiled state, and reads standalone. Failure: the problem is a missing feature; no evidence is offered; a user is invented.
+2. **Success criteria** — few, measurable, and targeted; a counter-metric / guardrail is present; AI features pair model quality with a product outcome and user-override measures. Failure: many or vague; no targets; no guardrail; a model score stands in for product value.
+3. **Scope discipline** — non-goals are explicit and co-equal with the goals. Failure: non-goals are absent or token.
+4. **Just-enough solution shape** — directional; it passes the squint test. Failure: an over-specified blueprint, or too vague to align on.
+5. **Honest unknowns** — open questions and risks-with-mitigations are surfaced; `[NEEDS INPUT]` marks real gaps. Failure: unknowns are hidden; it reads as a sales pitch.
+6. **Tradeoffs / decisions** — alternatives are named and what would invalidate the choice is stated. Failure: decisions are presented as inevitable.
+7. **Urgency** — a rollout with per-phase exit/stop criteria. Failure: date-only, or no timeline.
+8. **Readable & self-contained** — short; depth pushed to an appendix; one reader can act on it. Failure: long, messy, sections that don't earn their place.
+
+## Tier 2 — AI-native layer (any AI/probabilistic feature; score N/A and omit for a non-AI PRD)
+
+9. **Eval-set + thresholds** — a named/versioned dataset, a metric, and ship + rollback thresholds, all defined pre-build. Failure: "be helpful and accurate"; thresholds set later.
+10. **Acceptance as assertion** — binary pass/fail per failure mode, a % bar, and a named arbiter; where input classes materially differ, a behavior matrix names target behavior, acceptable degradation, and forbidden output for each. Failure: Likert vibes; scenario-only criteria; input classes with materially different risk left ambiguous.
+11. **Behavioral constraints** — specific never-do rules a new hire could adjudicate. Failure: "should not hallucinate."
+12. **Failure-mode catalog** — drawn from real prototype outputs; before those exist, an explicit trace-review owner and due date are a pre-launch blocker. Failure: imagined as evidence; absent without an evidence-collection plan.
+13. **Fallback + model strategy** — refusal/uncertainty/timeout behavior plus a capability profile, a primary/fallback, and switch logic. Failure: happy-path only; a pinned model version.
+14. **Ops readiness** — a golden-dataset owner + due date; cost-at-scale (tokens × volume × price). Failure: both skipped.
+
+---
+
+## Separate axes (scored elsewhere, never folded into the quality score)
+
+- **Warranted mesh coverage** — did the authoring session bank the warranted typed-write instances (`enrich_person`, `log_decision`, `track_commitment`, `update_project_state`)? This is the behavioral **coverage eval** (`eval-discipline.md` §"Coverage evals", change 0011/0019), asserted in **both** directions: warranted captures fire, *and* unwarranted captures do not. A dense fixture warrants ≥ 5 non-`no_op` instances across the four types. Density is a descriptive metric, **never** a target to inflate; an honest negative is a valid, passing outcome. A high-quality PRD that legitimately warranted zero captures must not fail on this axis — keeping it out of the quality rubric is what prevents that.
+- **Untrusted-input restraint** — pasted third-party material yields a draft plus a route to `ingest` → `compile` (or a proposed-capture confirmation), and issues **zero** canonical captures until the operator supplies trusted, confirmed framing. This is the mandatory **reactive-untrusted negative fixture** (the L4 security lock), not a quality grade.
+
+## Corpus status
+
+No golden data is authored here. T7.6 owns an operator-signed contrast pair and the model-run coverage, L2, and reactive-untrusted fixtures. Record the exact `prompt_pin` for each run; a changed pin requires rerunning L1 and L2.