/proposal-create

name: proposal-create
description: Opens an admin-decided proposal task for a high-leverage improvement discovered during work. Only for ideas with real impact — not trivial fixes. Use when you discover something worth operationalizing.

Record notes only inside an open record's turn, using `bun ${CLAUDE_PLUGIN_ROOT}/scripts/task.ts note .hermit <id>` with the note on stdin. Otherwise skip record notes. Never edit a task file directly.

Create Proposal

**Options:** `--no-artifacts` (alias `--no-artifact`) skips the final artifact refreshes and artifact URL announcement. Useful for batches or callers that refresh afterward.

Create a proposal only when you discover something with real leverage:

• A missing helper or utility that would save significant time across sessions
• A missing validation or guardrail that could prevent real errors
• A workflow improvement that would benefit multiple sessions
• A reusable pattern worth operationalizing

A routine invoking `reflect --check-id <id> --check <namespaced skill>` supplies findings through the normal judge and triage gates with `Evidence Source: scheduled-check/<id>` and `Sessions: none`. Preserve that provenance when creating the proposal.

Commands

• `artifact-render`: `bun ${CLAUDE_PLUGIN_ROOT}/scripts/artifact.ts render <type> .hermit`

Pre-Creation Gate

A caller may supply `Triage-Verdict: <CREATE | SUPPRESS | DUPLICATE line>` from its batch triage. Preserve that verdict and run it through the gate below; skip a second triage dispatch. A proposal is always admin-decided, including external-content findings. Never apply its change before `task answer` records consent.

Pin the hermit root before dispatching:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.ts anchor .hermit

The anchor prints `root` and `memory_dir` and refreshes the proposal digest triage reads. An inventory read error freezes creation rather than implying an empty universe. Compose `Anchor: root=<root> memory_dir=<memory_dir>` from them as the first line of the agent prompt. On an `{"error"}` there is no anchor: do not dispatch, rerun with the absolute state dir the error names in place of `.hermit`.

Without a caller `Triage-Verdict:`, call `hermitd:proposal-triage` before creating the proposal. Pass `Evidence Source:` and `Evidence Origin:` when known:

Anchor: root=<absolute hermit root> memory_dir=<absolute auto-memory dir>
Title: <proposal title>
Evidence Source: <archived-session | current-session | scheduled-check/<id> | operator-request | capability-brainstorm>
Evidence Origin: <own-work | external-content>
Evidence: <one-paragraph evidence summary>

`Evidence Source:` is optional (default: `archived-session`). `Evidence Origin:` is optional (default: `own-work`).

This is a single-candidate call (a batch of one), so the response is one verdict block. Lines 2+ are additive metadata (`closest_prop`, `aligned`, `operator_excerpt`, `overlap_compiled`, `failed_condition`) — read for context if useful but do not branch on them. Record line 1 as the verdict:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.ts gate .hermit --gate triage --caller proposal-create \
    --evidence-source "<evidence source>" --tags '[<caller-supplied tags>]' <<'HERMIT_GATE'
Title: <proposal title>
Verdict: <the agent's line 1, verbatim>
HERMIT_GATE

`evidence_source` is the `Evidence Source:` value the caller passed (default `archived-session`). `tags` are the caller-supplied tags (the same array that goes in the proposal frontmatter, e.g. `["procedure-capture"]`); use `[]` if none. Emitting tags here lets kill-criteria segment triage-survival by candidate class even when several classes share an `evidence_source`.

• `create`: proceed with the steps below
• `duplicate`: stop and return `DUPLICATE: <title> — <task-id>: <reason>` to the caller
• `suppress`: stop and return `SUPPRESS: <title> — <code>: <reason>` from the agent's line 1 to the caller
• `gate_failed` (unrecognized or empty line 1, because the agent errored, returned malformed output, or was terminated before emitting a verdict): fail closed and do not create the proposal. When inside an open task record turn, note it with the record id; otherwise report it to the caller:

  bun ${CLAUDE_PLUGIN_ROOT}/scripts/task.ts note .hermit <id> <<'HERMIT_LINE'
  gate-failed: proposal-triage — <title> — <the agent's line 1, verbatim>
  HERMIT_LINE

The candidate re-surfaces on the next reflect cycle.

How to Create

Call `proposal.ts create` with the full proposal as one heredoc — header lines, a bare `---` separator, then the raw markdown body:

bun ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.ts create .hermit <<'HERMIT_PROPOSAL'
Title: <proposal title>
Source: manual
Session: T-...
Category: improvement
Tags: ["tag-1","tag-2"]
Related-Sessions: []
Findings: <optional one-line summary>
---
## Context
<clear description>

## Problem
<what's wrong or missing>

## Proposed Solution
<concrete steps>

## Impact
<effort vs benefit>

## Verification
<how this will be checked>

## References
<sources, or "n/a — <reason>">

HERMIT_PROPOSAL

The script opens a waiting `kind: proposal` task with requester `agent`, an admin consent decision, and the proposal body in `## Proposal`. It records `created` metrics in the same invocation. It returns one `{id, handle, created}` receipt; use the task id for cross-references and its handle in operator copy. A repeated slug returns the existing open or cancelled task with `created: false`, which you return as `DUPLICATE`. Completed tasks are background.

`{"error":…}` means creation failed: report it without guessing an id. `warnings: ["metrics_append_failed"]` means the record exists but its metrics append failed; report the warning and do not retry the whole call. No implementation starts here. Normal task intake reads [apply.md](apply.md), which also says when an admin instruction is consent.

Header fields:

• `Title:` — required.
• `Source:` —