pi-gauntlet 7.2.1 → 7.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v7.3.0 - 2026-10-05
+
+- eval/brainstorming/replay: the live-tool replay harness code and verdict tables are committed; private inputs and transcripts are documented as non-committable.
+
+### Added
+
+- **forge-skill persona rules and eval harness.** `skills/forge-skill/SKILL.md` gains `## Persona rules` (the body is the whole system prompt, `description` is a routing label, frontmatter stays byte-identical unless a knob is named, tools stay as narrow as the job, no `/skill:` or `reference/` machinery, no reload step in pi) and marks its three skill-only authoring rules `Skills only:`. `eval/forge-skill/` is a fact-judged eval driver (worker edit, two reviewers, arithmetic kept/disputed/lost, refusal-guarded `compare`) with ten samples, six of them persona edits (four from `agents/` history, two constructed to exercise the persona rules); it ships outside the package; `scripts/ci.mjs` runs its deterministic driver tests and checks sample shape (exactly `case.md` + `expected.md`). The sample files are `case.md` (fixture files plus the edit request, fenced) and `expected.md`, and raw results stay under `$TMPDIR` - both deliberate deviations from `eval/README.md`, recorded in the spec. Baseline-vs-candidate judgment is recorded in the spec's `## Eval judgment`.
+
 ## v7.2.1 - 2026-10-04
 
 ### Changed

package/README.md

@@ -159,6 +159,8 @@ Evals compare prompt wording on fixed inputs against human-approved must-hold fa
 
 Run an arm with externally supplied models: `node eval/spec-summarizer/run.mjs run --arm candidate --persona agents/spec-summarizer.md --candidate-model <candidate-id> --reviewers <reviewer-a>,<reviewer-b>`. The [eval convention](eval/README.md) owns the layout, baseline/candidate process, and publication rules; the [spec-summarizer eval](eval/spec-summarizer/README.md) is the worked example with eight samples and committed results. Model calls run manually, never in CI; CI runs deterministic eval tests and hygiene checks. `eval/` is checkout-only and excluded from the npm tarball.
 
+`eval/forge-skill/` measures an edit to `skills/forge-skill/SKILL.md`: `node eval/forge-skill/run.mjs --skill-dir <path> --candidate-model <id> --reviewers <id>,<id>` runs a worker over ten samples (four skill fixtures, six persona fixtures - four from this repo's `agents/` history, two constructed to exercise the persona rules), has two reviewer models vote per must-hold fact, and writes records under `$TMPDIR`; `run.mjs compare <baseline> <candidate>` refuses mismatched inputs and fails on any fact that moved from kept to lost. Models are arguments, never committed. Its samples are `case.md` + `expected.md` and its raw results stay under `$TMPDIR` - the two places it deviates from the convention. Process and sample grammar: [`eval/forge-skill/README.md`](eval/forge-skill/README.md).
+
 ## Use from Claude Code
 
 Six skills are exposed to Claude Code via the plugin marketplace at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "7.2.1",
+  "version": "7.3.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/forge-skill/SKILL.md

@@ -11,6 +11,8 @@ This skill governs every file a model reads as instructions: `SKILL.md` and its
 
 ## Conventions
 
+Skills only; persona conventions are in ## Persona rules.
+
 Sources: pi - `docs/skills` in `@earendil-works/pi-coding-agent`; Claude Code - `code.claude.com/docs/en/skills`.
 
 | Item | pi | Claude Code |
@@ -31,24 +33,36 @@ Sources: pi - `docs/skills` in `@earendil-works/pi-coding-agent`; Claude Code -
 These rules bind the lines an edit adds or changes. Leave other lines alone.
 
 - Imperative voice. Write instructions as commands. Never "should", "consider", "you may want to", "it is recommended".
-- Low conditionality. One path per step: branch only on a runtime fact the model can observe - a tool result, a file's presence, a settings value - never on the reader's judgment. Two branches is the ceiling; a third goes into a table or a `reference/` file.
+- Low conditionality. One path per step: branch only on a runtime fact the model can observe - a tool result, a file's presence, a settings value - never on the reader's judgment. Two branches is the ceiling; a third goes into a table, or for a skill a reference/ file.
 - Minimal diff. A rule change touches the sentence that owns the rule, not the section. Never restate a rule in a second place; link the owner.
-- Oversized file. A change touching a file over 500 lines extracts the concern it touches - or the largest self-contained `##` section - into `reference/<topic>.md` in the same change, and leaves a one-line "read X now" pointer at the step that needs it.
+- Skills only: Oversized file. A change touching a file over 500 lines extracts the concern it touches - or the largest self-contained `##` section - into `reference/<topic>.md` in the same change, and leaves a one-line "read X now" pointer at the step that needs it.
 - Recipe over prohibition. A shape or quality problem gets a statement of what the output is; a discipline problem gets one explicit rule. Never a list of things to avoid.
 - No nuance clauses. "Unless it matters", "when appropriate", "if needed" reopen the decision; delete them or name the observable condition.
-- Description is a trigger. State when to load the skill (symptoms, file types, situations); never summarize its steps.
+- Skills only: Description is a trigger. State when to load the skill (symptoms, file types, situations); never summarize its steps.
 - One example. One concrete example per rule, never three.
 - Skip what the model knows. No explanations of git, shell, or the harness.
-- Never force-load. Cross-reference a skill by its invocation name (pi `/skill:name`, Claude Code `/name` or `/plugin:name`); never with `@`.
+- Skills only: Never force-load. Cross-reference a skill by its invocation name (pi `/skill:name`, Claude Code `/name` or `/plugin:name`); never with `@`.
 - ASCII punctuation, compact `|---|` table separators, present tense.
 
+## Persona rules
+
+A persona is an `agents/<name>.md` file dispatched by name (pi-cohort `subagent({ agent })`, Claude Code subagents); its body is the child's entire system prompt. Frontmatter fields: the "Agent frontmatter" table in pi-cohort's agents-and-chains doc; a project's pins: its personas doc ("Frontmatter knobs" in this repo's `doc/personas`). Every `## Authoring rules` bullet without a `Skills only:` marker binds here too.
+
+- Whole prompt. pi-cohort assembles no base prompt, AGENTS.md, or skills catalog around the body unless `inheritProjectContext` or `inheritSkills` opts in; Claude Code replaces its default prompt with it. Open with the role and why it exists, state the output contract the caller parses before any method; when the caller parses a closing line, keep it last.
+- Routing label. `description` is the one-sentence dispatch label the orchestrator's agent list shows: name when to dispatch, and write `Not for direct dispatch` when a skill owns the call. Never a summary of the body.
+- Frontmatter pin. Leave every line the edit does not touch byte-identical, and leave frontmatter untouched unless the request names a knob - a pinned field removes the matching `agentOverrides` knob, so the request states the pin; a line the edit rewrites follows the ASCII rule like any other. Never pin `model`.
+- Narrow tools. `tools` and `inherit*` list the operations the job performs and nothing else; a reviewer keeps `bash` when its caller injects a scoped command. A non-implementing persona with `bash` sets `completionGuard: false`; an implementing persona keeps the guard.
+- Contract strings. A sentence a caller parses - closing line, mode discriminator, verdict word - changes only together with its caller; the project's validator pins them. Example: `lean: nothing to cut` stays verbatim.
+- No skill machinery. No `/skill:` cross-reference and no `reference/` file: the body is read whole and nothing beside it is loaded (frontmatter `skills:` injects named skills; it is a knob, not a file split). A persona over 500 lines splits by job into a second persona.
+- Reload. pi-cohort re-reads `agents/` on every dispatch, so an edit is live at the next call; Claude Code needs a new session.
+
 ## Edit procedure
 
 1. Read the whole file.
 2. Locate and edit the sentence that owns the rule you are changing (see Minimal diff).
 3. Read the changed lines back against `## Authoring rules`.
-4. Run `wc -l` on the file; over 500 lines, extract per the oversized-file rule.
-5. pi: run `/reload`. Claude Code: start a new session.
+4. Run wc -l; over 500 lines, a skill extracts per the oversized-file rule, a persona splits by job.
+5. Skill, pi: run /reload. Persona, pi: nothing. Claude Code: start a new session.
 
 ## Test (optional)
 
@@ -62,6 +76,7 @@ Run after adding a rule or rewording a discipline rule.
 |---|---|
 | pi | `subagent({ agent: "worker", context: "fresh", task })` twice, one task with the body appended |
 | Claude Code | The harness's subagent dispatch tool, twice, same split |
+| pi, persona | baseline: `subagent({ agent: "worker", context: "fresh", task })` with the pre-edit body appended; loaded: `subagent({ agent: "<name>", context: "fresh", task })` after the edit - pi-cohort re-reads `agents/` per dispatch, so capture the pre-edit body first |
 
 ## Project overrides