phronesis 1.0.0 → 1.1.0

package/templates/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-version: 0.2.0
+version: 0.3.0
 invocation:
   explicit:
     - "onboard me"
@@ -133,6 +133,9 @@ 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.
 
+When you build any `phronesis act <type>` payload later in the run, read the payload
+shape with `phronesis act <type> --schema` instead of probing it with empty payloads.
+
 > **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
@@ -156,7 +159,16 @@ 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 /
+candidates you set aside and why.
+
+Before asking for any accept decision, **show each top draft's content, not just its
+title, path, or classification** (see `specs/skills.md` §"Approval requires visible
+content"): print the draft path (clickable-to-preview in Claude Code / Codex desktop)
+and, in a plain terminal, inline the body; show a short draft in full and a long draft
+as a structured summary with the body available on request. Never ask the operator to
+accept a draft they have not been shown a way to read.
+
+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.
 
@@ -176,6 +188,9 @@ operator gives one rationale. Record which accepted paths now exist in
 > 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.
+> Confirm the operator was shown each draft's content (not only its title or path)
+> before the accept decision. When you name an accepted object to the operator, use
+> its display name, not its path slug.
 
 ## Beat 4 - The one pressing thing
 
@@ -205,13 +220,25 @@ then connect it to the freshly accepted workspace state:
 > **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
+Open the beat by explaining what these are, in the operator's language:
+
+> Phronesis ships with a library of starter principles - distilled judgment patterns
+> that stay quarantined until you adopt one. Adopting copies the principle into your
+> personal codex with your reasons attached; the original stays in the library.
+
+The starter principles are the shipped seed library (`codex/seed/`) - external material,
+not the operator's earned codex - and adoption is the deliberate `promote_to_codex` act
+that copies one into `codex/personal/`. Browse the installed 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.
+aside (topic-keyword nearness is not a match), and recommend at most three.
+
+Before asking the operator to adopt any seed, **show that seed's content** (see
+`specs/skills.md` §"Approval requires visible content"): a short seed article in full, a
+longer one as a structured summary with the body available on request, with the seed path
+as a citation. Never ask the operator to adopt a principle they have not been shown a way
+to read. 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:
@@ -231,8 +258,19 @@ 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.
+> the operator's rationale or redirect, the adopted paths, and any skipped seeds.
+> Confirm each recommended seed's content was shown before adoption. Do
+> not claim a clean workspace; first-run lint may still show expected orphans — objects
+> not yet linked into the mesh in either direction (a freshly enriched person wired only
+> to a raw source is the common early case).
+>
+> **Speak in the operator's language, not the engine's.** When you name a person,
+> organization, or object to the operator, use its display name (for example
+> "Matt Moss"), not its path slug ("matt-moss") or file path. Describe what changed in
+> plain outcomes ("your workspace now holds three principles you chose"; "you added four
+> people"), not the internal graph or ledger tallies the engine keeps for its own
+> bookkeeping. A path may appear as evidence or a citation, but never as the
+> operator-facing name of a thing.
 
 ## Without the runtime
 
@@ -250,7 +288,7 @@ 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
+onboard`, `skill_version: 0.3.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

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

@@ -13,7 +13,7 @@ skill. The criteria are numbered in the house format so the shared L2 judge
    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).
+   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); and the operator was shown each draft's content (path plus body per the surface-tiered rule in `specs/skills.md` §"Approval requires visible content"), not only its title or classification, before approving it.
    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.
 
@@ -50,8 +50,10 @@ The core-0049 build validated loader, registry, install, docs, and runtime-free
 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
+distractor, visible salience-ranking with an operator correction, per-beat expectation
+evidence recorded before action, and — added by change 0045 / core-0059 — the draft/seed
+content rendered before the approval checkpoint (the operator was shown a way to read what
+they approved, per `specs/skills.md` §"Approval requires visible content"). 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;

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

@@ -1,6 +1,6 @@
 ---
 name: prd-draft
-version: 0.1.0
+version: 0.2.0
 invocation:
   explicit:
     - "help me write a PRD"
@@ -18,6 +18,7 @@ reads:
   - domains/{active_domain}/compiled/decisions/*
   - domains/{active_domain}/compiled/commitments/*
   - domains/{active_domain}/compiled/insights/*
+  - domains/{active_domain}/artifacts/prd/*
   - codex/personal/*
   - domains/{active_domain}/memory/long-term.md
 writes:
@@ -25,7 +26,7 @@ writes:
   - 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
+prompt_pin: gpt-5@2026-07-12
 ---
 
 # Skill: PRD Draft
@@ -44,9 +45,9 @@ The PM door may say “stakeholder”; the canonical object is a `person` in `co
 
 ### 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.
+Read the relevant project, decisions, people, commitments, insights, earned principles, and long-term memory. When the invocation already supplies a trusted context packet or post-alignment scenario stage and says it represents declared reads, treat those facts as already read; do not spend turns re-reading the same paths. Otherwise issue all independent workspace reads together in one assistant turn. 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.
+**Checkpoint 1 — context and delta sweep.** After the context pull, separate trusted context that was already canonical before this session from state newly established, confirmed, or changed during this authoring session. Existing context can ground the PRD but is not a new capture. Identify possible deltas across a person insight, decision, owned hand-off, and project-state change. Do not emit anything yet if it is uncertain, merely implied, or already banked.
 
 ### 2. Ask only blocking questions
 
@@ -67,7 +68,7 @@ State a compact alignment brief: the problem, measurable outcome and guardrails,
 
 ### 4. Produce the PRD
 
-Use this shape, adding detail only when it changes a decision. Keep the body short; push depth to an appendix.
+Use this shape, adding detail only when it changes a decision. Target 750–900 words for a deterministic PRD and 950–1,100 words total for an AI PRD, including its appendix; 1,150 words is a hard whole-document ceiling. When no mechanical word counter is available, aim at the low end rather than claiming an unverified count. Use these budgets: problem + outcomes + non-goals ≤160 words; directional solution + capability table ≤190; rollout + readiness + tradeoffs + risks/open questions ≤270; AI appendix ≤300. Do not repeat a target, constraint, rationale, or rollout gate after a table or earlier section already states it. Before persisting, compress anything plausibly over the ceiling by removing repetition and implementation detail—not trusted targets, real unknowns, or exit gates. Express requirements as one compact capability table with no more than four rows. Limit alternatives to the two or three choices that materially change the product, each in one compact bullet carrying direction, rationale, tradeoff, and `Revisit if:`. One representative acceptance signal can be qualitative and binary; never invent a latency, duration, count, percentage, expiry, or other numeric target merely to make it look testable. Move exhaustive Given/expect cases, API fields, transports, components, UI controls, and other implementation detail to a follow-up spec unless the detail is already a trusted target or changes a product decision. Omit non-decision-making depth rather than appending it to this PRD.
 
 ```markdown
 # <Feature or project> — PRD
@@ -82,15 +83,22 @@ Name the compiled decisions, insights, or people this rests on and add resolved
 
 ## Outcome and guardrails
 Few measurable success criteria with targets, plus the counter-metrics that must not regress.
+Preserve explicit targets already established in trusted state. Do not replace a known target with `[NEEDS INPUT]`, and do not invent a missing target merely to fill the shape.
 
 ## 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.
+Name only capabilities and observable behaviors grounded in trusted state. A category label such as “inbox,” “dashboard,” or “assistant” is not evidence for customary controls: do not add search, badges, queues, assignment, mark-as-done, refresh behavior, notifications, or similar UI conventions unless the trusted input names them. Keep an unresolved behavior in open questions rather than quietly turning it into a requirement.
 
 ## Requirements
-Specific, testable requirements for people and agents. State acceptance evidence in Given/expect form.
+| Capability | Observable behavior | One acceptance signal |
+|---|---|---|
+| <capability> | <what the user/system can observe> | <one representative Given/expect or trusted target> |
+
+This is an alignment contract, not the complete acceptance-test suite. Do not expand the table into sub-requirements in the main body.
+Every row must map to an explicit trusted target, decision, constraint, or user behavior. If you cannot point to that anchor, omit the row; do not make the PRD feel complete by importing a plausible category-default feature.
 
 ## Rollout and exit criteria
 Phases, dependencies, and the evidence required to advance or stop — not dates alone.
@@ -99,7 +107,7 @@ Phases, dependencies, and the evidence required to advance or stop — not dates
 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.
+Alternatives considered, decisions made, and a concrete `Revisit if:` condition for each chosen direction.
 
 ## Risks and open questions
 Risks with mitigations. Use [NEEDS INPUT: …] for genuine unknowns.
@@ -107,42 +115,42 @@ 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:
+For a probabilistic (AI/LLM) feature, the PRD is a **behavioral contract**, not a behavior description. Put the detailed contract in one in-document appendix so the decision-ready main body stays short while the document remains self-contained. Carry every component below, but express each once: at most four materially different behavior-matrix rows, one compact bullet block per remaining component, no repeated thresholds or rollout prose. 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)
+## Appendix A — 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.
+**Acceptance as assertion.** Binary pass/fail per named failure mode, a % bar, and a named human or accountable role as arbiter (e.g. "the PRD owner reviews 20 outputs/sprint; >2 failures → back to prompt iteration"). Repeat the trusted eval-set ship and rollback percentages exactly; never invent a second threshold for this section. 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.
+**Eval set + thresholds.** A named, versioned dataset, a scoring metric, and an explicit ship threshold *and* rollback threshold, both defined before building. The rollback threshold is a pre-build design choice, not a deferral: once the metric and ship threshold are set, state a concrete rollback trigger (a production safety-violation event and a live-quality floor) rather than leaving it `[NEEDS INPUT]`. If trusted state supplies a ship floor but no separate live-quality rollback floor, reuse that same trusted floor as the conservative production rollback floor and say explicitly that it is the same threshold; do not invent a second percentage and do not defer it.
 
 **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.
+**Failure-mode catalog.** Drawn from real prototype outputs, not imagined; keep observed failures visibly labelled as observed and any hypothesized mode separate. Do not add plausible hypothetical failures merely to fill out the catalog: include them only when trusted state also names the trace-review owner and due date that will test them. If even one observed failure is supplied, list every supplied observed failure and do not replace the evidence with an empty `[NEEDS INPUT]` placeholder. Add a trace-review owner-and-due plan only for a genuinely missing broader review, and name a specific owner and due date rather than a bare placeholder. If no prototype outputs 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.
+**Fallback + model strategy.** Use this exact three-part mini-contract: `Primary capability profile:` the tool-use/reasoning capabilities required and their role; `Fallback capability profile:` the reduced or alternate model capability and safe degradation; `Switch when:` an observable quality, latency, refusal, or availability condition. Also say what the user sees on uncertainty/refusal/timeout. Do not pin a model version. A client or connector such as Claude Desktop or ChatGPT is not itself a model fallback.
 
-**Ops readiness.** Golden-dataset owner + due date; cost-at-scale (tokens × volume × price).
+**Ops readiness.** Golden-dataset owner + due date; cost-at-scale as an explicit `tokens × volume × price` calculation. If inference is paid by an external client, write the equation explicitly as `0 product-paid tokens × call volume × model price = $0 product inference cost`, name who pays instead, and separately name the server-side cost drivers and missing inputs.
 ```
 
-**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.
+**Checkpoint 4 — artifact plus capture plan.** Do not invoke a canonical action before the PRD artifact is written. Once it exists, make a four-row capture plan—decision, commitment, project, person—with the exact trusted source, whether it is new this session, and `capture` or `skip` plus the reason. For every decision row, preflight four fields from trusted transition state: direction, rationale, cost/tradeoff, and evidence. Resolve those fields in this order: explicit operator rationale; named evidence; constraints and risks directly tied to the choice; only then a labeled inference. Preserve every available source field in the action. Do not replace a central supplied user risk, inherited-platform constraint, external dependency, or irreversible-harm concern with a different plausible tradeoff. Execute every `capture` row and no `skip` row in one tool-call wave. Do not stop after decisions. An honest zero is better than invented state; the coverage target counts warranted instances, not action-type variety.
 
 ### 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.
+- **Squint test** — can a reader squint and see the same product shape? If not, the directional solution is over- or under-specified. Remove field names, transport mechanics, components, UI controls, and exhaustive acceptance cases from the main body unless they change the product choice. Audit every capability and requirements row back to a trusted fact; delete category-default UI invented from the feature name, and return unresolved behaviors to open questions.
 - **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.
+**Checkpoint 5 — quality and compression 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; every chosen alternative has a `Revisit if:` condition; 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. Compress toward 750–900 words for a deterministic PRD or 950–1,100 total words for an AI PRD and treat 1,150 whole-document words as a hard failure. Remove repeated targets/rationales, invented numeric acceptance details, and detailed mechanics first; never compress away trusted targets, genuine `[NEEDS INPUT]` items, or phase exit evidence. Keep requirements in the compact capability table and omit implementation depth from this PRD. For an AI feature, put the terse behavioral contract under `Appendix A`, use no more than four behavior rows, and confirm every component is present without repeating main-body content. Acceptance repeats the trusted percentages exactly, and the eval-set defines both a ship and a rollback threshold rather than deferring rollback. When no distinct trusted rollback percentage exists, the live-quality rollback floor must explicitly reuse the trusted ship floor. Confirm the failure catalog retains every supplied observed failure, the fallback block literally names `Primary capability profile`, `Fallback capability profile`, and `Switch when`, connectors are not mistaken for model fallbacks, and ops readiness includes a literal cost equation. 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
 
@@ -165,18 +173,18 @@ Optional `links:` use the standard link grammar. A new `{slug}` creates a new ar
 
 ### 7. Bank warranted canonical context
 
-Use the runtime action path for trusted captures. Do not write `compiled/` or `codex/` directly.
+Use the runtime action path for trusted captures. Do not write `compiled/` or `codex/` directly. Execute from the post-artifact four-row plan. Read the action results before finishing. If an action is rejected because its payload is malformed, correct that same warranted action immediately; do not substitute a different capture to make the count look complete. Omit `exposure` unless the operator explicitly changes it—the action default is private—and never turn a contextual evidence label into an exposure value. Batch independent capture actions in one assistant turn so a correct dense run leaves room for one correction wave and a final response.
 
 | 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. |
+| A durable scope or priority choice is newly made, newly confirmed as unbanked, or materially changed in this session | `log_decision` | Capture the smallest sufficient set. Do not re-log every listed decision or every constraint read from canonical state. Make the title standalone: name the product or capability subject and the chosen direction; a generic title such as `Deployment model` or `Architecture choice` is invalid even when the body supplies the missing subject. When one established choice joins multiple load-bearing directions, carry every axis in the title rather than naming only one component. Preserve the trusted direction, rationale, cost/tradeoff, and evidence without substituting a different justification; include expected outcome, success signal, and a review prompt when high stakes. |
+| A human’s durable priority, constraint, or knowledge changes | `enrich_person` | The target must be a person, not a team or organization. Supply the canonical person slug as `name` and the new `insight`; only a genuinely new person gets create-only `title`, `exposure`, or `links` and may need approval. For an existing person, omit all create-only fields. |
+| A newly established owned hand-off has a real due date | `track_commitment` | Supply `title`, exact `due`, and a `body` beginning `Owner: <full name>.` followed by the deliverable and acceptance evidence. The V1 action has no typed owner field; do not invent one. Do not turn a date proposal or owner inference into a commitment. |
+| This PRD run materially changes a named project’s scope, status, lifecycle, or next gate | `update_project_state` | Supply the canonical project slug as `name` and one compact `update` covering the PRD lifecycle, core direction, success guardrail, launch perimeter when defined (such as tiers or connectors), phase gate, material open questions, and inherited external dependencies. Only a genuinely new project gets create-only `title`, `exposure`, or `links` and may need approval. For an existing project, omit all create-only fields. |
 
-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.
+Use semantically valid links from a newly-created decision or commitment to an existing project/person hub only when the current link vocabulary and target grammar can express the relationship. A PRD artifact path is not a valid canonical action link target: never add `artifacts/prd/...` to an action payload. Omit a link when no valid compiled target and relation exist. Do not misuse `cites`, `decided-by`, or another relation merely to encode commitment ownership. 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.
+**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. If multiple actions are rejected for the same payload defect, correct and resend every rejected warranted action together in the next tool-call wave; do not repair them one per turn.
 
 ### 8. Return a compact handoff
 
@@ -186,8 +194,8 @@ Return the artifact path, the decisions and commitments actually banked, the ope
 
 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.
+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.2.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`.
+`skills/prd-draft/evals/rubric.md` defines the L2 judgment criteria. The operator-signed contrast pairs, model-run coverage, and reactive-untrusted negative passed T7.6 at the reliability floor for this exact `prompt_pin`; `evals/PINS.md` records the accepted baseline.

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

@@ -24,7 +24,7 @@ Mesh coverage and untrusted-input restraint are **separate axes**, scored elsewh
 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.
+14. **Ops readiness** — a golden-dataset owner + due date; cost-at-scale (tokens × volume × price). When an external client pays inference, an explicit `$0` product-inference equation plus the product's server-side cost drivers and honestly marked missing sizing inputs satisfies the cost requirement; do not require invented volume. Failure: both skipped.
 
 ---
 

package/vendor/core/src/action-registry.js

@@ -40,7 +40,7 @@
 // one garbled entry disables the whole action layer with an error naming it. A config
 // error is loud and total, never partial.
 
-import { SLUG_SOURCE } from './contract.js';
+import { SLUG_SOURCE, RE_SLUG } from './contract.js';
 
 export const PERMISSION_ORDER = ['auto-run', 'ask-once-if-new', 'requires-approval'];
 
@@ -368,8 +368,11 @@ export function resolveActionTypesAgainst({ registry, codeTable }) {
   // resolution depends on it, so a malformed list fails closed HERE — the one
   // validator both `act` and `registry status` consume (a status that calls the
   // layer disabled while act still writes is the two-matchers drift, rules.md).
-  if (!Array.isArray(registry.domains) || registry.domains.some((d) => typeof d !== 'string')) {
-    errors.push('domains: must be a list of domain-slug strings (every action resolves its domain against it)');
+  // Enforce the SLUG the message already claims (Codex R3 F3): a non-slug domain (e.g. "../../outside")
+  // would path-traverse when any surface joins it into domains/{domain}; the registry is the trust
+  // root every domain resolution reads, so fail closed here, not only in each caller's containment guard.
+  if (!Array.isArray(registry.domains) || registry.domains.some((d) => typeof d !== 'string' || !RE_SLUG.test(d))) {
+    errors.push('domains: must be a list of domain-slug strings (kebab-case; every action resolves its domain against it)');
   }
 
   const section = registry.action_types;

package/vendor/core/src/actions.js

@@ -56,7 +56,6 @@ import { checkObjectContent } from './validate-object.js';
 import { appendEvent, readEvents, localDateStamp } from './event-log.js';
 import { digestFile } from './content-digest.js';
 import { resolveInstall } from './install-root.js';
-import { DEFAULT_DOMAIN } from './layout.js';
 import {
   slugify,
   serializeFrontmatter,
@@ -67,6 +66,26 @@ import {
   stageValidateRenameAll,
 } from './action-writers.js';
 
+// A POST-WRITE failure (Codex R4 F2): the artifact IS on disk, but a later audit-append / hook step
+// failed. The error carries `postWrite: true` so a surface adapter treats the mutation as LANDED (and
+// records it in its honest-cancellation ledger), not as a refusal — event-log.md:92 "artifact written
+// but audit failed" spine case. A pre-write refusal is a plain Error (no flag).
+function postWriteError(message) {
+  const e = new Error(message);
+  e.postWrite = true;
+  return e;
+}
+
+// A PRE-write cancellation (Codex R6 F1): an OPTIONAL `ctx.signal` aborted BEFORE the durable write —
+// so no artifact landed. `aborted: true` lets a surface report "cancelled", NOT "refused", and NOT as
+// a post-write landed mutation. Backward-compatible: with no `ctx.signal` there is no check and no
+// behavior change for any existing caller.
+function abortedError(type) {
+  const e = new Error(`${type}: the turn was cancelled before the durable write — nothing was written.`);
+  e.aborted = true;
+  return e;
+}
+
 // --- Payload schemas (D2 — hand-rolled, zero-dep) ------------------------------------
 //
 // A JS field-spec object per action satisfies ontology's "JSON schema" for 6 fixed
@@ -1193,6 +1212,61 @@ export function resolveActionTypes(registry) {
   return resolveActionTypesAgainst({ registry, codeTable: ACTION_REGISTRY });
 }
 
+// `describeActionSchema` — read-only resolution of ONE action type's EFFECTIVE payload
+// schema for `phronesis act <type> --schema` (change 0045). It reads the SAME
+// `.phronesis/registry.json` action-type table the action core validates against (so it
+// reflects any operator schema tightening, not just the code defaults) and returns plain,
+// deep-copied data the CLI formats. No write, no event, no approval — a caller reads the
+// payload contract instead of learning it by submitting empty payloads. All install/
+// registry access lives here so the `act` adapter stays a pure parse-and-delegate surface
+// (validate-actions D7b). Returns a discriminated result:
+//   { status: 'error', message }            install not found / registry unreadable
+//   { status: 'invalid-registry', errors }  the action layer is disabled (all-or-nothing)
+//   { status: 'unknown-type', type, knownTypes, isCodeType }
+//   { status: 'ok', type, source, fields }   fields: [{ name, kind, required, nonEmpty, values? }]
+export async function describeActionSchema({ dir, cwd, type } = {}) {
+  const installed = resolveInstall({ dir, cwd });
+  if (installed.error) return { status: 'error', message: installed.error };
+  const installRoot = installed.root;
+
+  let registry;
+  try {
+    registry = await fse.readJson(join(installRoot, '.phronesis', 'registry.json'));
+  } catch (err) {
+    return {
+      status: 'error',
+      message: `could not read the install registry (.phronesis/registry.json): ${err.message}`,
+    };
+  }
+
+  const { errors, source, effective } = resolveActionTypes(registry);
+  if (errors.length) return { status: 'invalid-registry', errors };
+
+  // Own-property check, never a truthy prototype-chain lookup (the repo convention for
+  // name-keyed JSON maps): `act constructor --schema` / `toString` / `__proto__` must be
+  // unknown types, not Object.prototype members wearing a trench coat that reach the OK
+  // path with an empty field list.
+  if (!Object.hasOwn(effective, type)) {
+    return {
+      status: 'unknown-type',
+      type,
+      knownTypes: Object.keys(effective).sort(),
+      isCodeType: Object.hasOwn(ACTION_REGISTRY, type),
+    };
+  }
+  const entry = effective[type];
+
+  // Plain, deep-copied field-spec list — no live reference to the code table escapes.
+  const fields = Object.entries(entry.schema || {}).map(([name, spec]) => ({
+    name,
+    kind: spec.kind,
+    required: spec.required === true,
+    nonEmpty: spec.nonEmpty === true,
+    ...(spec.values !== undefined ? { values: [...spec.values] } : {}),
+  }));
+  return { status: 'ok', type, source, fields };
+}
+
 // --- Permission gate (D5 — detective; specs/trust-scopes.md Scope 1) ------------------
 
 export function permissionGate(permission, { exists = false, approvalSource } = {}) {
@@ -1217,9 +1291,12 @@ export function permissionGate(permission, { exists = false, approvalSource } =
 // --- Execution-context resolution (D10) -----------------------------------------------
 
 // Resolve the active domain: explicit ctx.domain, else the domains/{slug}/ the cwd sits
-// in, else DEFAULT_DOMAIN — and the resolved slug MUST be in the install registry. An
-// unregistered domain refuses; an action must never conjure a phantom domains/{slug}/
-// tree as a side effect (the event-log --dir fail-closed lesson, applied to domains).
+// in, else the sole registered domain (core-0061 D4 — the old DEFAULT_DOMAIN "pm" fallback
+// was wrong for every single-domain install not named pm) — and the resolved slug MUST be
+// in the install registry. With no signal and several domains registered, refuse and list
+// them; with none registered, refuse. An unregistered domain refuses; an action must never
+// conjure a phantom domains/{slug}/ tree as a side effect (the event-log --dir fail-closed
+// lesson, applied to domains).
 // The registry is read ONCE per runAction (it also carries action_types since T2.4)
 // and passed in parsed. EXPORTED since core-0014: the retrieval surface (search.js)
 // resolves its default scope through this exact function — one resolver, two consumers
@@ -1231,9 +1308,21 @@ export function resolveDomain({ installRoot, registry, domain, cwd }) {
     const parts = relative(installRoot, resolve(cwd)).split(sep);
     if (parts[0] === 'domains' && parts[1]) slug = parts[1];
   }
-  if (!slug) slug = DEFAULT_DOMAIN;
 
   const registered = Array.isArray(registry.domains) ? registry.domains : [];
+  // No explicit --domain and cwd not inside a domains/<slug>/ tree: the sole registered
+  // domain wins (core-0061 D4). The install's one domain is the unambiguous default; the old
+  // "pm" literal defaulted a business install onto a phantom domain and refused. Several
+  // registered → cannot guess; refuse and list them so the caller picks with --domain. One
+  // resolver, every domain-scoped verb inherits (lint, search, query, ingest, act, …).
+  if (!slug) {
+    if (registered.length === 1) return registered[0];
+    throw new Error(
+      registered.length === 0
+        ? 'no domain specified and none are registered in this installation. Refusing — actions never create a domain as a side effect.'
+        : `no domain specified and this installation has ${registered.length} registered (${registered.join(', ')}). Pass --domain <slug> to choose one.`,
+    );
+  }
   if (!registered.includes(slug)) {
     throw new Error(
       `domain "${slug}" is not registered in this installation (registered: ${registered.join(', ') || 'none'}). Refusing — actions never create a domain as a side effect.`,
@@ -1248,7 +1337,7 @@ export function resolveDomain({ installRoot, registry, domain, cwd }) {
 //   dir              explicit install dir (marker-checked; optional)
 //   cwd              where the caller runs (install/domain discovery; default process.cwd())
 //   session          REQUIRED — session_id on both events
-//   domain           explicit domain slug (else cwd-derived, else DEFAULT_DOMAIN; D10)
+//   domain           explicit domain slug (else cwd-derived, else the sole registered domain; D10 / core-0061 D4)
 //   actor / surface  event identity (defaults: agent / cli, like `event emit`)
 //   invocation_id    attribution provenance supplied by a skill adapter or controlled
 //                    harness; caller-controlled metadata, never authority
@@ -1277,6 +1366,10 @@ export async function runAction({ type, payload = {}, ctx = {} } = {}) {
       ? ctx.invocation_id
       : undefined;
   const now = ctx.now || new Date();
+  // OPTIONAL cancel signal (Codex R6 F1): a surface may pass ctx.signal to close the TOCTOU window —
+  // re-checked immediately before each durable write. Absent ⇒ no check (backward-compatible).
+  // Named cancelSignal to avoid colliding with the approval-signal boolean below.
+  const cancelSignal = ctx.signal;
 
   // invocation_id is execution-context provenance, not action semantics. A model can
   // place arbitrary JSON in payload, so discard a payload-supplied value before schema
@@ -1452,6 +1545,7 @@ export async function runAction({ type, payload = {}, ctx = {} } = {}) {
   // The draft overwrites any prior candidate at this path (idempotent convergence: an
   // identical re-draft re-fires the same candidate, no new canonical state).
   if (built.draft) {
+    if (cancelSignal?.aborted) throw abortedError(type); // R6 F1: no draft write lands after a cancel
     await stageValidateRename({
       installRoot,
       relPath: built.draft.writeRelPath,
@@ -1488,13 +1582,14 @@ export async function runAction({ type, payload = {}, ctx = {} } = {}) {
       // Same "WAS written, but the audit failed" guarantee as the committed path: the
       // draft already landed; say so plainly so a re-run is an idempotent re-draft, not a
       // blind retry into a confusing state.
-      throw new Error(
+      throw postWriteError(
         `${type}: the draft WAS written to ${built.draft.writeRelPath}, but the compile.candidate audit event failed to append: ${err.message}`,
       );
     }
     return { ok: true, path: built.draft.writeRelPath, draft: true, changes_summary: built.changesSummary };
   }
 
+  if (cancelSignal?.aborted) throw abortedError(type); // R6 F1: no canonical write lands after a cancel
   if (built.writes) {
     if (built.writes.length) await stageValidateRenameAll({ installRoot, writes: built.writes });
   } else {
@@ -1539,10 +1634,13 @@ export async function runAction({ type, payload = {}, ctx = {} } = {}) {
       now,
     });
   } catch (err) {
+    if (wrote.length) {
+      throw postWriteError(
+        `${type}: the artifact WAS written to ${wrote.join(' and ')}, but the action_type.committed audit event failed to append: ${err.message}`,
+      );
+    }
     throw new Error(
-      wrote.length
-        ? `${type}: the artifact WAS written to ${wrote.join(' and ')}, but the action_type.committed audit event failed to append: ${err.message}`
-        : `${type}: the run was a no-op (nothing written), but the action_type.committed audit event failed to append: ${err.message}`,
+      `${type}: the run was a no-op (nothing written), but the action_type.committed audit event failed to append: ${err.message}`,
     );
   }
 
@@ -1559,19 +1657,25 @@ export async function runAction({ type, payload = {}, ctx = {} } = {}) {
       event: committedEvent,
     });
   } catch (err) {
+    if (wrote.length) {
+      throw postWriteError(
+        `${type}: the artifact WAS written to ${wrote.join(' and ')}, but hook execution after action_type.committed failed: ${err.message}`,
+      );
+    }
     throw new Error(
-      wrote.length
-        ? `${type}: the artifact WAS written to ${wrote.join(' and ')}, but hook execution after action_type.committed failed: ${err.message}`
-        : `${type}: the run was a no-op (nothing written), but hook execution after action_type.committed failed: ${err.message}`,
+      `${type}: the run was a no-op (nothing written), but hook execution after action_type.committed failed: ${err.message}`,
     );
   }
   if (committedHooks.gateFailures.length) {
     const f = committedHooks.gateFailures[0];
     const detail = `${f.error}${f.stderrTail ? ` — ${f.stderrTail.trim()}` : ''}`;
+    if (wrote.length) {
+      throw postWriteError(
+        `${type}: the artifact WAS written to ${wrote.join(' and ')}, but gate hook "${f.id}" failed at action_type.committed: ${detail} (audited in .phronesis/audit.log; the write is not rolled back)`,
+      );
+    }
     throw new Error(
-      wrote.length
-        ? `${type}: the artifact WAS written to ${wrote.join(' and ')}, but gate hook "${f.id}" failed at action_type.committed: ${detail} (audited in .phronesis/audit.log; the write is not rolled back)`
-        : `${type}: the run was a no-op (nothing written), but gate hook "${f.id}" failed at action_type.committed: ${detail} (audited in .phronesis/audit.log)`,
+      `${type}: the run was a no-op (nothing written), but gate hook "${f.id}" failed at action_type.committed: ${detail} (audited in .phronesis/audit.log)`,
     );
   }
 

package/vendor/core/src/index.js

@@ -55,9 +55,12 @@ export {
   CONVERGENT_COMMITTED_HOOKS,
   defaultActionTypesSection,
   resolveActionTypes,
+  describeActionSchema,
   resolveDomain,
 } from './actions.js';
 
+export { matchFrontmatterBlock } from './workspace-scan.js';
+
 export {
   buildActiveContextProjection,
   refreshActiveContext,