cyber-aced 0.4.0 → 0.4.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
 	"name": "aced",
-	"version": "0.4.0",
+	"version": "0.4.2",
 	"description": "Agent Config Evaluation & Development. Spec, evaluate, and improve agent configurations: skills, AGENTS.md sections, subagent definitions, and commands.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://raw.githubusercontent.com/cyberuni/marketplace/main/schema/claude/plugin.json",
 	"name": "aced",
-	"version": "0.4.0",
+	"version": "0.4.2",
 	"description": "Agent Config Evaluation & Development. Spec, evaluate, and improve agent configurations: skills, AGENTS.md sections, subagent definitions, and commands.",
 	"author": {
 		"name": "unional"

package/.plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://raw.githubusercontent.com/cyberuni/marketplace/main/schema/claude/plugin.json",
 	"name": "aced",
-	"version": "0.4.0",
+	"version": "0.4.2",
 	"description": "Agent Config Evaluation & Development. Spec, evaluate, and improve agent configurations: skills, AGENTS.md sections, subagent definitions, and commands.",
 	"author": {
 		"name": "unional"

package/agents/aced-impl-judge.md

@@ -19,7 +19,7 @@ The **impl-judge** for agent-configuration domain types — it grades the **buil
 ## Input
 
 ```
-DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH
+DOMAIN, DOMAIN_PATH, SPEC_PATH, FEATURE_PATH: the domain under work, its spec folder, its spec.md, and its .feature
 IMPLEMENTATION_PATHS:  the agent configuration under evaluation (the SUBJECT)
 VERIFICATION_PATHS:    the frozen .feature (the eval source) + eval.md (run policy only)
 ```
@@ -28,9 +28,9 @@ VERIFICATION_PATHS:    the frozen .feature (the eval source) + eval.md (run poli
 
 1. **Read the frozen `.feature` as the eval source.** Enumerate its scenarios in file order. Each scenario carries its own eval: a `@rubric` scenario's inline rubric docstring (named dimensions + `max` + `threshold`), a `@trigger` `Scenario Outline`'s `Examples` rows, or a deterministic boolean `Then`. You **run** it, you do not author it. A `@rubric` scenario whose inline rubric block is **absent** is a `BLOCKER` — you do not free-author the missing rubric.
 
-2. **Set the run policy from `eval.md`.** Read the run policy under the `eval:` block: `eval.trigger.{runs, activation_threshold}` for `@trigger` scenarios; `eval.judge.model` and `eval.judge.default_threshold` for `@behavior`/`@quality` scenarios (an inline `threshold` in a `@rubric` docstring overrides the default). Defaults when `eval.md` omits them: judge model `claude-sonnet-4-6`, default_threshold 4, trigger activation_threshold 0.5, trigger runs 3.
+2. **Set the run policy from `eval.md`.** Read the run policy under the `eval:` block: `eval.trigger.{runs, activation_threshold}` for `@trigger` scenarios; `eval.judge.model` and `eval.judge.default_threshold` for `@behavior`/`@quality` scenarios (an inline `threshold` in a `@rubric` docstring overrides the default). Defaults when `eval.md` omits them: judge model the session's current model, default_threshold 4, trigger activation_threshold 0.5, trigger runs 3.
 
-3. **Run the evals.** For each scenario, invoke `aced-case-judge` with the SUBJECT, the **`.feature` path and the scenario name**, and its threshold, over its run count — for a `@trigger` `Scenario Outline`, **once per `Examples` row**, passing its zero-based `ROW` (one row is one case; the judge reports one invoke decision, and aggregating accuracy across rows is yours). **Never pass the scenario's steps, its `Then`, or its rubric** — the judge blinds its own simulating context (composing that context's brief with the `extract-situation` engine) and scores the returned transcript in a separate one; handing it the scenario body would put the answer key back in the context that has to reach the answer. One invocation covers both passes; never sequence them here. It returns a score per named dimension against that dimension's own `max`, plus a total. Aggregate the totals across runs.
+3. **Run the evals.** For each scenario, invoke `aced-case-judge` with the SUBJECT, the **`.feature` path and the scenario name**, and its threshold, over its run count — for a `@trigger` `Scenario Outline`, **once per `Examples` row**, passing its zero-based `ROW` (one row is one case; the judge reports one invoke decision, and aggregating accuracy across rows is yours). **Never pass the scenario's steps, its `Then`, or its rubric** — the judge blinds its own simulating context (composing that context's brief with the `extract-situation` engine) and scores the returned transcript in a separate one; handing it the scenario body would put the answer key back in the context that has to reach the answer. One invocation covers both passes; never sequence them here. It returns a score per named dimension against that dimension's own `max`, plus a total. Aggregate the totals across runs. <!-- field-mandate-ignore: ROW is aced-case-judge's input, which this judge constructs -->
 
    **Wait for each case judge, and bank only its last word.** Dispatching a case judge is asynchronous, and the case judge is itself waiting on its own blind simulator — so a judge can report before its measurement exists and correct itself afterwards. Two rules follow. **Only the final notification per agent id is trustworthy**: when an agent reports more than once, the later report supersedes the earlier one entirely — never bank the first and never merge them. And **a verdict is a result only when the agent has finished**: do not collapse to boolean or roll up `IMPLEMENTATION_PASS` while any dispatched case judge is still live. If a run ends with cases still outstanding, that is `STATUS: needs-input` with those scenarios named — not a pass and not a fail.
 

package/agents/aced-scenario-writer.md

@@ -30,7 +30,7 @@ Before writing anything, classify the subject's fit tier (`aced:aced-fit`) and *
 ## Input
 
 ```
-DOMAIN, DOMAIN_PATH, SPEC_PATH
+DOMAIN, DOMAIN_PATH, SPEC_PATH: the domain under work, its spec folder, and its spec.md
 SUBJECT:          <full text of the agent configuration under spec, or null for a new one>
 COMMAND_SURFACE:  <the configuration's trigger surface / interface — or null>
 DESIGN_DECISIONS: <known choices — or null>
@@ -56,7 +56,7 @@ USER_ANSWERS:     <answers to previously returned QUESTIONS — or null>
    - **Select the form before you grade it — the substitutability test.** A `@rubric` is a **compensatory** model (strength on one dimension pays for weakness on another), so a criterion belongs in one **only if** it is **substitutable**: only if you accept that trade — *"great scope makes up for shipping an npx dependency"* is a trade nobody accepts, so `no_npx_dependency` is a boolean `Then`, not a dimension. A rule graded as a dimension becomes **tradeable**, which is the one thing a rule must never be, and no threshold repairs it. Split a **double-barreled** dimension (`harness_agnostic_and_mcp_free`) before selecting — its halves routinely land in different forms. **Write the trade down** for each dimension you author or revise, in the same record that carries the cut's reason, naming it and **what pays for it** — a trade nobody wrote is one nobody can disagree with. The duty is **yours alone**: no judge reports a missing record, so nothing catches you skipping it. **Keep a property a boolean scenario in the suite already decides out of the rubric** — author it as the boolean only, never both; scoring it as a dimension too smuggles an untradeable rule into the compensatory sum (the boolean-smuggling tell: if your rubrics begin restating booleans, the boundary was set too high). This is a **same-object** check, not same-criterion: two dimensions may share a criterion with no boolean twin deciding either without either being a smuggled boolean.
    - **Ask the span question before the trade question — a whole-output criterion is untradeable by construction.** When a graded criterion covers **the whole of what the subject produces** (a persona's voice, the fitness of the artifact as a whole), there is no *rest of the output* left to pay for weakness in it, so the compensatory sum has nothing to trade against. Author it as **one boolean `@quality` scenario**, never as a dimension — and never go hunting for a boolean twin the suite does not have; the same-object check above requires one, this does not. `@quality` names the **result axis** while `@rubric` is the orthogonal, optional **assertion form**, so a boolean `@quality` scenario is ordinary boolean Gherkin, not a new form. The boolean is strictly **stronger**: the gate requires every scenario to pass, so the property cannot be zeroed and bought back on unrelated points the way a dimension can. Do not let *"but it is graded, so it must be a `@rubric` dimension"* route you past this — that inference is exactly what failed. **The test is monadic:** read the single criterion against the output and ask *can I name an attribute of the output this criterion does not touch?* If you can, it is per-attribute and stays a dimension. Sibling dimensions tell you how the **output decomposes**; they are never what you compare the criterion against. Because span is asked **first**, a whole-output criterion authored alongside per-attribute siblings does not make the case ambiguous — the spanning one becomes the boolean and the siblings stay dimensions. A whole-output-*sounding* name (`coherence`, `clarity`, `overall_quality`) is not the test: judge what the dimension **scores**, not how broadly it is worded.
    - **Read your scenarios against each other before returning.** No two sharing a `When` may demand opposite verdicts on one constructible snapshot; narrow one `Given` to exclude the overlap. Overlap whose `Then`s agree, and scenarios whose `When`s name different operations, are not contradictions.
-   - **On a backfill, re-derive the scenario set from the CFG's edges** — one per `(path class, edge)` pair, every guard paired with a positive companion — rather than reading the standing `.feature` and patching the gaps a diff notices. Any pre-existing suite or retired golden set is **reference only**: a claim to verify against the current configuration, never the baseline to patch (`sdd:suite-format-governance`, ADR-0029).
+   - **On a backfill, re-derive the scenario set from the CFG's edges** — one per `(path class, edge)` pair, every guard paired with a positive companion — rather than reading the standing `.feature` and patching the gaps a diff notices. Any pre-existing suite or retired golden set is **reference only**: a claim to verify against the current configuration, never the baseline to patch (`sdd:suite-format-governance`).
 
 4. **Pre-flight before you freeze.** Before returning the `spec.md` + `.feature`, run the produce-time pre-flight — the cheap check that stops a wrong assumption from being frozen into an already-shipped suite:
    - **Ground every asserted harness/tool behavior in the harness's own primary docs.** When a `Then` (or the `spec.md`) asserts *how a harness or tool behaves* — a flag's effect, what a field controls, when a mechanism fires — confirm it against the harness's own primary documentation before freezing. Never assert harness behavior from memory; a wrong assumption frozen into a scenario forces a re-open of a shipped suite.

package/agents/aced-spec-validator.md

@@ -24,7 +24,7 @@ The per-scenario **Checks** below are the `aced:aced-builder-spec` bar (its cano
 ## Input
 
 ```
-DOMAIN, DOMAIN_PATH, FEATURE_PATH, SPEC_PATH
+DOMAIN, DOMAIN_PATH, FEATURE_PATH, SPEC_PATH: the domain under work, its spec folder, its .feature, and its spec.md
 SUBJECT:  <full text of the agent configuration under spec, or null>
 ```
 

package/governances/README.md

@@ -48,5 +48,5 @@ rationale belong in ADRs and research dossiers.
 Owned elsewhere and referenced from these documents: `plugin-design`, `slash-invocation`, and
 `universal-plugin` ship from the `universal-plugin` package.
 
-See [ADR-0035](../../../docs/adr/0035-authored-governances-ship-as-package-files.md) for why these
+See [ADR-0035](https://github.com/cyberuni/cyber-sdd/blob/main/docs/adr/0035-authored-governances-ship-as-package-files.md) for why these
 ship as package files rather than as governance skills.

package/governances/skill-design.md

@@ -123,8 +123,10 @@ When a skill includes `scripts/` or documents CLI commands agents run, load **ag
 ### Frontmatter
 
 - `name` must match the parent directory name exactly.
-- `description` must contain `"Use this skill when"` or `"When to use"` trigger language — **unless the skill is name-only**, whose `description` is exactly `"By name only"` and carries no trigger language at all.
-- Keep `description` ≤120 characters — long descriptions are truncated in the agent context window.
+- `description` of a situationally triggered skill states what the skill does, then when it applies — the situations, requests, and implicit phrasings that should select it. Lead with the capability, in third person.
+- Do not open the `description` with a fixed lead-in such as `"Use this skill when"` or `"When to use"`. A trigger clause after the capability (`"… Use when …"`) is fine; no particular phrase is required.
+- A **name-only** skill's `description` is exactly `"By name only"` and carries no capability or trigger text at all.
+- Keep `description` ≤1024 characters — the agentskills.io hard limit. Put the capability and the main triggers first; listings may truncate the tail.
 - `compatibility` — optional; declare environment constraints (required tools, network access, OS, runtime version). Include only when the skill has requirements the agent cannot assume.
 
 #### Runtime fields
@@ -180,7 +182,7 @@ The `activation` field belongs in **SKILL.md frontmatter** as a **top-level fiel
 ---
 name: my-skill
 activation: per-situation
-description: "Use this skill when..."
+description: "<what it does>. Use when <situations>."
 ---
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyber-aced",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Agent Config Evaluation & Development. Spec, evaluate, and improve agent configurations: skills, AGENTS.md sections, subagent definitions, and commands.",
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
     "!skills/**/*.test.mts"
   ],
   "dependencies": {
-    "@cyberuni/agent-harness": "0.5.0"
+    "@cyberuni/agent-harness": "0.6.0"
   },
   "publishConfig": {
     "access": "public"

package/skills/aced-architect-impl/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aced-architect-impl
-description: "Partial Skill: invoke by name only — the ACED Architect bar at the impl gate — whether an agent-configuration artifact is well-formed as configuration. Loaded by the ACED impl-producer to self-align and by the impl-judge to grade. Not triggered by users directly."
+description: "By name only"
 user-invocable: false
 metadata:
   actor: architect

package/skills/aced-builder-impl/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aced-builder-impl
-description: "Partial Skill: invoke by name only — the ACED Builder bar at the impl gate — the frozen .feature conformance criteria. Loaded by the ACED impl-producer to self-align and by the impl-judge to verify. Not triggered by users directly."
+description: "By name only"
 user-invocable: false
 metadata:
   actor: builder
@@ -29,7 +29,7 @@ agent level.
 - **Run policy is explicit — from `eval.md`.** Read the `eval:` block: `@trigger` scenarios run
   `eval.trigger.runs` against `eval.trigger.activation_threshold` (accuracy); `@behavior`/`@quality`
   scenarios run N times against the scenario's inline `threshold` (else `eval.judge.default_threshold`),
-  scored by `eval.judge.model`. Defaults when omitted: model claude-sonnet-4-6, default_threshold 4,
+  scored by `eval.judge.model`. Defaults when omitted: model the session's current model, default_threshold 4,
   trigger activation_threshold 0.5, trigger runs 3.
 - **Collapse to a boolean.** A scenario passes when its aggregate **total across the rubric's named
   dimensions** ≥ `threshold` and no must-not-do was triggered (trigger scenarios: accuracy ≥

package/skills/aced-builder-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aced-builder-spec
-description: "Partial Skill: invoke by name only — the ACED Builder bar at the spec gate — the agent-configuration contract criteria. Loaded by the ACED spec-producer to self-align and by the spec-judge to grade. Not triggered by users directly."
+description: "By name only"
 user-invocable: false
 metadata:
   actor: builder
@@ -78,8 +78,8 @@ bar. Two criteria below are **conditional on tier**; a **missing** `**Fit:**` de
     - **The test is monadic.** Read the **single** criterion against the output: *can you name an
       attribute of the output this criterion does not touch?* If you can, it is per-attribute and stays
       a dimension. Sibling dimensions are evidence of how the **output decomposes** — never the object
-      of the comparison. Comparing one candidate dimension against another is the twin-scan #280
-      rejected, on this ground exactly as much as on Ground 2.
+      of the comparison. Comparing one candidate dimension against another is the twin-scan the
+      suite format rejects, on this ground exactly as much as on Ground 2.
     - **Span is checked before substitutability.** A whole-output criterion never reaches the trade
       question. So when one is authored **alongside** per-attribute siblings — the shape the
       persona-voice recurrence actually took — the span ruling governs the spanning criterion and the
@@ -99,9 +99,8 @@ bar. Two criteria below are **conditional on tier**; a **missing** `**Fit:**` de
     `only` bounds Ground 2's own test, not selection as a whole, so it never licenses passing a
     criterion that fails Ground 1. Two `@rubric` dimensions that merely
     **share a criterion**, with no boolean twin deciding either, do **not** fail selection for sharing
-    it — comparing two dimensions to each other is the twin-scan SDD issue #280 rejected (reconciled in
-    `design/decisions/0002-boundary-vs-surface-more.md`); #280's discrimination verdict (noise, not a
-    hole) and this Selection verdict (a smuggled boolean, out of the sum) are orthogonal reads of one
+    it — comparing two dimensions to each other is the twin-scan the suite format rejects; the
+    discrimination verdict (noise, not a hole) and this Selection verdict (a smuggled boolean, out of the sum) are orthogonal reads of one
     dimension.
 - **Discrimination** *(all tiers; every scenario and every `@rubric` dimension).* Each must be able
   to **register a miss** — a plausible wrong config must fail it, or score below the dimension's
@@ -126,5 +125,5 @@ bar. Two criteria below are **conditional on tier**; a **missing** `**Fit:**` de
   Validate-section coverage requires a scenario for.
 - `sdd:suite-format-governance` — the miss test, the wrong-subject table, the three anti-patterns,
   the substitutability test, and the pairwise-consistency rule this bar specializes.
-- `design/decisions/0002-boundary-vs-surface-more.md`, `design/test-levels.md` — the boolean-smuggling
-  tell and the SDD #280 reconciliation (same-object, not same-criterion) the Selection bullet encodes.
+- `design/test-levels.md` — the boolean-smuggling tell and the same-object, not same-criterion,
+  reconciliation the Selection bullet encodes.

package/skills/aced-fit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aced-fit
-description: "Partial Skill: invoke by name only — the ACED fit classifier — which of ACED's eval layers carry real signal for a subject. Loaded by the ACED spec-producer and the spec-judge. Not triggered by users directly."
+description: "By name only"
 user-invocable: false
 metadata:
   type: governance
@@ -35,7 +35,7 @@ name-only description) makes no activation decision, so it is never `strong`.
 ## How each role uses it
 
 - **`aced-scenario-writer` (producer, explore) — decides.** Classify fit **first**; declare it as a
-  `**Fit:** strong | partial` line in the subject's node spec (its `README.md`) `## Use Cases`. Then author to the tier:
+  `**Fit:** strong | partial` line in the subject's node spec (its `spec.md`) `## Use Cases`. Then author to the tier:
   `strong` → author should-trigger + same-keyword near-miss; `partial` → author behavior/edge/rule,
   **no fabricated near-miss**; `wrong-squad` → **recuse**, produce nothing, recommend the SDD default.
 - **`aced-spec-validator` (judge, gate) — enforces.** Read the declared tier; apply trigger-context /
@@ -83,7 +83,7 @@ is **not** a `CONTENT_GAP` (unlike the tier's).
 Assertions about **the subject being classified**, run by the producer before handoff and re-run by
 the cold judge against the artifact — never against the producer's account of what it did:
 
-1. The subject's node spec (`README.md`) carries exactly one `**Fit:** strong` or `**Fit:** partial`
+1. The subject's node spec (`spec.md`) carries exactly one `**Fit:** strong` or `**Fit:** partial`
    line; a subject recused as wrong-squad has neither a `**Fit:**` line nor an ACED
    `eval.md` (its node, if any, was written by the SDD-default chain). *(mechanical)*
 2. A subject declared `strong` does not have a name-only description (one beginning `By name only`
@@ -98,8 +98,7 @@ the cold judge against the artifact — never against the producer's account of
 
 ## References
 
-- `design/fit.md` (`.agents/specs/aced/design/fit.md`) — the normative model + ADR 0001 (tier) and
-  ADR 0003 (measured axis).
+- `design/fit.md` (`.agents/specs/aced/design/fit.md`) — the normative model (tier and measured axis).
 - `aced:aced-builder-spec` — the spec bar whose trigger-context / trigger-balance criteria this
   governance makes conditional.
 - `aced:aced-builder-impl` — the impl bar (which eval layers get evals follows the tier).

package/skills/aced-impl-producer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aced-impl-producer
-description: "Partial Skill: invoke by name only — the ACED impl-producer's diagnose-and-refine loop — loaded by define-agent, define-skill, and define-governance, and by the public improve skill for ACED-tracked targets, not user-triggered."
+description: "By name only"
 user-invocable: false
 metadata:
   actor: producer
@@ -13,7 +13,7 @@ Diagnose failing eval cases and propose targeted edits to the target agent confi
 
 ## Role: the ACED impl-producer
 
-When the conductor dispatches `define-agent`, `define-skill`, or `define-governance` as a generic builder (`produced-by sdd:automaton`) for the **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **agent configuration** to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline `@rubric` scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore and frozen at the spec gate — so the impl-producer does **not** author a separate eval suite. As impl-producer it self-aligns to `sdd:ownership-governance` plus the resolved **builder-impl + architect-impl** bars (the ACED builder-impl is `aced:aced-builder-impl`). When the **impl-judge** (`aced-impl-judge`) reports scenario failures, load this skill to run the diagnose-and-refine loop below. Independence holds because the evals are anchored to the frozen `.feature` and executed by a separate runner (`aced-case-judge`), which is not the producer.
+When the conductor dispatches `define-agent`, `define-skill`, or `define-governance` as a generic builder (`produced-by sdd:sdd-automaton`) for the **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **agent configuration** to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline `@rubric` scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore and frozen at the spec gate — so the impl-producer does **not** author a separate eval suite. As impl-producer it self-aligns to `sdd:ownership-governance` plus the resolved **builder-impl + architect-impl** bars (the ACED builder-impl is `aced:aced-builder-impl`). When the **impl-judge** (`aced-impl-judge`) reports scenario failures, load this skill to run the diagnose-and-refine loop below. Independence holds because the evals are anchored to the frozen `.feature` and executed by a separate runner (`aced-case-judge`), which is not the producer.
 
 ## Load context
 
@@ -23,7 +23,7 @@ and its colocated `eval.md` (subject + run policy):
 - Read `eval.md` for the `subject` agent configuration path and the `eval:` run policy
 - Read the `subject` agent configuration in full
 - Read the frozen `<node>.feature` (the eval source)
-- Read the most recent result file from `results/` (sort by filename descending, take first)
+- Read the most recent result file from `.agents/aced/results/<target-slug>/` (sort by filename descending, take first)
 
 If no results exist, run `run` first.
 
@@ -54,7 +54,7 @@ For each pattern, propose a concrete change to the agent configuration. Show exa
 Examples of edit types:
 
 - **Trigger false-positive/negative** → rewrite the `description:` field; add explicit "when NOT to use" section
-- **Missing step** → make the step more prominent; add a concrete example; break it into sub-steps
+- **Missing step** → state the step and why it matters; break it into sub-steps if it is compound
 - **Ambiguous rule** → replace vague language ("prefer X") with decision rule ("use X when Y, use Z when W")
 - **Conflicting instruction** → add explicit precedence rule or split into separate instructions
 - **Description mismatch** → align `description:` to match what the body actually instructs

package/skills/check-freshness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-freshness
-description: "Partial Skill: invoke by name only — the ACED eval-result freshness check — decides whether a recorded result still describes the configuration on disk, not user-triggered."
+description: "By name only"
 user-invocable: false
 metadata:
   internal: true
@@ -70,7 +70,7 @@ about what it measured.
 
 **Trust boundary.** `evaluated` is what the run **reports** consuming, not a verified trace. An
 under-reporting run records a shorter set whose entries all match, and this answers `current` with
-full confidence — a silent failure pointing the unsafe way (`#475`). What is checkable is
+full confidence — a silent failure pointing the unsafe way. What is checkable is
 **coherence**: a set omitting the `.feature` whose scenarios the record scores, or the configuration
 its own `target` names, contradicts the record it accompanies and reads `absent`. That catches only
 an *inconsistent* under-reporter; a uniform one escapes.
@@ -81,8 +81,7 @@ it should have" is not, and this engine never claims the second.
 ## Boundaries
 
 Scores nothing (`run`), compares no two versions (`compare`), rolls nothing up (`report`), and does
-not judge whether a recorded *pass* was well-founded (a judge-protocol question, `#477`). It decides
-a verdict and reports it; **what a caller does with that verdict is the caller's** — wiring `run` and
-`improve` to consult it is `#476`.
+not judge whether a recorded *pass* was well-founded (a judge-protocol question). It decides
+a verdict and reports it; **what a caller does with that verdict is the caller's**.
 
 Spec: `.agents/specs/aced/eval-run/check-freshness/`.

package/skills/define-agent/SKILL.md

@@ -7,7 +7,7 @@ description: 'Use this skill when the user wants to create or improve an agent d
 
 Create or improve an agent definition — a named role encoded in a single file.
 
-When the conductor dispatches this skill as a generic builder (`produced-by sdd:automaton`) for the ACED **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **agent definition** to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline `@rubric` scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore — so no separate eval suite is authored here; `eval.md` carries only the `subject` binding and run policy. As impl-producer it self-aligns to `sdd:ownership-governance` plus the resolved **builder-impl + architect-impl** bars (the ACED builder-impl is `aced:aced-builder-impl`). (Invoked standalone — no frozen `.feature` — only the agent definition is produced.) If the impl-judge reports scenario failures, load `aced-impl-producer` to run the diagnose-and-refine loop rather than re-deriving it here.
+When the conductor dispatches this skill as a generic builder (`produced-by sdd:sdd-automaton`) for the ACED **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **agent definition** to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline `@rubric` scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore — so no separate eval suite is authored here; `eval.md` carries only the `subject` binding and run policy. As impl-producer it self-aligns to `sdd:ownership-governance` plus the resolved **builder-impl + architect-impl** bars (the ACED builder-impl is `aced:aced-builder-impl`). (Invoked standalone — no frozen `.feature` — only the agent definition is produced.) If the impl-judge reports scenario failures, load `aced-impl-producer` to run the diagnose-and-refine loop rather than re-deriving it here.
 
 ## First: confirm an agent definition is the right artifact
 
@@ -103,7 +103,7 @@ The canonical file lives at the canonical path. All runtime locations are symlin
 
 Ask the user:
 
-1. **Name** — kebab-case slug (e.g. `conductor`, `code-reviewer`). If the agent's role is to **score or verify a specific gate or case**, name it by that gate/scope, not a bare action verb: `<domain>-<gate>-judge` for a gate scorer (e.g. `sdd-impl-judge`, `aced-impl-judge`), `<domain>-case-judge` for a case scorer (e.g. `aces-case-judge`). Flag any gate/case scorer whose name is not in that form — bare verdict verbs (`implementer`, `judge`, `validator`, `reviewer`, `checker`) and non-verdict action names (`eval-runner`, `grader`) alike. A producer/worker agent (e.g. `scenario-writer`, `doc-writer`) keeps its action-oriented name — this convention only applies to gate/case scorers.
+1. **Name** — kebab-case slug (e.g. `conductor`, `code-reviewer`). If the agent's role is to **score or verify a specific gate or case**, name it by that gate/scope, not a bare action verb: `<domain>-<gate>-judge` for a gate scorer (e.g. `sdd-impl-judge`, `aced-impl-judge`), `<domain>-case-judge` for a case scorer (e.g. `aced-case-judge`). Flag any gate/case scorer whose name is not in that form — bare verdict verbs (`implementer`, `judge`, `validator`, `reviewer`, `checker`) and non-verdict action names (`eval-runner`, `grader`) alike. A producer/worker agent (e.g. `scenario-writer`, `doc-writer`) keeps its action-oriented name — this convention only applies to gate/case scorers.
 2. **Role** — one sentence: "You are a [seniority] [role] focused on [bounded concern]."
 3. **Responsibilities** — what does this agent do? (3–6 bounded concerns)
 4. **Output format** — what does it produce? (file, report, JSON, confirmation, etc.)

package/skills/define-command/SKILL.md

@@ -8,7 +8,7 @@ description: 'Use this skill when the user wants to create or improve a command
 Create or improve a **command** — a workflow the user invokes explicitly via `/name`, never
 triggered automatically by the model.
 
-When the conductor dispatches this skill as a generic builder (`produced-by sdd:automaton`) for the
+When the conductor dispatches this skill as a generic builder (`produced-by sdd:sdd-automaton`) for the
 ACED **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **command
 file** to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline
 `@rubric` scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore — so no
@@ -51,7 +51,7 @@ harnesses to target if not stated):
 | Mechanism | File | Portability | When to pick it |
 |---|---|---|---|
 | **`commands/` folder** (legacy) | A standalone markdown file, not a `SKILL.md` | Widest support — Claude Code, and GitHub Copilot CLI (reads `.claude/commands/`); the only option for cross-harness plugin commands targeting Cursor too | Default choice; use for anything shipped in a plugin or targeting more than Claude Code |
-| **`disable-model-invocation: true`** (modern) | A `SKILL.md` with the frontmatter flag | Claude Code, Windsurf; **not** Copilot CLI, Codex CLI, or Gemini CLI; has a known Cursor bug hiding plugin-delivered skills from the `/` menu (Mar 2026) | Only when targeting Claude Code / Windsurf exclusively and the command benefits from full `SKILL.md` progressive disclosure (a `references/` or `scripts/` dir) |
+| **`disable-model-invocation: true`** (modern) | A `SKILL.md` with the frontmatter flag | Claude Code, Windsurf; **not** Copilot CLI, Codex CLI, or Gemini CLI; may not surface plugin-delivered skills in Cursor's `/` menu — verify before relying on it | Only when targeting Claude Code / Windsurf exclusively and the command benefits from full `SKILL.md` progressive disclosure (a `references/` or `scripts/` dir) |
 
 If improving an existing file, read it first and keep its current mechanism unless the user asks to
 migrate.
@@ -135,7 +135,7 @@ For the `disable-model-invocation` mechanism, run the structural audit and fix a
 finding before presenting the skill:
 
 ```bash
-npx cyberplace@0.2.4 audit validate --path <placement-dir>/<name>   # resolve <version> via: npm view cyberplace version — never @latest
+npx cyberplace@<version> audit validate --path <placement-dir>/<name>   # resolve <version> via: npm view cyberplace version — never @latest
 ```
 
 The `commands/` folder mechanism is not a `SKILL.md` — the audit tool does not apply; check by hand

package/skills/define-governance/SKILL.md

@@ -59,7 +59,7 @@ Write the file at the canonical path using this structure:
 ```markdown
 ---
 name: <name>
-description: "Partial Skill: invoke by name only — <one sentence: what domain this governs and who loads it>"
+description: "By name only"
 user-invocable: false
 metadata:
   type: governance
@@ -90,7 +90,7 @@ dimensions already are the verification.>
 
 Rules for the body:
 - Set `user-invocable: false` — the classifier for a partial skill (a governance is loaded by name, never user-triggered)
-- Lead `description` with the `"Partial Skill:"` prefix (recommended form `"Partial Skill: invoke by name only — …"`) — a self-declaration for the reader; keep it minimal and non-trigger-shaped so the harness (which still sees the description) does not auto-match it
+- Set `description` to exactly `"By name only"` — the harness still sees the description, so anything added is another handle for a spurious match; put identity and caller in the body
 - Do not include `## Why`, `## Rationale`, or causal prose — put that in ADRs
 - Encode decisions and criteria, not facts the model already knows
 - For a **Constraint set**, **Checklist**, or **Decision table** governance, write a `## Validate`

package/skills/define-skill/README.md

@@ -24,7 +24,7 @@ The skill walks you through the shape before writing anything:
 3. **Pattern** — process, tool-based, or standard (personas go to `define-agent`)
 4. **Placement** — user-global, project-private, or project-public, plus which runtime symlinks to create
 
-It then drafts the SKILL.md (kebab-case name, a 150–400 char trigger-bearing description, a step body under the size bar), adds a README for a public skill, runs the structural audit and fixes CRITICAL/HIGH findings, and points you at the ACED eval loop (`start-mission` / `add-scenario` / `run`) to spec and score it.
+It then drafts the SKILL.md (kebab-case name, a description that leads with the capability and then says when it applies, ≤1024 chars, a step body under the size bar), adds a README for a public skill, runs the structural audit and fixes CRITICAL/HIGH findings, and points you at the ACED eval loop (`start-mission` / `add-scenario` / `run`) to spec and score it.
 
 ## Enhanced from create-skill
 

package/skills/define-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: define-skill
-description: 'Use this skill when the user wants to create, scaffold, or formalize a workflow skill — a process, tool-based, or standard SKILL.md — from scratch or from an existing ad-hoc workflow. Trigger on "create a skill", "write a skill for X", "I want a skill that…", "turn this workflow into a skill", or "help me build this skill", even if they do not say "skill" explicitly. Not for agent definitions or personas (define-agent), reference-only rule sets (define-governance), or extracting the current session (skillify).'
+description: 'Creates, scaffolds, or formalizes a workflow skill — a process, tool-based, or standard SKILL.md — from scratch or from an existing ad-hoc workflow. Use when the user asks for one — "create a skill", "write a skill for X", "I want a skill that…", "turn this workflow into a skill", "help me build this skill" — even if they do not say "skill" explicitly. Not for agent definitions or personas (define-agent), reference-only rule sets (define-governance), or extracting the current session (skillify).'
 ---
 
 # Define Skill
@@ -8,7 +8,7 @@ description: 'Use this skill when the user wants to create, scaffold, or formali
 Create or improve a **workflow skill** — a process, tool-based, or standard SKILL.md — then hand it
 to the ACED eval loop to spec and score.
 
-When the conductor dispatches this skill as a generic builder (`produced-by sdd:automaton`) for the
+When the conductor dispatches this skill as a generic builder (`produced-by sdd:sdd-automaton`) for the
 ACED **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **SKILL.md**
 to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline `@rubric`
 scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore — so no separate
@@ -45,16 +45,16 @@ skill here.
 
 ## Load the governance
 
-Before writing content, load the **skill-design** governance and read stdout as the authoritative
-rules for principles, progressive disclosure, description structure, and when to extract deterministic
-logic to a script:
+Before writing content, load the **skill-design** governance as the authoritative rules for
+principles, progressive disclosure, description structure, and when to extract deterministic logic to
+a script. Read the first that exists:
 
-```bash
-npx cyberplace@0.2.4 governance show skill-design   # resolve <version> via: npm view cyberplace version — never @latest
-```
+1. `.agents/governances/skill-design.md` — a project override
+2. `references/governances/skill-design.md` in this skill — the default copy
 
 If the skill will ship a `scripts/` directory or document CLI commands agents run, also load
-**agent-tool-output** for stdout / JSON / non-interactive / stderr rules.
+**agent-tool-output** the same way (`references/governances/agent-tool-output.md`) for stdout / JSON /
+non-interactive / stderr rules.
 
 ## Settle the shape — five questions
 
@@ -129,12 +129,13 @@ description: <capability> + "Use when <trigger>" + an implicit-phrasing example
 2. <step>
 ```
 
-- **Description** — the only field loaded at startup; it carries the whole triggering burden. Target
-  150–400 characters (≤1024 hard limit): capability + "Use when…" + an implicit phrasing. For a
-  **partial skill** (a reusable part other skills call by name, not user-triggered), set
-  `user-invocable: false` and lead the description with the `"Partial Skill:"` prefix (recommended
-  form `"Partial Skill: invoke by name only — <identity>. <caller>."`), kept minimal and
-  non-trigger-shaped so it does not self-activate.
+- **Description** — the only field loaded at startup; it carries the whole triggering burden. Lead
+  with the capability, then a "Use when…" trigger clause, then an implicit phrasing. Never open with a
+  fixed lead-in such as "Use this skill when" or "When to use". Keep it ≤1024 characters, the
+  capability and main triggers first. For a
+  **name-only skill** (a reusable part other skills call by name, never matched to a situation), set
+  `user-invocable: false` and the description to exactly `"By name only"` and nothing else; identity
+  and caller go in the body.
 - **Body** — step-by-step, under 500 lines. Keep the *when* here; move any **deterministic,
   fixed-output** step to a `scripts/` file or an existing CLI and have the body only say when to run
   it.
@@ -162,11 +163,11 @@ is `improve`.
 For a subagent this skill scaffolds (realized as a partial skill, e.g. loaded via the ACED
 impl-producer/impl-judge pattern): if its role is to **score or verify a specific gate or case**,
 name it by that gate/scope, not a bare action verb — `<domain>-<gate>-judge` for a gate scorer (e.g.
-`aced-impl-judge`), `<domain>-case-judge` for a case scorer (e.g. `aces-case-judge`). Reject
+`aced-impl-judge`), `<domain>-case-judge` for a case scorer (e.g. `aced-case-judge`). Reject
 `implementer`, `judge`, `validator`, `reviewer`, `checker` alone. A producer subagent (e.g.
 `scenario-writer`, `doc-writer`) keeps its action-oriented name — this check does not fire for it.
 
-Evaluate this **in-skill quality check** — separate from the mechanical `audit validate` below — before
+Evaluate this **in-skill quality check** — separate from the mechanical structural audit below — before
 handing the skill back: a drafted gate/case scorer named with a bare action verb is a **HIGH** severity
 finding; fix it (rename to the gate-and-scope form) before presenting the skill.
 
@@ -175,9 +176,11 @@ finding; fix it (rename to the gate-and-scope form) before presenting the skill.
 Run the structural audit and fix any CRITICAL or HIGH finding **before** presenting the skill:
 
 ```bash
-npx cyberplace@0.2.4 audit validate --path <placement-dir>/<name>
+node "<improve-skill>/scripts/validate.mts" --path <placement-dir>/<name>
 ```
 
+Replace `<improve-skill>` with the directory of the `improve-skill` skill installed beside this one.
+
 For a fuller pass, invoke the `improve-skill` skill. Do not present a skill with an
 open CRITICAL finding.
 

package/skills/define-skill/references/governances/agent-tool-output.md

@@ -0,0 +1,86 @@
+# Agent Tool Output
+
+Rules for scripts, hooks, and CLIs that AI agents invoke. Apply when authoring skill `scripts/` or documenting CLI commands in SKILL.md.
+
+## Agent-native tools
+
+Use for skill `scripts/`, hook runtime commands, and any tool where the primary consumer is always an agent.
+
+### Stdout is the machine contract
+
+- Emit **one JSON value** per run, or silence on success with no payload.
+- Use `process.stdout.write(JSON.stringify(result) + '\n')` — never `console.log` for contract output.
+- No prose, tables, progress bars, or ANSI decoration on stdout in default mode.
+
+### Stderr is human/diagnostic
+
+- Use `console.warn`, `console.error`, or `process.stderr.write` for diagnostics.
+- Gate tables, progress, and verbose human output behind a `--verbose` flag.
+
+### Files hold durable state
+
+- Write artifacts to disk; stdout JSON names paths or fields only.
+- Agents read artifact files by path (from stdout JSON or SKILL.md), not by scraping stdout prose.
+
+### Skills present; tools record
+
+- SKILL.md tells the agent which file or JSON field to read.
+- The agent summarizes results for the user — the tool does not format user-facing prose on stdout.
+
+### Autonomous runs
+
+- Document `--yes` or an equivalent non-interactive flag when the tool can prompt.
+- Never put interactive prompts on stdout.
+- Agents must be able to run the tool without human input.
+
+### Exit codes
+
+- `0` = success.
+- Non-zero = failure; include a concise error on stderr.
+
+## Dual-audience CLI
+
+Use for command-line tools used by both humans and agents.
+
+### Default stdout = human-readable
+
+- Tables, aligned fields, and prose summaries are fine for interactive terminal use.
+
+### `--format agent` = agent contract
+
+- Agents **must** pass `--format agent` when they need output optimized for LLM reasoning.
+- `--format agent` stdout is terse, structured text — lower token cost and better reasoning than JSON.
+- `--format json` is for non-LLM machine consumers (scripts, pipelines, database inserts).
+- SKILL.md must instruct agents to use `--format agent`, not to parse default prose or tables.
+- `--json` is a deprecated alias for `--format json`, accepted for backward compatibility but not shown in `--help`.
+
+### Default-stdout exception
+
+- When a tool documents **default stdout** as the machine contract (not `--json`), SKILL.md must say so explicitly.
+- Do not assume default stdout is parseable for arbitrary CLIs.
+
+### Stderr and verbosity
+
+- Errors and validation failures go to stderr.
+- Optional human status (dry-run summaries, registration tables) goes to stderr when `--verbose` is set.
+
+### Same non-interactive and exit-code rules
+
+- Document `--yes` / non-interactive paths where prompts exist.
+- Exit `0` on success; non-zero on failure.
+
+## SKILL.md authoring
+
+When a skill documents commands agents run:
+
+- Tell agents which flag to use: `--format agent` for LLM consumption, `--format json` for non-LLM machine consumers.
+- Do **not** instruct agents to parse default stdout prose, summary tables, or generic "script output" as data.
+- Prefer: "read `<artifact-path>`" or "run with `--format agent`" or "run with `--format json` and parse the array."
+
+## References
+
+Related governances (load on demand; read stdout as authoritative):
+
+```bash
+npx cyberplace@<version> governance show skill-design
+```