cyber-aced 0.3.0 → 0.4.1

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/license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,44 +1,44 @@
 {
-	"name": "cyber-aced",
-	"version": "0.3.0",
-	"description": "Agent Config Evaluation & Development. Spec, evaluate, and improve agent configurations: skills, AGENTS.md sections, subagent definitions, and commands.",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/cyberuni/cyber-sdd.git",
-		"directory": "plugins/aced"
-	},
-	"homepage": "https://github.com/cyberuni/cyber-sdd",
-	"license": "MIT",
-	"type": "module",
-	"bin": {
-		"aced-bench": "./dist/aced-bench.js"
-	},
-	"files": [
-		"dist",
-		"skills",
-		"agents",
-		"governances",
-		".plugin",
-		".codex-plugin",
-		".claude-plugin",
-		"!skills/**/*.test.mts"
-	],
-	"dependencies": {
-		"@cyberuni/agent-harness": "0.5.0"
-	},
-	"scripts": {
-		"build": "tsdown",
-		"check:spec": "node ../sdd/skills/check-project-specs/scripts/check-project-specs.mts",
-		"test": "node --test \"skills/*/scripts/*.test.mts\"",
-		"typecheck": "tsc -p tsconfig.json"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"devDependencies": {
-		"tsdown": "^0.23.0"
-	},
-	"engines": {
-		"node": ">=22.11"
-	}
-}
+  "name": "cyber-aced",
+  "version": "0.4.1",
+  "description": "Agent Config Evaluation & Development. Spec, evaluate, and improve agent configurations: skills, AGENTS.md sections, subagent definitions, and commands.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyberuni/cyber-sdd.git",
+    "directory": "plugins/aced"
+  },
+  "homepage": "https://github.com/cyberuni/cyber-sdd",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "aced-bench": "./dist/aced-bench.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "agents",
+    "governances",
+    ".plugin",
+    ".codex-plugin",
+    ".claude-plugin",
+    "!skills/**/*.test.mts"
+  ],
+  "dependencies": {
+    "@cyberuni/agent-harness": "0.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.0"
+  },
+  "engines": {
+    "node": ">=22.11"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check:spec": "node ../sdd/skills/check-project-specs/scripts/check-project-specs.mts",
+    "test": "node --test \"skills/*/scripts/*.test.mts\"",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/skills/check-freshness/README.md

@@ -21,6 +21,14 @@ A directory the run expanded carries both its own entry and a `file` entry per f
 yielded — the directory hash covers names only, so without the per-file entries an edit inside that
 directory would read `current` forever.
 
+## Measured records
+
+The bench engine writes a measured record per arm to `.agents/aced/results/bench/<suite>/` with an
+`evaluated` set in the same entry shape but no `target`. `--suite <suite> --arm <label>` finds those
+records by the `suite` and `arm` they record, picks the greatest recorded `createdAt`, and compares.
+Every recorded input — `tasks.json`, a check, a `file` arm's source — changes what was measured, so
+any mismatch is `stale`; there is no `incomplete` here.
+
 ## Why the record and not the tree
 
 The first attempt at this capability inferred the subject's dependencies from outside: it guessed
@@ -50,7 +58,8 @@ oversight.
 ## Tests
 
 `scripts/check-freshness.test.mts` — one test per frozen scenario, with fixtures chosen so a
-guessing implementation cannot pass: the result is filed under a deliberately wrong directory name,
+guessing implementation cannot pass: the result is filed under a deliberately wrong directory name (a
+measured record under a file name ending in the wrong arm label),
 alphabetical filename order is the reverse of recorded timestamp order, and one fixture rewrites a
 file's modification time while leaving its bytes identical.
 

package/skills/check-freshness/SKILL.md

@@ -26,6 +26,18 @@ node "<skill>/scripts/check-freshness.mts" --node <node-dir>
 `.feature`. Exit status is **zero only for `current`**; every other verdict, and every fail-closed
 path, exits non-zero.
 
+For a **measured record** the bench engine wrote, name the suite and arm instead:
+
+```
+node "<skill>/scripts/check-freshness.mts" --suite <suite> --arm <label>
+```
+
+It reads `.agents/aced/results/bench/<suite>/`, keeps the records whose own `suite` and `arm` fields
+match (never the file name), takes the greatest recorded `createdAt`, and compares its evaluated set —
+the suite's `tasks.json`, its `checks/`, and a `file` arm's source. A measured record has no frozen
+suite, so any moved input reads `stale`; it never reads `incomplete`. Run it from inside the
+repository. `--suite` without `--arm`, or the reverse, fails closed with no verdict.
+
 It also exposes the hashing routine, so `run` records entries with the same implementation that
 reads them back — never a second one that merely agrees today:
 

package/skills/check-freshness/scripts/check-freshness.mts

@@ -282,6 +282,119 @@ export function findRepoRoot(from: string): string | null {
 
 export const RESULTS_DIR = join('.agents', 'aced', 'results')
 
+// ─── measured records ─────────────────────────────────────────────────────────
+//
+// The bench engine writes one measured record per arm to `.agents/aced/results/bench/<suite>/`.
+// It names no `target`, so it is found by the `suite` and `arm` it RECORDS — never by its file
+// name — and compared with the same hash rule. Every recorded input moves what was measured (the
+// prompts, what `pass` means, the arm itself), so there is no frozen suite to split off and no
+// `incomplete`: any moved input reads `stale`.
+
+export const MEASURED_RESULTS_DIR = join(RESULTS_DIR, 'bench')
+const MEASURED_BENCH_DIR = join('.agents', 'aced', 'bench')
+
+export interface MeasuredRecord {
+	layer?: string
+	suite?: string
+	arm?: string
+	createdAt?: string
+	subject?: { kind?: string; from?: string }
+	evaluated?: EvaluatedEntry[]
+}
+
+export interface MeasuredScan {
+	forArm: Array<{ file: string; record: MeasuredRecord }>
+	unreadable: string[]
+}
+
+/**
+ * Keeps the measured records whose OWN `suite` and `arm` fields match. A file that parses but is
+ * not a measured record — a compare record sitting beside them — is simply not a candidate.
+ */
+export function scanMeasured(files: string[], suite: string, arm: string, read: (f: string) => string): MeasuredScan {
+	const forArm: MeasuredScan['forArm'] = []
+	const unreadable: string[] = []
+	for (const file of files) {
+		let record: MeasuredRecord
+		try {
+			record = JSON.parse(read(file)) as MeasuredRecord
+		} catch {
+			unreadable.push(file)
+			continue
+		}
+		if (record && record.layer === 'measured' && record.suite === suite && record.arm === arm)
+			forArm.push({ file, record })
+	}
+	return { forArm, unreadable }
+}
+
+/** Newest by RECORDED `createdAt`, for the same reason `selectNewest` ignores file names. */
+export function selectNewestMeasured(records: MeasuredScan['forArm']): MeasuredScan['forArm'][number] | null {
+	let best: MeasuredScan['forArm'][number] | null = null
+	for (const r of records) {
+		const t = r.record.createdAt ?? ''
+		if (!best || t > (best.record.createdAt ?? '')) best = r
+	}
+	return best
+}
+
+/**
+ * The bench engine always records the suite's `tasks.json`, and records a `file` arm's source
+ * whenever the arm reads it from a path. A set omitting either contradicts the record carrying it.
+ */
+export function measuredIncoherence(record: MeasuredRecord, suite: string): string | null {
+	const paths = new Set((record.evaluated ?? []).map((e) => e.path))
+	const tasks = join(MEASURED_BENCH_DIR, suite, 'tasks.json')
+	if (!paths.has(tasks)) {
+		return `the recorded provenance contradicts the record it accompanies: it carries no entry for ${tasks}`
+	}
+	const from = record.subject?.kind === 'file' ? record.subject.from : undefined
+	if (from?.startsWith('path:')) {
+		const source = from.slice(5)
+		if (!paths.has(source)) {
+			return `the recorded provenance omits the file arm's source: no entry for ${source}`
+		}
+	}
+	return null
+}
+
+function measuredMain(repoRoot: string, suite: string, arm: string): number {
+	process.stdout.write(`suite: ${suite}\narm: ${arm}\n`)
+
+	const dir = join(repoRoot, MEASURED_RESULTS_DIR, suite)
+	if (!existsSync(dir)) {
+		report({ verdict: 'absent', reason: 'nothing is measured for this suite', mismatched: [], skipped: [] })
+		return 1
+	}
+
+	const scan = scanMeasured(collectResultFiles(dir), suite, arm, (f) => readFileSync(f, 'utf8'))
+	const skipped = scan.unreadable.map((f) => relative(repoRoot, f))
+	const newest = selectNewestMeasured(scan.forArm)
+	if (!newest) {
+		report({
+			verdict: 'absent',
+			reason: 'no measured record is recorded for this arm',
+			mismatched: [],
+			skipped,
+		})
+		return 1
+	}
+	if (!newest.record.evaluated) {
+		report({ verdict: 'absent', reason: 'the record carries no recorded provenance', mismatched: [], skipped })
+		return 1
+	}
+	const bad = measuredIncoherence(newest.record, suite)
+	if (bad) {
+		report({ verdict: 'absent', reason: bad, mismatched: [], skipped })
+		return 1
+	}
+
+	// No frozen suite: every entry is a subject input, so the verdict is `stale` or `current`.
+	const decision = decideVerdict(newest.record, repoRoot, '', skipped)
+	report(decision)
+	return decision.verdict === 'current' ? 0 : 1
+}
+
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 function report(d: Decision): void {
@@ -314,10 +427,30 @@ export function main(argv: string[]): number {
 		return 0
 	}
 
+	const suiteIdx = argv.indexOf('--suite')
+	const armIdx = argv.indexOf('--arm')
+	if (suiteIdx !== -1 || armIdx !== -1) {
+		// Fail closed, as the --node path does: one option without the other emits no verdict.
+		const suite = suiteIdx === -1 ? undefined : argv[suiteIdx + 1]
+		const arm = armIdx === -1 ? undefined : argv[armIdx + 1]
+		if (!suite || !arm) {
+			console.error(
+				`✗ a measured check needs both --suite <suite> and --arm <label>; missing ${suite ? '--arm' : '--suite'}; no verdict`,
+			)
+			return 1
+		}
+		const repoRoot = findRepoRoot(process.cwd())
+		if (!repoRoot) {
+			console.error('✗ no repository root above the working directory; no verdict')
+			return 1
+		}
+		return measuredMain(repoRoot, suite, arm)
+	}
+
 	const nodeIdx = argv.indexOf('--node')
 	const nodeArg = nodeIdx === -1 ? undefined : argv[nodeIdx + 1]
 	if (!nodeArg) {
-		console.error('✗ usage: check-freshness --node <node-dir>')
+		console.error('✗ usage: check-freshness --node <node-dir> | --suite <suite> --arm <label>')
 		return 1
 	}
 	const nodeDir = resolve(nodeArg)

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
@@ -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,8 +129,10 @@ 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
+- **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
   **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
@@ -166,7 +168,7 @@ name it by that gate/scope, not a bare action verb — `<domain>-<gate>-judge` f
 `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 +177,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
+```