cyber-aced 0.3.0

package/skills/define-skill/README.md

@@ -0,0 +1,37 @@
+# define-skill
+
+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 to use
+
+Use this skill when you want to author a new workflow skill or formalize an existing ad-hoc workflow into one.
+
+Good triggers include:
+
+- "Create a skill that does X" / "I want a skill for X"
+- Turning a documented multi-step process into a reusable skill
+- Filling out an incomplete or weakly-triggering existing SKILL.md
+- Scaffolding the SKILL.md + README + runtime symlinks in one pass
+
+Defer to a sibling when the request is really about an agent or persona (`define-agent`), a reference-only rule set (`define-governance`), extracting the current session (`skillify`), or scoring / diagnosing an existing config (`run` / `add-scenario` / `improve`).
+
+## What it does
+
+The skill walks you through the shape before writing anything:
+
+1. **Route** — confirm this is a workflow skill, not an agent, governance, or session extraction
+2. **Settle scope** — the five design questions (scope, trigger, output contract, quality bar, out-of-scope)
+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.
+
+## Enhanced from create-skill
+
+`define-skill` is the ACED-native successor to the legacy `create-skill` skill: same scaffold → audit → link lifecycle, but the test step is the ACED eval loop (a frozen `.feature` with inline `@rubric` scenarios scored over N runs) instead of a one-shot trigger-query file, and fit is classified up front so authoring effort matches the subject.
+
+## Install
+
+```bash
+npx skills add cyberuni/cyberplace --skill aced/define-skill
+```

package/skills/define-skill/SKILL.md

@@ -0,0 +1,200 @@
+---
+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).'
+---
+
+# Define Skill
+
+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
+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
+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`). If the impl-judge reports
+scenario failures, load `aced-impl-producer` to run the diagnose-and-refine loop rather than
+re-deriving it here.
+
+There are two other entry points, both with **no frozen `.feature`** and **only the SKILL.md**
+produced:
+
+- **Standalone** — the user invokes this skill directly, outside any CR. Scaffold, then offer the
+  ACED eval loop (see "Report and hand off" below) rather than assuming it.
+- **Escaped** — the gateway or `start-mission` invokes this skill directly after resolving the
+  request `non-durable` (the escape hatch, before any CR opens). There is no mission to hand off
+  within: scaffold, audit, report, and **stop** — do not mention the ACED eval loop.
+
+## Route the request first
+
+`define-skill` owns **workflow skills**. Defer when the intent belongs to a sibling that carries the
+same config vocabulary:
+
+| The request is really about… | Defer to |
+|---|---|
+| a named reusable **agent** / delegated worker / an in-context **persona** | `define-agent` |
+| a **reference-only rule set / governance** other skills load but never execute as steps | `define-governance` |
+| generalizing **the current session's** work into a skill | `skillify` |
+| **scoring** an existing config, or **adding** an eval case | `run` / `add-scenario` |
+| **diagnosing** why an existing skill's evals fail | `improve` |
+
+A persona request that surfaces mid-authoring is handed to `define-agent` — do not scaffold a persona
+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:
+
+```bash
+npx cyberplace@0.2.4 governance show skill-design   # resolve <version> via: npm view cyberplace version — never @latest
+```
+
+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.
+
+## Settle the shape — five questions
+
+Answer all five before writing a line of SKILL.md. If any cannot be inferred from what the user has
+said, **ask the user to resolve it** — never invent it:
+
+| Question | What to decide |
+|---|---|
+| Scope | What exactly does this skill do? One workflow only. |
+| Trigger condition | When should it fire? List both explicit and implicit phrasings. |
+| Output contract | What artifact does it produce — a file path, a report format, a decision? |
+| Quality bar | How will you know a run succeeded? A concrete pass condition. |
+| Out of scope | What must this skill explicitly NOT do? |
+
+## Choose the pattern
+
+Capture the workflow shape (separate from placement). A persona is **not** a pattern here — route it
+to `define-agent`.
+
+| Pattern | When to use it | Body shape |
+|---|---|---|
+| Process | Ordered multi-step workflow with decision points | Numbered steps |
+| Tool-based | Consistent use of tools, systems, or connectors | Tool usage + guardrails |
+| Standard | Tone, format, structure, or quality enforcement | Rules + pass conditions |
+
+## Resolve placement and runtimes
+
+Pick placement before scaffolding; if unclear from context, ask:
+
+| Placement | Location | Notes |
+|---|---|---|
+| User-global | `~/.agents/skills/<name>/` | Personal, across all projects; no README |
+| Project-private | `.agents/skills/<name>/` | Contributor tooling; add `metadata: internal: true` |
+| Project-public | `skills/<name>/` (or `plugins/<plugin>/skills/<name>/`) | Shipped with a package; **requires a README** |
+
+Check whether `npx skills` is available, then scaffold at the derived path:
+
+```bash
+npx skills --version 2>/dev/null && npx skills init <name> --dir <placement-dir>   # else: mkdir -p <placement-dir>/<name>
+```
+
+Ask which runtimes to target; the SKILL.md is the canonical file, each runtime location is a symlink
+to it. Create and **verify** one symlink per selected runtime:
+
+| Runtime | Symlink location |
+|---|---|
+| Claude Code | `~/.claude/skills/<name>` (or `.claude/skills/<name>`) |
+| Cursor | `~/.cursor/skills/<name>` |
+| Codex | `~/.codex/skills/<name>` |
+
+```bash
+ln -sf <relative-path-to-canonical> <runtime-location> && ls <runtime-location>   # verify it resolves
+```
+
+## Draft the SKILL.md
+
+Write the file at the canonical path:
+
+```markdown
+---
+name: <name>          # kebab-case, must match the directory name exactly
+description: <capability> + "Use when <trigger>" + an implicit-phrasing example ("even if they say …")
+---
+
+# <Title>
+
+## When to use
+<the trigger condition, restated for the body>
+
+## Instructions
+1. <step>
+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.
+- **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.
+- **Project-public** skills get a `README.md` beside the SKILL.md (title, when-to-use, what-it-does,
+  install line). User-global skills get none.
+- **Binding rules get a `## Validate` section.** If the body states rules the agent must, must not,
+  always, or never do — most commonly the **Standard** pattern, but any pattern can carry one —
+  add a `## Validate` section: one assertion per rule, phrased as an observable, falsifiable claim
+  about the resulting artifact (a diff, a file's presence, a structural shape), not a restatement of
+  the rule or a claim about the agent's intent. Write it so it works run twice, from two vantage
+  points: as the agent's own pre-handoff self-check before declaring the work done, and as an
+  independent re-check by a cold reader later, against the same artifact rather than against
+  anything the first agent said about itself. Prefer a mechanical check (script, grep, diff) wherever
+  the rule permits one. A skill whose body is only ordered steps with no binding rules on the
+  *outcome* does not need one — this is for rules a result can violate, not for the steps themselves.
+
+### Improving an existing skill
+
+If the target SKILL.md already exists, **read it first** and change **only** the gaps or issues found
+— leave every sound part intact. This fills gaps in a skill's *definition*; diagnosing failing evals
+is `improve`.
+
+## Name gate/case scorers by role
+
+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
+`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
+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.
+
+## Audit before handing back
+
+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>
+```
+
+For a fuller pass, invoke the `improve-skill` skill. Do not present a skill with an
+open CRITICAL finding.
+
+## Report and hand off to the ACED eval loop
+
+Summarize:
+
+- Canonical SKILL.md path
+- README path (project-public only)
+- Runtime symlinks created and verified
+- Audit outcome
+
+**Escaped** entry: stop here — the artifact resolved `non-durable`, so there is no mission to hand
+off to.
+
+**Standalone or impl-producer** entry: point the user at the **ACED eval loop** to spec and score
+the skill — run `sdd:start-mission` (the conductor resolves the ACED roles for the `skill`
+artifact-type) to author its frozen `.feature` (with inline `@rubric`), or `add-scenario` / `run` to
+grow and score it. Do **not** embed a legacy trigger-query eval file as the test step — scoring is the
+ACED loop's job.

package/skills/extract-situation/README.md

@@ -0,0 +1,32 @@
+# extract-situation
+
+Internal, non-invokable ACED engine — loaded by `aced-case-judge`, not triggered directly. It reads
+one scenario out of a frozen `.feature` and emits only the situation a simulating agent may see.
+
+## What it does
+
+Parses the `.feature`, finds the named scenario, and emits its `Given` and `When` steps verbatim, in
+file order. It withholds the scenario name, every `Then`, the inline `@rubric` docstring, the tags,
+the `Feature:` description, and every sibling scenario.
+
+An `And` inherits the keyword above it, so `Then A / And B` withholds `And B` while
+`Given X / And Y` emits `And Y`. For a `Scenario Outline`, `<placeholder>` tokens are preserved and
+an `Examples` column survives only when an emitted step references it.
+
+Every failure exits non-zero and emits nothing: an unreadable or unparseable file, a scenario name
+that is absent or matches twice, or a missing argument.
+
+## Why it exists
+
+ACED's per-case scorer used to be handed a scenario's name, its `Then`, and its rubric — and then
+asked to simulate an agent and score that simulation in one context. The simulator was told the
+answer before it answered, so a passing score could not distinguish an agent that reasons from one
+handed the key. This engine composes the simulator's brief mechanically, so the redaction is done by
+tested code rather than by a judge deciding what to withhold from itself.
+
+## Usage
+
+```
+node "<skill>/scripts/extract-situation.mts" --feature <path-to-.feature> --scenario "<exact name>"
+node "<skill>/scripts/extract-situation.mts" --feature <path> --scenario "<name>" --format json
+```

package/skills/extract-situation/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: extract-situation
+description: "Partial Skill: invoke by name only — the ACED blind-brief extractor — loaded by aced-case-judge to compose a simulating context's brief, not user-triggered."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# extract-situation
+
+The **blind-brief extractor** — the deterministic engine that reads one scenario out of a frozen
+`.feature` and emits **only the situation**: its `Given` and `When` steps. The scenario **name**,
+every `Then`, the inline `@rubric`, and the tags are **never** emitted. `aced-case-judge` composes a
+simulating context's brief **only** through this engine; it never decides by its own judgment what to
+withhold. It is **read-only** — it never writes a `.feature`, a brief, or any other file.
+
+## Invocation
+
+```
+node "<skill>/scripts/extract-situation.mts" --feature <path-to-.feature> --scenario "<exact name>"
+```
+
+`--format json` emits `{ steps, given, when, placeholders, examples }` instead of the markdown brief —
+`steps` is the emitted brief in file order (`given`/`when` regroup the same steps by keyword), and
+`examples` carries a `Scenario Outline`'s surviving columns.
+
+## What it emits, and what it must never emit
+
+| Element | Emitted | Why |
+|---|---|---|
+| `Given` steps (and an `And`/`But` inheriting `Given`) | **yes** | the situation the agent is in |
+| `When` steps (and an `And`/`But` inheriting `When`) | **yes** | the act under evaluation |
+| Scenario **name** | never | names state the verdict (`red tests block the commit`) |
+| `Then` steps, and any `And`/`But` inheriting `Then` | never | the expected outcome is the answer key |
+| Inline `@rubric` docstring | never | the scoring ladders are worked answers |
+| Tags, `Feature:` description, sibling scenarios | never | not the situation |
+
+**Keyword inheritance is the load-bearing rule.** An `And` takes the keyword of the step above it:
+`Given X / And Y` makes `And Y` a `Given` (emit); `Then A / And B` makes `And B` a `Then` (withhold).
+Tracking the current keyword is what keeps the answer key out of the brief.
+
+For a `Scenario Outline`, `<placeholder>` tokens stay intact and an `Examples` column is emitted
+**only when an emitted step references its placeholder** — a column only a `Then` reads is withheld.
+
+## Fail closed
+
+Every failure exits non-zero and emits **no brief** — an empty brief must never be mistakable for a
+valid one. Unreadable or unparseable `.feature`; scenario name absent; the name matching **two**
+scenarios; `--feature` or `--scenario` missing.
+
+## References
+
+The contract this engine serves: `aced-case-judge`'s blind two-pass protocol, spec'd at
+`.agents/specs/aced/sdd-roles/judge/`.

package/skills/extract-situation/scripts/extract-situation.mts

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+// extract-situation — mechanically redacts a named .feature scenario down to its SITUATION: the
+// Given/When steps only. This is the fix for the "eval cannot fail" defect in
+// plugins/aced/agents/aced-case-judge.md — that judge is handed the scenario's Then/And/But
+// assertions AND its inline @rubric in the SAME context it simulates the subject in, so the
+// simulator sees the answer key before it acts. A simulating context must see ONLY this engine's
+// output: never the scenario name, never a Then/And/But, never a docstring, never a tag, never a
+// sibling scenario.
+//
+// The keyword-inheritance rule is the load-bearing logic: `And`/`But` inherit the keyword of the
+// concrete step above them (`Given X` / `And Y` → Y is a Given; `Then A` / `And B` → B is a
+// Then). Each step's EFFECTIVE keyword — never its literal `And`/`But` text — decides inclusion.
+//
+// Pure functions are exported for node:test; running the file directly drives the CLI. No
+// dependencies — plain node strips the types.
+
+import { readFileSync, realpathSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+// ─── types ────────────────────────────────────────────────────────────────────
+
+export type ConcreteKeyword = 'Given' | 'When' | 'Then'
+
+// An `And`/`But` with no concrete step above it has no keyword to inherit. It resolves to
+// `unresolved` and is withheld: a step whose keyword cannot be established is never emitted.
+export type EffectiveKeyword = ConcreteKeyword | 'unresolved'
+
+export interface Step {
+	text: string
+	effectiveKeyword: EffectiveKeyword
+	// A docstring belongs to the step above it and inherits that step's fate. Under a `Given`/`When`
+	// it IS the situation (the prompt under test); under a `Then` it is the answer key (the rubric).
+	docstring: { fence: string; lines: string[] } | null
+}
+
+export interface ParsedScenario {
+	name: string
+	steps: Step[]
+	isOutline: boolean
+	examples: { header: string[]; rows: string[][] } | null
+}
+
+export interface Situation {
+	// Every emitted step, in the order the file lists them. `given`/`when` regroup the same steps
+	// by keyword; the brief is rendered from `steps`, so an interleaved scenario reads as written.
+	steps: string[]
+	given: string[]
+	when: string[]
+	placeholders: string[]
+	examples: { header: string[]; rows: string[][] } | null
+}
+
+// ─── parse ────────────────────────────────────────────────────────────────────
+
+// Finds every scenario in the file (name, steps with resolved keywords, outline/Examples). Steps
+// carry the ORIGINAL line text (minus indentation) so the brief is verbatim; only the keyword used
+// for inclusion is resolved.
+//
+// Docstring lines are skipped wholesale rather than left to fall through the step regex. A rubric
+// ladder routinely opens a line with a step keyword ("When the agent stages only related files,
+// award 3"); read as a step, that line both leaks the answer key into the brief AND overwrites
+// `lastKeyword`, so the collapsing `And ... at least the threshold` below it inherits `When` and
+// leaks too.
+export function parseScenarios(text: string): ParsedScenario[] {
+	const lines = text.split('\n')
+	const scenarios: ParsedScenario[] = []
+	let current: ParsedScenario | null = null
+	let lastKeyword: ConcreteKeyword | null = null
+	let docstringFence: string | null = null
+	let docstringOwner: Step | null = null
+
+	for (const raw of lines) {
+		const line = raw.trimStart()
+
+		// Docstring lines are captured onto their owning step, never re-read as steps. Letting them
+		// fall through the step regex is what leaks a rubric ladder that opens with a step keyword
+		// ("When the agent stages only related files, award 3") into the brief, and overwrites
+		// `lastKeyword` so the collapsing `And ... at least the threshold` below it leaks too.
+		const fence = /^("""|```)/.exec(line)?.[1]
+		if (docstringFence) {
+			if (fence === docstringFence) {
+				docstringFence = null
+				docstringOwner = null
+			} else if (docstringOwner?.docstring) {
+				docstringOwner.docstring.lines.push(raw)
+			}
+			continue
+		}
+		if (fence) {
+			docstringFence = fence
+			const owner = current?.steps.at(-1) ?? null
+			if (owner) {
+				owner.docstring = { fence, lines: [] }
+				docstringOwner = owner
+			}
+			continue
+		}
+
+		if (/^Scenario:/i.test(line) || /^Scenario Outline:/i.test(line)) {
+			if (current) scenarios.push(current)
+			const isOutline = /^Scenario Outline:/i.test(line)
+			const name = line.replace(/^Scenario(?: Outline)?:/i, '').trim()
+			current = { name, steps: [], isOutline, examples: null }
+			lastKeyword = null
+			continue
+		}
+
+		if (current && /^Examples:/i.test(line)) {
+			current.examples = { header: [], rows: [] }
+			continue
+		}
+
+		if (current?.examples && line.startsWith('|')) {
+			const cells = line
+				.split('|')
+				.slice(1, -1)
+				.map((c) => c.trim())
+			if (current.examples.header.length === 0) current.examples.header = cells
+			else current.examples.rows.push(cells)
+			continue
+		}
+
+		const stepMatch = /^(Given|When|Then|And|But)\b/i.exec(line)
+		if (current && stepMatch) {
+			const literal = stepMatch[1]
+			const resolved: EffectiveKeyword = /^(Given|When|Then)$/i.test(literal)
+				? ((literal[0].toUpperCase() + literal.slice(1).toLowerCase()) as ConcreteKeyword)
+				: (lastKeyword ?? 'unresolved')
+			current.steps.push({ text: line, effectiveKeyword: resolved, docstring: null })
+			if (resolved !== 'unresolved') lastKeyword = resolved
+		}
+	}
+
+	if (current) scenarios.push(current)
+	return scenarios
+}
+
+// ─── extraction ───────────────────────────────────────────────────────────────
+
+export class ScenarioNotFoundError extends Error {}
+export class AmbiguousScenarioError extends Error {}
+export class UnparseableFeatureError extends Error {}
+// A scenario the file holds but which carries no Given/When has no situation to simulate from. It
+// fails closed rather than emitting an empty brief: a simulator handed nothing simulates nothing,
+// the case scores low, and the eval reads as a defect in the SUBJECT rather than in the extraction.
+export class EmptySituationError extends Error {}
+// A `Scenario Outline` row index that the Examples table does not hold.
+export class RowOutOfRangeError extends Error {}
+
+// Extracts the redacted situation for the named scenario: its Given/When steps only, by EFFECTIVE
+// keyword (never literal text) — every Then/And/But-after-Then step, every tag, the scenario name
+// itself, and every sibling scenario are excluded by construction (never read into the result).
+// Fails closed: an unparseable file, a missing name, or a duplicate name throws rather than
+// returning an empty-but-plausible brief a caller could mistake for a valid one.
+export function extractSituation(text: string, scenarioName: string, fileLabel: string, row?: number): Situation {
+	if (!/^\s*Feature:/im.test(text)) {
+		throw new UnparseableFeatureError(`${fileLabel}: not a valid .feature file (no Feature: line)`)
+	}
+
+	const scenarios = parseScenarios(text)
+	const matches = scenarios.filter((s) => s.name === scenarioName)
+
+	if (matches.length === 0) {
+		throw new ScenarioNotFoundError(`${fileLabel}: scenario not found: "${scenarioName}"`)
+	}
+	if (matches.length > 1) {
+		throw new AmbiguousScenarioError(
+			`${fileLabel}: scenario name is ambiguous (${matches.length} matches): "${scenarioName}"`,
+		)
+	}
+
+	const scenario = matches[0]
+	const emitted = scenario.steps.filter((s) => s.effectiveKeyword === 'Given' || s.effectiveKeyword === 'When')
+	const steps = emitted.flatMap((s) =>
+		s.docstring ? [s.text, s.docstring.fence, ...s.docstring.lines, s.docstring.fence] : [s.text],
+	)
+	const withDoc = (s: Step) =>
+		s.docstring ? [s.text, s.docstring.fence, ...s.docstring.lines, s.docstring.fence] : [s.text]
+	const given = emitted.filter((s) => s.effectiveKeyword === 'Given').flatMap(withDoc)
+	const when = emitted.filter((s) => s.effectiveKeyword === 'When').flatMap(withDoc)
+
+	if (steps.length === 0) {
+		throw new EmptySituationError(`${fileLabel}: scenario has no Given or When steps: "${scenarioName}"`)
+	}
+
+	const placeholders = [...new Set(steps.flatMap((s) => [...s.matchAll(/<([^>]+)>/g)].map((m) => m[1])))]
+
+	let examples: Situation['examples'] = null
+	if (scenario.isOutline && scenario.examples && placeholders.length > 0) {
+		const keepIdx = scenario.examples.header
+			.map((col, i) => (placeholders.includes(col) ? i : -1))
+			.filter((i) => i !== -1)
+		if (keepIdx.length > 0) {
+			// One row is one case: judge scores a single invoke decision per invocation, so an outline
+			// is extracted a row at a time rather than handed over whole.
+			const allRows = scenario.examples.rows
+			if (row !== undefined && (row < 0 || row >= allRows.length)) {
+				throw new RowOutOfRangeError(
+					`${fileLabel}: row ${row} is outside the Examples table (${allRows.length} rows): "${scenarioName}"`,
+				)
+			}
+			const picked = row === undefined ? allRows : [allRows[row]]
+			examples = {
+				header: keepIdx.map((i) => scenario.examples!.header[i]),
+				rows: picked.map((r) => keepIdx.map((i) => r[i])),
+			}
+		}
+	}
+
+	return { steps, given, when, placeholders, examples }
+}
+
+// ─── format ───────────────────────────────────────────────────────────────────
+
+function formatTable(table: { header: string[]; rows: string[][] }): string {
+	const line = (cells: string[]) => `| ${cells.join(' | ')} |`
+	return [line(table.header), ...table.rows.map(line)].join('\n')
+}
+
+export function formatMarkdown(situation: Situation): string {
+	const lines: string[] = ['## Situation', '']
+	for (const step of situation.steps) lines.push(step)
+	if (situation.examples) {
+		lines.push('', 'Examples:', formatTable(situation.examples))
+	}
+	return `${lines.join('\n')}\n`
+}
+
+export function formatJson(situation: Situation): string {
+	return `${JSON.stringify(situation, null, 2)}\n`
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+export function main(argv: string[]): number {
+	const featurePath = flag(argv, '--feature')
+	const scenarioName = flag(argv, '--scenario')
+	const rowRaw = flag(argv, '--row')
+	const format = flag(argv, '--format') ?? (argv.includes('--json') ? 'json' : 'text')
+
+	if (!featurePath || !scenarioName) {
+		console.error('✗ usage: extract-situation.mts --feature <path> --scenario "<name>" [--row <n>] [--format json]')
+		return 1
+	}
+
+	let row: number | undefined
+	if (rowRaw !== undefined) {
+		row = Number(rowRaw)
+		if (!Number.isInteger(row) || row < 0) {
+			console.error(`✗ --row must be a non-negative integer, got "${rowRaw}"`)
+			return 1
+		}
+	}
+
+	let text: string
+	try {
+		text = readFileSync(featurePath, 'utf8')
+	} catch {
+		console.error(`✗ ${featurePath}: cannot read file`)
+		return 1
+	}
+
+	try {
+		const situation = extractSituation(text, scenarioName, featurePath, row)
+		process.stdout.write(format === 'json' ? formatJson(situation) : formatMarkdown(situation))
+		return 0
+	} catch (err) {
+		console.error(`✗ ${(err as Error).message}`)
+		return 1
+	}
+}
+
+// `import.meta.main` is Node >=24.2, but this repo's engines floor is >=22, where it is `undefined`
+// — the CLI would never run, printing nothing and exiting 0. A caller keying its BLOCKER on a
+// non-zero exit would read that empty brief as a success and simulate from nothing.
+//
+// `pathToFileURL`, not `file://${process.argv[1]}`: `import.meta.url` percent-encodes, so the naive
+// concat mismatches on any path holding a space (or #, ?, %) and silently reproduces that same
+// never-fires bug — the trigger merely moves from a Node version to an install path.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/improve/README.md

@@ -0,0 +1,25 @@
+# improve
+
+Improve an existing agent configuration of any kind — a skill, subagent, command, or AGENTS.md section — whether by diagnosing failing ACED evals or by general review against fit and quality bars.
+
+## When to use
+
+Use this skill when a config isn't working as well as it should and you want concrete proposed edits, not just a diagnosis.
+
+Good triggers include:
+
+- "Improve this skill" / "Make this agent better"
+- "Why does this config keep failing?"
+- Reviewing a config that has no eval suite yet, before deciding whether it's worth building one
+
+Defer to a sibling when the request is really about scaffolding something new (`define-skill` / `define-agent` / `define-governance`), just scoring (`run`), just adding a case (`add-scenario`), just diffing two versions (`compare`), or auditing a `SKILL.md`'s structure specifically (`improve-skill`).
+
+## What it does
+
+If the target is ACED-tracked (has an `eval.md`), it loads the internal impl-producer loop to classify failing cases by pattern and propose before/after edits, then verifies with `compare`. If not yet tracked, it runs a general review — fit classification plus the relevant builder bar — and proposes edits for any gap found, offering to hand off to `sdd:start-mission` to formalize an eval suite.
+
+## Install
+
+```bash
+npx skills add cyberuni/cyberplace --skill aced/improve
+```