Skip to content
Back to skills

Record State Result

ASecurity

Records a state outcome in the run ledger, validates the transition and advances state.current. Use after a state ends.

  • 2 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 11, 2026
ai-agentsrustgoshellbashgitsecurity

Works with

  • terminal

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 11, 2026

npx -y skills add brenpike/hivemind --skill record-state-result --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Record State Result?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Record State Result
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/brenpike-record-state-result/badge)](https://www.skillsdirectory.com/skills/brenpike-record-state-result)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: record-state-result
description: Records a state outcome in the run ledger, validates the transition and advances state.current. Use after a state ends.
allowed-tools:
  - Bash(bash "${CLAUDE_PLUGIN_ROOT}/skills/record-state-result/scripts/record-state-result.sh" *)
  - Read(~/.claude/plugins/cache/brenpike/hivemind/**)
  - Edit(.hivemind/runs/.record-inputs-*.json)
shell: bash
---

# Record State Result

Record the current workflow state's outcome in the run ledger, append a ledger event,
validate the transition against the workflow definition, and advance `state.current`
to the legal next state. The engine is the committed script
`${CLAUDE_PLUGIN_ROOT}/skills/record-state-result/scripts/record-state-result.sh`; this
body authors one JSON inputs file and runs the script once. The script reads the
allowed-result set from the workflow definition; the model never supplies it.

Rules: ADR-0018 §A (ledger and definitions are JSON), §C (engine is the committed
script), §I (the engine hard-rejects a workflow id/version mismatch and exposes no
rebind). The overlord resume-on-start gate owns the two version-skew doors (start
fresh / proceed intent-driven); the engine op for both is `hivemind:mark-intent-fallback`.

## Required Inputs

The caller resolves and passes these; the skill does not invent them.

- `run_id`: the run identifier (from `init-run-ledger`). The engine derives the ledger
  (`<git-root>/.hivemind/runs/<run_id>/state.json`) and the workflow definition (the
  ledger's `run.workflow` in the script's own packaged `workflows/` dir); the caller
  passes no ledger or workflow path.
- `state`: the state the run is in (must equal `ledger.state.current`).
- `result`: the named outcome (must be a legal transition key under that state).
- `summary`: human-readable summary; untrusted, stored exactly.
- `outputs` (optional): a JSON object of named outputs; untrusted, stored as data.
- `plan_steps` (optional): cerebrate's plan `steps` as a JSON array; untrusted, stored
  as data. Pass it when recording any cerebrate planning state result (§A below).
- `plan_path` (optional): path to the cerebrate directive; untrusted, stored exactly.

## The §A Plan-Steps Seam

Cerebrate's plan `steps` arrive as YAML; the ledger is JSON, with no maintained
converter. The primary, live writer of `plan.steps` is here, at record time: the
caller inits the ledger before any cerebrate planning state runs. When recording any
cerebrate planning state result (`plan` / `review_remediation_plan` /
`review_remediation_plan_postpr` / `brood_plan`), reformat cerebrate's YAML `steps`
into a JSON array as `plan_steps` (and optionally `plan_path`) in the inputs file; the
script sets `.plan.steps` (and `.plan.path`). When those keys are absent (missing or
null), `.plan.*` is left untouched, never clobbered to `[]`. `init-run-ledger`'s
`plan_steps` only seeds a child/resume run (default `[]`; see that skill's §A
Plan-Steps Seam). `outputs` is the event's free-form object, never a plan-steps
writer.

Recording any cerebrate planning-state result also advances the engine-owned
monotonic plan epoch (`.plan.epoch`), and every appended event, for any state, is
stamped with the current `plan_epoch`. The caller supplies nothing for it.

## Inputs JSON

The script owns the deterministic read -> validate -> mutate -> atomic-write; the
navigator authors one JSON inputs file and passes its path as the one positional
argument. The script first checks the whole inputs file against its contract (one
JSON object; the field rules below), on the intact JSON values, before it reads any
field or opens the ledger. Shape:

```json
{
  "run_id": "<required> run identifier; the engine derives the ledger and the workflow definition from it. No path is accepted.",
  "state": "<required> state the run is currently in (must match ledger.state.current)",
  "result": "<required> named outcome to record (must be a legal transition key)",
  "summary": "<required> human-readable summary (UNTRUSTED, stored exactly)",
  "outputs": {},
  "plan_steps": [],
  "plan_path": "<optional> path to the cerebrate directive (sets plan.path)"
}
```

Field rules (all checked by the one whole-file contract check, in this order):
- Absent: a key that is missing or `null` is absent. `""` is present.
- `run_id`, `state`, `result` are required names: 1 to 255 of `A-Z a-z 0-9 . _ -`, not
  `.` or `..`. `run_id` is a single safe path component and the only identity the
  caller supplies.
- `summary` is a required string, not empty. Stored exactly: no byte is lost,
  including a trailing line feed.
- `outputs` is optional; when present it must be a JSON object, recorded verbatim
  (absent gives `{}`). `outputs.completed_steps`, when present, must be an array and
  is authorized only per check 11 below.
- `plan_steps` is optional (sets `.plan.steps`; absent leaves `.plan.*` untouched);
  when present it must be a JSON array. Every entry must be an object whose `id` is a
  required step id (1 to 64 of `A-Z a-z 0-9 . _ -`), and every `depends_on` entry
  (when present, `depends_on` must be an array) likewise a step id. A `null` entry
  fails. `.`/`..` are not rejected (step ids never become path components).
- `plan_path` is optional (sets `.plan.path`; absent leaves it untouched); when
  present it is a string, stored exactly.
- A failure is one blocker `record-state-result inputs file: <position>: <problem>`.
  The position is the dotted path with `[N]` indexes (for example
  `plan_steps[2].depends_on[0]`); the problem is a fixed phrase. A blocker never names
  the value.
- Every value is data. None is interpolated into generated shell command source.

The script validates, in order, all before any write:

1. The whole inputs contract (field rules above).
2. The ledger at the derived `<git-root>/.hivemind/runs/<run_id>/state.json`
   (`git rev-parse --show-toplevel`; outside a git checkout → blocker) must exist and
   be exactly one JSON object.
3. `ledger.run.id == run_id`.
4. The whole ledger meets its contract (`run.id`, `run.workflow`, `state.current`
   required names; `run.workflow_version` a required whole number; blocker
   `record-state-result ledger: <position>: <problem>`). Then the definition is
   derived from `run.workflow` in the script's self-located packaged `workflows/`
   dir (`BASH_SOURCE` + `pwd -P`, independent of `${CLAUDE_PLUGIN_ROOT}` and of any
   caller value).
5. `definition.id == ledger.run.workflow` (binding guard).
6. `definition.version == ledger.run.workflow_version` (binding guard). There is no
   rebind and no deterministic-resume door: the engine never reconciles skew.
7. `ledger.state.current == state`.
8. `state` exists in `definition.states` (state existence, not version skew).
9. `result` is a key under `states.<state>.transitions`, and its `next_state` must be
   declared in `definition.states`.
10. Plan-write authorization: if `plan_steps` or `plan_path` is present (non-null),
    the state must be a cerebrate planning state
    (`states.<state>.agent == "hivemind:cerebrate"`: `plan` / `review_remediation_plan`
    / `review_remediation_plan_postpr` / `brood_plan`). Key presence alone authorizes
    no plan write.
11. Producer authorization: if `outputs` carries a present, non-null `completed_steps`,
    the state must be a wave-producing agent state (`states.<state>.type == "agent"`,
    `states.<state>` declares `allowed_agents`, and `"hivemind:cerebrate"` is not in
    it, from the packaged definition). Key presence alone authorizes no credit.

Any failure exits 1 with a blocker and leaves the ledger byte-unchanged.

Then it appends the event and updates `state.previous`/`state.current`/`state.status`,
`run.updated_at`, `run.status` if `next_state` is terminal, and `plan.steps` /
`plan.path` when present (non-null). Terminal `run.status` mapping (enum
`running|complete|blocked|cancelled`): `complete`→`complete`, `blocked`→`blocked`,
`cancelled`→`cancelled`, the human-intervention terminals (`user_input_required` /
`review_rejected` / `review_exhausted`)→`blocked`, never masked as success, and any
other done-terminal (e.g. `hatchery_monitor`, `review_window_elapsed`)→`complete`.
Every write is temp-write + atomic rename.

## Procedure

1. **Build the inputs object** in your reasoning from the Required Inputs. When
   recording a cerebrate planning state result, include `plan_steps` (and `plan_path`
   if known) per §A. Each untrusted value (`summary`, `outputs`, `plan_steps`,
   `plan_path`) is structured JSON data, never spliced into command source.

2. **Write the inputs file** with the Write tool, per
   `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Inert Inputs-File Navigator Pattern):
   `file_path` = `.hivemind/runs/.record-inputs-<token>.json`, where `<token>` is new for each
   invocation (a UTC timestamp plus a random part, such as `20260601T014132Z-a1b2c3`);
   `content` = the JSON object from step 1. No cleanup is needed.
   If the Write call does not succeed, stop blocked per
   `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Transport Degradation Is a Hard Stop).

3. **Execute the script** with one Bash call, passing the inputs file path:
   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/skills/record-state-result/scripts/record-state-result.sh" .hivemind/runs/.record-inputs-<token>.json
   ```
   Execute (do not Read) the script.
4. **Interpret the result.** Exit 0: the script printed YAML routing lines on stdout:
   ```yaml
   previous_state: <state>
   result: <result>
   current_state: <next_state>
   ledger: <path>
   state_definition: <compact JSON of next_state from the packaged definition>
   ```
   Advance only to `current_state` and execute it as `state_definition` defines it,
   with no read of the workflow definition file. Exit 1: the script printed
   `blocker: <reason>` on stderr and the ledger is byte-unchanged; surface it and stop.

## Pointers

- Execute (do not read) the engine:
  `${CLAUDE_PLUGIN_ROOT}/skills/record-state-result/scripts/record-state-result.sh`.
- Ledger schema: `${CLAUDE_PLUGIN_ROOT}/references/run-ledger-schema.md`.

## Silence Discipline

Follow `${CLAUDE_PLUGIN_ROOT}/governance/definitions.md` (Silence Discipline). The step 2 Write
is the inputs-file Write; the procedure ends at the step 3 Bash call, which performs every
atomic ledger write. Exit 0: the caller advances to `current_state`, which the
`state_definition` line defines. Exit 1: the ledger is unchanged.

## Do Not

- supply or guess the allowed-result set.
- advance to any state other than the `current_state` the script returns.
- mutate the ledger by hand or with any tool other than this script. The version-skew
  intent-fallback write and the start-fresh stale-run closeout go through
  `hivemind:mark-intent-fallback`, never by hand.
- use the Write tool for anything other than the `.hivemind/runs/.record-inputs-<token>.json`
  inputs file.
- author the inputs file by any transport other than the Write tool; see
  `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Transport Degradation Is a Hard Stop).
- commit, push, or open a PR.
- Read or reconstruct the script body; invoke it with the documented inputs file path.

Files in this skill

  • SKILL.md11 KB
  • scripts/record-state-result.sh37.4 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.