Skill and Workflow Proposal Tracking - Plan

Overview

Implement a project-level proposal ledger that lets Hive preserve the full history of skill and workflow candidates, evaluations, authoritative decisions, supersession, and rollback evidence. Validated task and evaluation source events will open candidates and append evaluation evidence automatically; configured operators and policy authorities will append accepted/rejected decisions, authorize supersession, and record rollback. The ledger, CLI, compiled wiki views, and supplied context will remain tracking-only and will never activate, install, publish, or revert a skill or workflow.

The implementation will add a versioned proposal domain under Hive's existing hive/state authority. It will reuse canonical JSON, atomic file writes, project commit locking, task-activity provenance, plan-review compare-and-swap, shared secret redaction, and llm-wiki source pinning. A proposal-owned immutable source-event inbox will provide the durable, discoverable recovery queue; canonical candidate records and proposal events remain the sole inputs to projections and compiled views. The implementation will not reuse the monolithic WorkLedger JSONL replay format because one malformed line currently invalidates a whole stream, which conflicts with per-record failure isolation.

This plan covers the complete curated brainstorm scope. It provides a strict producer contract for later skill-evolution and workflow-evolution pipelines, but it does not create those workflows or change the public workflow descriptor grammar.

Goal capsule

• Objective: Operators and future proposal workflows can recover accepted, rejected, superseded, and rolled-back lessons from one durable, queryable history without changing active behavior.
• Means: Store one immutable candidate record and independent append-only event files per proposal, derive projections through one query layer, and compile deterministic CLI and wiki views from those projections.
• Authority: brainstorm.md governs product behavior. Configured evaluator and decision authority bindings govern mutations. The canonical proposal record and event files govern history.
• Execution profile: Cross-cutting Ruby implementation with schema, storage, event, concurrency, CLI, prompt-context, llm-wiki, and integration coverage.
• Stop conditions: Stop if implementation would require activating a proposal, rewriting historical records, treating an LLM-authored summary as canonical, or weakening the configured terminal-decision boundary.
• Tail ownership: Implementation includes code, tests, schemas, and wiki documentation. It does not authorize a release, deployment, package publication, skill publication, workflow installation, or version change.

Assumptions

• A proposal subject needs a stable project-relative subject reference in addition to kind and revision; this binds evidence and relevance queries without copying an active skill or workflow into the ledger.
• Authenticated task/evaluation activity is materialized as an immutable proposal-owned source event. That inbox is the bounded trigger and recovery input; task-journal entries are correlation mirrors only, and proposal records/events are the only inputs to projections and compiled views.
• Hive's current same-user local trust model can enforce configured identities, capabilities, expected-state checks, and immutable provenance. It cannot cryptographically prove that a same-UID CLI caller is a human rather than an agent; stronger identity proof is separate security work.
• Visibility and retention are required metadata in v1. Producer-supplied classifications may only narrow configured access, never widen it; unclassified evidence defaults to restricted/digest-only. Restricted artifacts remain external and contribute only safe metadata and digests; v1 does not add an external-artifact deletion engine.
• No dedicated proposal workflow is added here. Later workflows will emit the typed submission/evaluation contract and consume the proposal context selector.

Product Contract

Problem frame

Hive currently retains task artifacts, benchmark outputs, review evidence, and wiki knowledge in separate places. It has no canonical record that connects one skill or workflow candidate revision to all of its positive and negative evaluations, one authoritative decision, successor revisions, or a later rollback. This makes rejected and rolled-back lessons easy to lose and encourages later agents to repeat failed experiments.

Generic task completion events are not sufficient. They do not carry a validated candidate or evaluation contract, and the general event surfaces are either fail-soft observability or closed module-trigger vocabularies. The proposal domain therefore needs its own strict task-event bridge while preserving Hive's existing project-state authority and recovery semantics.

Requirements

Actors and event ownership

• R1. Hive must create candidate revisions and append evaluation evidence only from validated, typed task submission/evaluation source events, retaining proposer, evaluator, task, attempt, source-event, and commit provenance.
• R2. Proposers may submit candidates and evidence, and configured named evaluators may append evaluations; only a caller holding the configured same-user operator or policy capability may append an accepted/rejected decision, authorize a lifecycle-changing supersession, or record rollback. This is a capability boundary, not proof that a same-UID caller is human or non-agent.

Canonical identity and history

• R3. Hive must mint one permanent opaque proposal ID for each candidate revision, retain multiple evaluations on that ID, and give revised or retried candidates distinct IDs linked by supersedes or retries.
• R4. Candidate data must be immutable, while evaluation, decision, supersession, and rollback facts must be independent append-only events with stable event identity and actor/source provenance.
• R5. Submission must require subject kind, subject reference, revision, proposed change, motivation/evidence, and author provenance; the created record must additionally contain the permanent opaque proposal ID minted by Hive. Evaluation and decision history must preserve evaluator provenance, method or benchmark identity, result, rationale, and relevant task/commit links.

Lifecycle and concurrency

• R6. Schema-valid drafts are allowed; one authoritative event establishes accepted or rejected; an authority may reject without an evaluation only with an explicit no_evaluation rationale category; supersession links a successor; rollback is allowed only after historical acceptance and must retain the acceptance while recording the reverted revision, reason, and external revert reference.
• R7. Every valid evaluation must survive, including contradictory and post-decision evidence. Lifecycle mutations must compare the observed lifecycle head and explicitly considered evaluation set, reject stale or conflicting lifecycle facts, allow unrelated evaluation appends without starving an in-flight decision, and treat exact source-event retries as idempotent.

Tracking and compiled knowledge

• R8. No proposal operation or generated artifact may provision, activate, install, update, remove, publish, or revert an active skill or workflow.
• R9. Canonical individual records and events must deterministically compile to wiki/proposals.json and wiki/proposals.md; the machine view includes valid drafts, while the terminal human summary excludes drafts and both views derive from the same normalized projections.
• R10. Malformed, incomplete, oversize, symlinked, unknown-version, duplicate, or structurally inconsistent inputs must be logically quarantined with bounded redacted diagnostics while all unaffected valid proposals still compile.

Discovery, privacy, and rollout

• R11. Operators and agents must be able to browse the wiki and use CLI list, show, and filter surfaces backed by live canonical projections rather than a potentially lagging compiled wiki branch.
• R12. Future proposal runs with a controller/dispatcher-authored typed proposal subject binding in the durable attempt record must receive a deterministic relevant set of closed typed facts under item and shared-appendix byte caps. Rejected and rolled-back lessons remain eligible, while all free-form proposal, evidence, rationale, and instruction text and all restricted evidence are excluded from automatic context.
• R13. Project-visible text must be bounded and secret-redacted before persistence; private or restricted evidence must retain only safe labels, digests, size/type metadata, visibility, retention policy, and non-secret source references. Producer-supplied visibility/retention may only narrow configured policy, and unclassified evidence defaults to restricted/digest-only.
• R14. V1 must initialize lazily from new proposal events and must not scan, reinterpret, or backfill historical tasks, benchmarks, skills, or workflows.
• R15. Untrusted proposal text, labels, paths, and links must reject disallowed control characters and URL schemes, then use output-specific escaping for terminal, Markdown, JSON, and prompt-context surfaces so retained evidence cannot alter surrounding structure.

Key decisions carried from the brainstorm

• KD1. Tracking is the complete v1 behavior; activation and actual revert execution remain separately approval-gated work. Governs R8.
• KD2. Each candidate revision gets a new permanent opaque ID, with lineage expressed through links rather than identity reuse. Governs R3.
• KD3. Immutable candidate data plus append-only events is canonical; mutable status snapshots are derived only. Governs R4, R6, and R7.
• KD4. One configured capability-authorized lifecycle decision wins through compare-and-swap over lifecycle-affecting facts plus its explicitly considered evaluation set; unrelated concurrent evaluations do not starve the decision, and last-writer-wins is forbidden. Governs R2 and R7.
• KD5. Valid compilation continues around quarantined inputs, and drafts do not enter terminal summaries. Governs R9 and R10.
• KD6. Wiki browsing, CLI discovery, and bounded future context are all required consumers of the same retained evidence. Governs R11 and R12.

Actors

• A1. A proposer supplies one candidate revision, its motivation, and evidence through a proposal-aware task event.
• A2. A configured evaluator appends one or more method-bound results without gaining terminal-decision authority.
• A3. A configured operator or policy authority appends the accepted/rejected decision, authorizes predecessor supersession, and may later record a compensating rollback.
• A4. Hive validates, mints identities, persists events, projects state, reconciles interrupted ingestion, and compiles views without choosing outcomes.
• A5. Future proposal workflows and agents read bounded relevant lessons but cannot gain mutation authority from supplied context.

Acceptance examples

• AE1. A review-prompt candidate improves held-out review recall with no protected regression. An authorized acceptance preserves the benchmark, considered evaluations, rationale, and links in the canonical history, machine index, and wiki summary while the active prompt remains byte-identical.
• AE2. A broader planning-prompt candidate improves its target score but exceeds false-positive or cost thresholds. Rejection retains both the improvement and threshold failure, leaves the active prompt unchanged, and remains discoverable through wiki, CLI, and future bounded context.
• AE3. A revised candidate receives a distinct ID and reciprocal supersession link. A historically accepted candidate can later add a rollback event that preserves the original decision and links the compensating external revert and reason.
• AE4. Two conflicting decisions from one observed head allow at most one terminal event. Repeated compilation is byte-stable, and malformed neighbors produce safe quarantine diagnostics without changing valid output bytes.

Requirements Trace

Scope Boundaries

In scope

• A versioned project-level proposal namespace under the existing hive/state branch, including an immutable task/evaluation source-event inbox used only for admission and recovery.
• Immutable candidate records, independent append-only events, source-event idempotency, derived lifecycle projections, and per-input logical quarantine.
• A task-bound production producer service and hive proposal submit/evaluate surfaces that emit typed proposal source events from trusted task/attempt context, without scraping arbitrary Markdown or benchmark files.
• Durable evaluator admission at attempt dispatch, configured decision/policy authority, head-digest compare-and-swap, authority-gated supersession, retries, and rollback records.
• Live CLI list/show/filter plus task-bound submit/evaluate, authority-gated decide/supersede/rollback, and deterministic refresh surfaces with versioned JSON envelopes.
• A pinned-state compiler and llm-wiki bridge for a machine index and human terminal summary.
• Bounded, deterministic, secret-safe proposal context for already proposal-bound tasks and future proposal workflow stages.
• V1 schemas, configuration, failure diagnostics, acceptance fixtures, architecture/CLI/state documentation, and a wiki log fragment.

Deferred to Follow-Up Work

• A packaged evidence-driven skill/workflow evolution workflow and its stage prompts, budgets, role routing, and operator UX.
• Approval-gated activation of an accepted candidate and automated execution of a compensating revert.
• Historical proposal backfill or import from existing tasks, benchmark folders, wiki pages, commits, or active skill/workflow stores.
• Web/TUI proposal management, aggregate analytics, pruning, and an external restricted-artifact retention/deletion service.
• Cryptographic or OS-privileged proof that a terminal action came from a human rather than another same-UID process.

Out of scope

• Treating Hive::Events, generic task.completed, module-daemon delivery, arbitrary result files, or LLM-written wiki prose as proposal authority.
• Copying raw private notes, credentials, transcripts, large benchmark artifacts, or unrestricted patches into canonical proposal files or prompt context.
• Mutating lib/hive/agent_skills provision/publish paths, config/agent-skills.yml, workflow-package managed stores, or workflow install/update/remove/publish commands from proposal operations.
• Release, deployment, tag, package publication, version selection, or unrelated cleanup of the proposal-adjacent workflow and llm-wiki code.

Planning Contract

Key technical decisions

• KTD1. Store each creation record and event as an independent canonical JSON file under proposals/v1/, using Hive::CanonicalJSON, Hive::AtomicFile, no-follow reads, project commit locking, and explicit file-size/schema bounds. This adapts the immutable-file pattern from Hive::Modules::EventLedger and the CAS discipline from Hive::PlanReview without adopting WorkLedger's fail-whole-stream JSONL replay.
• KTD2. Use a durable event-first transaction owned by Hive::Proposals::Producer. For CLI and service callers alike, the producer resolves trusted task/attempt context, snapshots the exact task/activity/inbox paths, validates and writes one immutable source event, commits the task transaction with additive exact paths, and rolls that snapshot back on failure before synchronous ingestion begins a separate canonical transaction. Committed hive/state blobs are authoritative: reconciliation cleans or quarantines crash-left worktree-only remnants under the commit lock, scans only committed unconsumed receipts, and replays each receipt into its exact canonical commit before reporting convergence.
• KTD3. Derive lifecycle from orthogonal facts: the accepted/rejected decision, optional superseded_by, optional retry lineage, and optional rollback. An effective status is a query result, so supersession or rollback never erases historical acceptance or rejection.
• KTD4. Give every mutation a source-event idempotency key. Evaluations append independently. Decisions, supersession, and rollback require an observed lifecycle-head version/digest plus the explicitly considered evaluation IDs under the owning lock. A new evaluation outside that considered set does not invalidate the mutation; changes to lifecycle facts or a considered evaluation do.
• KTD5. Extend the versioned durable Attempts::Record with immutable evaluator binding, configuration fingerprint, and a typed proposal subject (proposal_id, revision) set only by the controller/dispatcher at admission under the existing state lock. Source commits fix evaluator authority: ingestion and crash replay verify event integrity and the historical admitted binding without reauthorizing against later configuration; revocation affects new events. Agent-authored fields and prompt text never create or alter either binding, and lifecycle authority is resolved independently.
• KTD6. Build one normalized Projection/Query result consumed by CLI renderers, the deterministic compiler, and the context selector. The compiler reads an exact pinned hive/state source commit, while CLI reads live canonical state.
• KTD7. Apply privacy before persistence: project-visible text is bounded and passed through Hive::SecretPatterns; producer-requested visibility/retention can only narrow configured policy; and unclassified or restricted evidence stores only a digest and safe metadata. Retention is declarative in v1 and every surface reports enforcement=none; it never hides, deletes, redacts, or expires canonical bytes. Automatic context applies a second projection filter and includes only closed typed facts, using the remaining bytes after the existing context appendix under MAX_PROMPT_APPENDIX_BYTES.
• KTD8. Expose a real controller-owned Hive::Proposals::Producer through task-bound hive proposal submit/evaluate commands and a reusable service call for later workflows. This task does not add a proposal workflow, stages, templates, or proposal-specific descriptor grammar.

High-level technical design

The diagrams define component ownership and ordering. Method names and exact class splits may change during implementation, but the authority and data-flow boundaries must not.

flowchart LR
    Producer[Task-bound proposal producer] --> Binding[Trusted task attempt and actor binding]
    Binding --> Inbox[(Immutable source-event inbox)]
    Binding -. correlation mirror .-> Journal[Task activity]
    Inbox --> Ingestor[Proposal ingestor]
    Inbox --> Reconciler[Bounded reconciler]
    Reconciler --> Ingestor
    Ingestor --> Store[(proposals/v1 records and events)]
    Store --> Projection[Projection and query]
    Projection --> CLI[Live CLI]
    Projection --> Context[Bounded proposal context]
    Store --> Compiler[Pure pinned-source compiler]
    Compiler --> Index[wiki/proposals.json]
    Compiler --> Summary[wiki/proposals.md]

sequenceDiagram
    participant P as Producer
    participant B as Trusted binding
    participant Q as Source-event inbox
    participant J as Task activity mirror
    participant G as GitOps commits
    participant I as Proposal ingestor
    participant R as Reconciler

    P->>B: resolve active task/attempt and actor
    B->>Q: create validated immutable source event
    B->>J: append bounded correlation entry
    B->>G: commit normal task/log paths plus exact inbox path
    G-->>I: committed source event ID and digest
    I->>I: validate source idempotency and current head
    I->>G: commit exact canonical record/event paths
    alt canonical commit lands
        G-->>P: source event consumed once
    else ingestion interruption or failure
        R->>Q: scan bounded unconsumed source IDs
        R->>I: replay exact source event
        I->>G: no-op replay or commit missing canonical paths
    end

stateDiagram-v2
    [*] --> draft: immutable candidate created
    draft --> accepted: authoritative decision
    draft --> rejected: authoritative decision
    draft --> superseded: authority-approved successor event
    accepted --> superseded: authority-approved successor event
    rejected --> superseded: authority-approved successor event
    accepted --> rolled_back: compensating event
    superseded --> rolled_back: historical decision was accepted

Evaluations may append in every displayed state. A decision records the exact evaluation IDs and head it considered. The projection retains the decision, lineage, and rollback as separate facts even when its displayed effective status is superseded or rolled_back.

Canonical and generated layout

proposals/v1/
  inbox/<source-event-id>.json
  records/<proposal-id>.json
  events/<proposal-id>/<version>-<event-id>.json

lib/hive/proposals.rb
lib/hive/proposals/
  producer.rb
  source_event.rb
  source_event_store.rb
  evaluator_authority.rb
  record.rb
  event.rb
  store.rb
  projection.rb
  ingestor.rb
  reconciler.rb
  decision_service.rb
  authority.rb
  query.rb
  compiler.rb
  context_selector.rb

wiki/proposals.json
wiki/proposals.md

The proposals/v1/ tree is project state, not a main-worktree source directory. Inbox files are durable admission/recovery receipts but are not projection or compilation inputs; canonical records/events carry their source-event provenance. Quarantine is logical: invalid bytes stay at their original bounded path, while projections and compilation exclude the affected input and emit a stable safe diagnostic. Generated views are never read back as canonical input.

Committed blobs on hive/state, not the mutable .hive-state checkout, are authoritative for every proposal mutation. The inbox also maintains a committed consumed-source index/low-water state and terminal quarantine facts so reconciliation examines only unconsumed receipts at constant steady-state cost. Inbox bytes remain immutable; pruning is deferred.

Implementation constraints

• Add a distinct additional_pathspecs: keyword to the task commit API for exact proposal inbox/activity paths while leaving existing exclusive pathspecs: behavior unchanged. Reconciliation commits only exact canonical/index/quarantine paths.
• Make Producer own an independent task/activity/inbox snapshot, commit, rollback, and ingestion transaction. Under the commit lock, compare the checkout to committed hive/state, clean or quarantine worktree-only remnants, and never ingest them. If canonical append is uncommitted, restore it; if its receipt is committed, replay it into the exact deterministic canonical commit before convergence is reported.
• Store the source task ID, task/workflow/ownership generation, attempt ID, immutable evaluator binding and configuration fingerprint where applicable, artifact reference and digest, actor binding, timestamp, source commit, and source event ID on every ingested record/event. A changed payload under an existing source event ID is a typed conflict.
• Allocate a monotonically increasing proposal-local event version under the proposal/project lock. A malformed filename still reserves its numeric slot so recovery never overwrites it.
• A decision normally names valid considered evaluation IDs and preserves their evaluator, method/benchmark, and result plus rationale and links. Authority may instead append a terminal rejection with an empty set only when it supplies the closed no_evaluation rationale category. Later evidence remains visible without rewriting the decision.
• Enforce admission-time per-project and per-proposal event/byte ceilings and per-authority rate limits with typed quota failures; limits count immutable inbox, canonical, quarantine, and diagnostic bytes.
• A new record may request predecessor lineage, but only configured terminal authority may append the CAS-protected predecessor superseded event and make that relation effective. The event must name the distinct existing successor; projection derives the reciprocal link without mutating either candidate record. Supersession validates a matching subject kind/reference and rejects self-links and lineage cycles. A proposer may create a retries lineage link without changing predecessor status.
• A rollback must reference a historically accepted proposal, the reverted subject revision, an external revert task/commit/link, and a reason. It records the external action but never performs it.
• Compilation must sort records/events/diagnostics, serialize canonical JSON, render Markdown from the same normalized fields, omit wall-clock refresh timestamps, and write both outputs inside a disposable managed llm-wiki worktree. The pair becomes public only through one wiki Git commit; interrupted or failed refreshes must leave no committed torn pair.
• The machine index must expose all valid projections plus safe quarantine diagnostics. The human summary must exclude drafts, retain rejected and rolled-back lessons, and carry projection/evidence digests so parity is testable.
• Admission must reject disallowed control characters and unsafe link schemes. Terminal, Markdown, JSON, and prompt renderers must encode retained text for their own structural context; redaction alone is not an encoding boundary.
• No proposal-facing code may depend on or call active skill provisioners/publishers or workflow-package mutation stores.

Implementation Units

U1. Add the versioned canonical proposal domain

Goal: Create independently validatable immutable records/events, opaque identity, isolated replay, and derived projection primitives.

Requirements: R3-R6, R10, R13, and R15.

Dependencies: None.

Files:

• lib/hive/proposals.rb
• lib/hive/proposals/record.rb
• lib/hive/proposals/event.rb
• lib/hive/proposals/store.rb
• lib/hive/proposals/projection.rb
• lib/hive/canonical_json.rb
• lib/hive/schemas.rb
• schemas/hive-proposal-record.v1.json
• schemas/hive-proposal-event.v1.json
• test/unit/proposals/record_test.rb
• test/unit/proposals/event_test.rb
• test/unit/proposals/store_test.rb
• test/unit/proposals/projection_test.rb
• test/unit/schema_files_test.rb
• test/unit/schemas_test.rb
• test/fixtures/proposals/

Approach:

1. Define closed versioned schemas for one candidate record and the evaluation, decision, supersession, and rollback event variants, including bounded visibility/retention and safe-link fields.
2. Mint a UUID-backed opaque proposal ID through one injectable identity factory; use canonical digests only for integrity, observations, and idempotency.
3. Persist one immutable record and one immutable, proposal-local-versioned file per event with atomic create semantics, fsync, safe relative paths, and no-follow bounded reads.
4. Validate each file independently and return valid typed objects plus stable quarantine diagnostics rather than failing the collection.
5. Project orthogonal decision, lineage, rollback, evidence, and effective-status facts without writing a mutable canonical snapshot.
6. Resolve evidence visibility/retention as the intersection of configured policy and any producer request, default absent classifications to restricted/digest-only, and persist retention as informational metadata with enforcement=none on every projection. Reject forbidden controls and URL schemes and keep structural output encoding in consuming renderers.

Patterns to follow: lib/hive/modules/event_ledger.rb, lib/hive/plan_review/store.rb, lib/hive/plan_review/projection.rb, lib/hive/canonical_json.rb, lib/hive/atomic_file.rb, and lib/hive/secret_patterns.rb.

Test scenarios:

• A valid submission containing the required subject, change, evidence, provenance, visibility, and retention fields creates one draft with one permanent ID.
• Reopening an existing record with byte-identical canonical content is idempotent; different content for the same proposal ID conflicts without changing the original.
• Multiple valid evaluations remain independently replayable and retain contradictory results.
• Invalid JSON, a non-object top level, missing fields, unknown schema versions, oversize files, symlinks, duplicate IDs, and invalid event versions each quarantine only the affected input.
• A malformed event filename reserves its version and a later append selects the next unused version rather than overwriting it.
• A dangling proposal reference or lineage cycle is diagnosed deterministically while unrelated valid projections remain unchanged.
• Project-visible token-shaped text is redacted and bounded; restricted or unclassified evidence persists only digest and safe metadata.
• A producer cannot widen configured visibility or retention, and disallowed terminal controls, Markdown-breaking controls, and non-approved URL schemes fail before persistence without affecting valid neighbors.
• Retention values round-trip through canonical, CLI, index, wiki, and context provenance as declarative metadata with enforcement=none; no expiry hides or changes immutable bytes.

Verification: The record and event schemas validate every supported variant, canonical replay is stable across filesystem order, and a mixed-validity fixture yields the same valid projections as its valid-only subset plus bounded diagnostics.

U2. Produce and ingest durable typed task/evaluation source events

Goal: Give real task/evaluation execution a controller-owned path that admits named evaluators and automatically opens or advances canonical proposal state from a durable, authenticated, recoverable source event.

Requirements: R1-R5, R7, R13-R15; supports KTD2, KTD5, and KTD8.

Dependencies: U1.

Files:

• lib/hive/proposals/producer.rb
• lib/hive/proposals/source_event.rb
• lib/hive/proposals/source_event_store.rb
• lib/hive/proposals/evaluator_authority.rb
• lib/hive/proposals/ingestor.rb
• lib/hive/proposals/reconciler.rb
• lib/hive/attempts/context.rb
• lib/hive/attempts/record.rb
• lib/hive/attempts/repository.rb
• lib/hive/attempts/dispatcher.rb
• lib/hive/config.rb
• templates/project_config.yml.erb
• lib/hive/task_journal.rb
• lib/hive/task_activity.rb
• lib/hive/commands/proposal.rb
• lib/hive/commands/run.rb
• lib/hive/git_ops.rb
• lib/hive/daemon/dispatcher.rb
• schemas/hive-proposal-source-event.v1.json
• schemas/hive-attempt-record.v2.json
• test/unit/proposals/producer_test.rb
• test/unit/proposals/source_event_test.rb
• test/unit/proposals/source_event_store_test.rb
• test/unit/proposals/evaluator_authority_test.rb
• test/unit/proposals/ingestor_test.rb
• test/unit/proposals/reconciler_test.rb
• test/unit/attempts/context_test.rb
• test/unit/attempts/record_test.rb
• test/unit/attempts/repository_test.rb
• test/unit/attempts/dispatcher_test.rb
• test/unit/config_test.rb
• test/unit/task_journal_test.rb
• test/unit/task_activity_test.rb
• test/unit/git_ops_test.rb
• test/integration/proposal_event_routing_test.rb

Approach:

1. Add the evaluator portion of a closed proposal configuration subtree: named identities map to allowed workflow/stage/agent-profile or policy bindings, and evidence visibility/retention ceilings and approved link schemes are fail-closed defaults.
2. Version and migrate Attempts::Record/repository so dispatch durably stores the immutable evaluator binding, configuration fingerprint, and controller-authored typed proposal subject. Attempts::Context reconstructs only from that record; payloads, prompt text, and CLI actor/evaluator/subject strings cannot create or replace trusted bindings.
3. Add controller-owned Hive::Proposals::Producer, callable through task-bound commands and later runners, which owns an independent exact-path task/activity/inbox snapshot, additive commit, rollback, and synchronous-ingestion transaction for both CLI and service callers.
4. At source-event admission, validate the artifact, durable subject/evaluator bindings, quotas, safe evidence, and then store the admitted evaluator binding/fingerprint immutably. Ingestion and replay verify event integrity and that historical admission rather than current configuration. Permanently invalid/conflicting events enter a committed terminal quarantine fact with bounded typed reason instead of retrying forever.
5. Mirror only a bounded source-event ID/digest correlation entry to TaskActivity; task journals remain observability, not the queue or source of proposal recovery.
6. Add additional_pathspecs: to Hive::GitOps.hive_commit for the exact inbox/activity paths, composing with default task/log staging. Preserve the existing exclusive semantics of pathspecs: and regression-test all existing callers.
7. After the source event is durably committed, invoke the ingestor synchronously. Use the source event ID as canonical idempotency, and commit only the exact record/event paths in a second rollback boundary so an ingestion failure cannot erase the source receipt.
8. Add bounded reconciliation on proposal commands and daemon lifecycle over committed hive/state trees only. Under the commit lock, clean/quarantine worktree-only remnants, enumerate the committed unconsumed-source index, replay missing exact canonical commits, no-op exact replays, and terminally quarantine permanent integrity/admission conflicts. Advance a committed consumed low-water/index so work stays constant as history grows; never scan journals or legacy history.
9. Enforce configured aggregate project/proposal event and byte quotas plus per-authority rate limits before the source commit, returning typed quota failures without partial state.
10. Keep the producer service workflow-neutral so the sibling evolution workflow can use it without this unit registering new stages, templates, or descriptor grammar.

Execution note: Start with crash-point integration coverage around the real task activity and GitOps boundaries before changing commit behavior.

Patterns to follow: lib/hive/task_activity.rb, lib/hive/task_journal.rb, lib/hive/commands/run.rb, lib/hive/commands/workflow.rb, lib/hive/commit_or_rollback.rb, and lib/hive/git_ops.rb.

Test scenarios:

• A real task-bound submit command and controller service create one committed inbox event, invoke ingestion, mint and commit exactly one proposal, and return the same ID on exact source-event replay.
• A real task-bound evaluate command targets an existing proposal, uses the evaluator binding admitted at dispatch, commits one inbox event, and appends one evaluation with that source event ID.
• A wrong workflow/stage/agent profile, unconfigured evaluator identity, or payload-only binding is rejected before commit. A source admitted before later configuration change/revocation still ingests and replays from its historical binding; revocation rejects new sources.
• Changed artifact bytes under a reused event ID fail as a conflict and do not create or mutate canonical state.
• Invalid, missing, raced, symlinked, oversize, unsafe-link, or control-bearing source artifacts fail before an inbox event, activity mirror, or proposal mutation is admitted.
• A failed source commit restores the normal task/activity/inbox transaction; no uncommitted source receipt survives as if durable.
• A crash after the inbox commit but before canonical append reconciles to one proposal; a crash after canonical append but before its commit restores only the uncommitted canonical paths and later converges from the inbox.
• Additive path staging retains all normal task-directory and log changes while excluding an unrelated dirty proposal file and unrelated task journal entry.
• A malformed inbox neighbor is diagnosed independently and does not block ingestion of valid source events.
• A permanently invalid or conflicting committed receipt becomes a visible terminal quarantine entry returned by filter and the machine index, with bounded retries and no retry loop.
• Reconciliation work remains constant as consumed history grows, and crash-left uncommitted inbox/canonical files are never ingested; committed receipts converge to exact canonical commits.
• Project/proposal byte/event ceilings and authority rate limits fail closed under flood tests without exhausting disk or leaving partial receipts.
• A pre-feature project with historical task journals remains proposal-empty until a new typed inbox event is committed; reconciliation never opens historical journals.

Verification: The production task/attempt-to-inbox-to-ingestor flow and dispatch-admitted evaluator binding are proven without stubs, every crash point converges idempotently, the task commit keeps its default staging semantics, and each source event maps to exactly one canonical record/event mutation.

U3. Enforce decision, supersession, and rollback authority

Goal: Preserve all evidence while allowing only fresh configured authorities to append lifecycle-changing facts.

Requirements: R2, R5-R8, R13, and R15.

Dependencies: U1 and U2.

Files:

• lib/hive/proposals/authority.rb
• lib/hive/proposals/decision_service.rb
• lib/hive/config.rb
• templates/project_config.yml.erb
• test/unit/proposals/authority_test.rb
• test/unit/proposals/decision_service_test.rb
• test/unit/config_test.rb

Approach:

1. Extend U2's closed proposal configuration subtree with operator/policy lifecycle authorities and policy fingerprints; fail closed when authority is absent or stale.
2. Resolve accepted/rejected, supersession, and rollback authority independently from the configured same-user operator or policy capability before any lifecycle-changing event, and document that unrestricted same-UID agents can exercise that capability.
3. Under the proposal/project lock, compare the caller's expected lifecycle-head version/digest and explicitly considered evaluation IDs against current lifecycle facts and those evaluation projections. Evaluation appends outside the considered set do not invalidate the operation.
4. Append one accepted/rejected event with considered evaluation IDs, method/result projections, rationale, task/commit links, authority provenance, and authority-policy fingerprint; permit an empty considered set only for an authority-authored rejection with the typed no_evaluation rationale category.
5. Treat an exact decision source retry as a no-op, reject a different terminal outcome or rationale as a conflict, and continue to retain later evaluation evidence without rewriting the decision.
6. Let a new candidate request predecessor lineage, but require configured lifecycle authority plus head-digest CAS to append the predecessor supersession event naming the existing successor. Derive the reciprocal effective link in projection without mutating either candidate record. Keep retries lineage-only; validate distinct IDs, consistent subjects, matching requested lineage when present, and acyclic lineage.
7. Permit rollback only when historical acceptance exists, require the reverted revision, reason, and external revert reference, and record rather than execute that action.

Patterns to follow: lib/hive/plan_review/decision.rb, lib/hive/plan_review/decision_service.rb, lib/hive/provider_health/repository.rb, and lib/hive/patrol_fix/receipt_store.rb.

Test scenarios:

• A configured named evaluator whose binding passed U2 can append evidence but cannot decide, supersede, or record rollback.
• A configured operator and a valid policy receipt can decide; a free-form actor string, stale policy fingerprint, absent authority configuration, or agent-only context cannot.
• Two evaluations arriving concurrently both survive with distinct event IDs and versions.
• Two different decisions from the same observed digest allow at most one; the loser receives a typed stale/conflicting-decision result.
• Evaluations can stream before and during a decision: appends outside the explicitly considered set do not starve it, while a changed/missing considered evaluation or lifecycle-head change makes it stale. Post-decision evidence remains visible.
• An exact terminal retry is a no-op; a second outcome, altered rationale, or different evidence set is rejected.
• A decision with no considered evaluation is rejected unless it is an authority-authored rejection with no_evaluation; missing method/result for named evaluations or absent required provenance is rejected.
• A proposer can create the distinct successor and request lineage but cannot change predecessor status; configured lifecycle authority can append the CAS-protected predecessor event, from which projection derives the reciprocal link. Retries link a new ID without changing predecessor status. Self-links, duplicate successors, subject mismatches, and cycles fail.
• An accepted proposal can record rollback and preserve acceptance; a draft or rejected proposal cannot roll back.
• Accepted, rejected, superseded, and rolled-back service operations leave representative active skill and workflow files byte-identical.

Verification: Lifecycle projections preserve every event and historical decision, lifecycle authority is checked independently from U2 evaluator admission and trusted context, concurrency has no last-writer-wins path, and no lifecycle operation reaches an active mutation store.

U4. Compile deterministic machine and llm-wiki views

Goal: Produce byte-stable proposal knowledge from an exact state commit while isolating invalid inputs and preserving ordinary llm-wiki publication semantics.

Requirements: R8-R11, R13, and R15.

Dependencies: U1 and U3.

Files:

• lib/hive/proposals/compiler.rb
• schemas/hive-proposal-index.v1.json
• lib/hive/schemas.rb
• templates/llm-wiki/post-commit-refresh.sh
• .llm-wiki/post-commit-refresh.sh
• lib/hive/llm_wiki_bootstrap.rb
• lib/hive/llm_wiki_bootstrap/scripts.rb
• wiki/proposals.json
• wiki/proposals.md
• test/unit/proposals/compiler_test.rb
• test/unit/schema_files_test.rb
• test/unit/schemas_test.rb
• test/unit/llm_wiki_bootstrap_test.rb
• test/integration/proposal_wiki_refresh_test.rb
• test/integration/llm_wiki_post_commit_refresh_test.rb
• test/integration/wiki_command_test.rb

Approach:

1. Make the compiler accept a pinned hive/state tree/ref and separate output root, then independently validate every record/event and build one normalized sorted projection set.
2. Render canonical JSON and deterministic Markdown from that set; include valid drafts only in JSON, include safe quarantine diagnostics, and render rejected, superseded, and rolled-back lessons without an LLM summarization pass. Escape Markdown structural delimiters and raw HTML, and render only approved URL schemes without changing canonical field values.
3. Register hive-proposal-index v1. Extend installed/template hooks so canonical proposal commits resolve the primary checkout when invoked from .hive-state, retain the exact source commit, and enter a proposal-only compile queue that neither launches an LLM provider nor consumes ordinary auto-pending/breaker budget. Inbox/index/cursor-only changes do not trigger refresh.
4. In coalesced refreshes, select the latest queued proposal-affecting state source deterministically and prevent later unqueued state from leaking into the compile.
5. For mixed batches run the pure compiler after the wiki agent; for proposal-only batches skip the agent and compile directly inside the same disposable managed worktree. Stage both paths together and publish one wiki commit, preserving publication guards and loop suppression.
6. Make hive proposal refresh enter this boundary. refresh --check compiles only to an ephemeral directory outside every managed worktree and project checkout, compares bytes, removes it, and never replaces the live pair.

Patterns to follow: lib/hive/llm_wiki_bootstrap.rb, lib/hive/llm_wiki_bootstrap/scripts.rb, templates/llm-wiki/post-commit-refresh.sh, and lib/hive/canonical_json.rb.

Test scenarios:

• Covers AE4. Repeated compilation of the same source tree is byte-identical under shuffled filesystem enumeration and different wall-clock times.
• One malformed record/event, unknown version, duplicate ID, or dangling link produces a stable redacted diagnostic while valid output bytes match the valid-only fixture.
• Covers AE1 and AE2. Accepted and rejected fixtures carry the same proposal ID, decision, evaluation facts, rationale, task/commit links, evidence digests, and projection digest across canonical projection, JSON, and Markdown.
• Drafts appear in the machine index but not the terminal Markdown summary; explicit rejected and rolled-back lessons remain present.
• A canonical proposal record/event commit triggers refresh and compiles from that exact pinned commit; a source-inbox-only commit does not, and later state events do not leak into the batch.
• A canonical .hive-state commit resolves the primary project's wiki pipeline and drives exactly one refresh; a burst of proposal-only commits coalesces without provider launch, pending-budget consumption, or breaker trip.
• A wiki agent cannot edit the generated proposal facts, and committing unchanged generated output does not trigger a refresh loop.
• Control-bearing fields fail admission; Markdown delimiters, raw HTML, and unsafe external links cannot create headings, links, HTML, or other structure in the generated summary.
• An interrupted or failed refresh leaves the previous committed pair visible and the unpublished worktree disposable; a successful refresh publishes both changed files in one commit, so no committed torn JSON/Markdown pair is reachable.
• refresh --check uses an external ephemeral output root and leaves the primary and managed worktrees byte-clean, including ignored/untracked state.

Verification: The compiler is a pure function of the pinned valid inputs plus deterministic diagnostics, generated artifacts pass their schema/content checks, output encoding preserves structure, and the managed wiki refresh publishes the pair only as one commit under existing wiki publication rules.

U5. Add live CLI discovery, authority actions, and bounded future context

Goal: Make retained evidence usable by operators and future proposal stages without leaking restricted data or granting prompt-derived authority.

Requirements: R2, R7-R13, and R15.

Dependencies: U1-U4.

Files:

• lib/hive/proposals/query.rb
• lib/hive/proposals/context_selector.rb
• lib/hive/commands/proposal.rb
• lib/hive/cli.rb
• lib/hive/config.rb
• lib/hive/stages/base.rb
• lib/hive/context_provenance.rb
• templates/project_config.yml.erb
• schemas/hive-proposal-list.v1.json
• schemas/hive-proposal-show.v1.json
• schemas/hive-proposal-mutation.v1.json
• lib/hive/schemas.rb
• test/unit/proposals/query_test.rb
• test/unit/proposals/context_selector_test.rb
• test/unit/commands/proposal_test.rb
• test/unit/schema_files_test.rb
• test/unit/schemas_test.rb
• test/unit/config_test.rb
• test/unit/stages/base_context_provenance_test.rb
• test/integration/proposal_command_test.rb
• test/integration/cli_usage_error_json_test.rb

Approach:

1. Add hive proposal list, show, and filter over the live store, with stable human and versioned JSON renderers from one query result; list defaults to terminal records, filter can opt into drafts and quarantine diagnostics, and show exposes complete contradictory history. Escape terminal control syntax in human output and preserve structural JSON encoding in machine output.
2. Register hive-proposal-list, hive-proposal-show, and hive-proposal-mutation v1. Complete commands through U2-U4; list/show report lifecycle-head version and digest, and decide/supersede/rollback require both plus the considered evaluation IDs. Return typed unauthorized, stale, conflict, invalid, quota, or quarantine errors.
3. Make refresh use the managed llm-wiki publication boundary and make refresh --check non-publishing; neither path writes the generated pair directly into a live worktree.
4. Select context only from the controller/dispatcher-authored typed proposal subject in the durable attempt record, validated against canonical ID/revision; fail closed when absent, stale, or malformed. Rank exact subject/lineage first, then related typed method/tag facts.
5. Supply only bounded closed typed facts: canonical IDs, enums, timestamps, numeric evaluation outcomes, and fixed labels. Exclude every free-form proposal, evidence, rationale, and instruction field. Compute the proposal byte cap from the bytes remaining under ContextProvenance::MAX_PROMPT_APPENDIX_BYTES after the existing appendix, and record configured/effective budget, selected IDs/digest, and truncation in provenance so composition never falls back to an undecorated prompt.
6. Use the same normalized query semantics for CLI filters and context selection so a selected proposal can be reproduced by an operator.

Patterns to follow: lib/hive/commands/workflow.rb, lib/hive/commands/findings.rb, lib/hive/context_provenance.rb, lib/hive/context_provenance/context_receipt.rb, and lib/hive/stages/base.rb.

Test scenarios:

• List returns terminal proposals by default; filter deterministically selects by kind, subject, revision, status, relation, evaluator, and method and can include drafts/quarantine diagnostics.
• Show exposes all evaluations, the considered-evaluation set, decision, lineage, rollback, provenance, visibility, retention, and safe diagnostics without restricted content.
• Human and JSON CLI outputs agree on proposal identity/status; invalid IDs, unauthorized actions, stale observations, and conflicting decisions use stable typed envelopes and exit behavior.
• Submit/evaluate refuse absent or spoofed durable task/attempt/subject bindings; decide/supersede/rollback refuse evaluator-only authority and stale lifecycle-head version/digest; refresh publishes only through the managed wiki boundary.
• Covers AE2. A relevant rejected planning-prompt lesson is returned in full through explicit read-only CLI/wiki access; automatic context includes only its typed IDs, status, timestamps, method label, and numeric threshold outcome.
• Exact subject/lineage matches outrank weaker matches; deterministic ties remain byte-stable; count and byte caps expose truncation without partial UTF-8 or partial records.
• Restricted/unclassified artifacts, token-shaped text, private notes, unsafe links, and every free-form field appear in no automatic context or provenance payload beyond permitted typed metadata/digests.
• An existing context receipt that consumes most of the 4 KiB appendix leaves only the measured remainder for proposal facts; overflow truncates whole proposal items, records the effective budget, and preserves the existing receipt rather than dropping the appendix.
• Terminal escape sequences display inertly and JSON remains structurally valid; malicious free-form proposal text is absent from automatic prompt context.
• Equivalent proposal context is supplied across supported agent providers, while unrelated workflows and proposal-unbound tasks receive none.

Verification: Operators can reproduce context selection through live CLI filters, all mutation commands preserve U2 evaluator admission and U3 lifecycle authority/CAS, and prompt-context tests prove deterministic bounds, redaction, provenance, and injection isolation.

U6. Prove the curated lifecycle and document the operating contract

Goal: Close the full acceptance matrix through real integrations and document how proposal history is produced, decided, refreshed, queried, retained, and kept tracking-only.

Requirements: R1-R15 and AE1-AE4.

Dependencies: U1-U5.

Files:

• test/fixtures/proposals/accepted-review-prompt/
• test/fixtures/proposals/rejected-planning-prompt/
• test/fixtures/proposals/superseded-rollback/
• test/fixtures/proposals/mixed-validity/
• test/integration/proposal_tracking_test.rb
• test/integration/proposal_command_test.rb
• wiki/modules/proposals.md
• wiki/commands/proposal.md
• wiki/index.md
• wiki/architecture.md
• wiki/component-boundaries.md
• wiki/state-model.md
• wiki/cli.md
• wiki/testing.md
• wiki/log.d/<timestamp>-proposal-tracking.md

Approach:

1. Drive accepted, evaluated rejection, no_evaluation rejection, superseded/rolled-back, streaming-evaluation decision, crash recovery, quota, quarantine, and mixed-validity examples through the real durable attempt binding, producer, committed inbox, ingestor, store, authority, query, compiler, CLI, context, and wiki-refresh seams.
2. Assert projection parity by stable identity and digests rather than independent textual summaries.
3. Snapshot representative active skill and workflow stores before each lifecycle and compile flow, then prove every byte remains unchanged.
4. Document committed-blob authority, Producer transaction ownership, versioned attempt migration and subject/evaluator admission, same-UID capability limits, historical evaluator authorization, lifecycle CAS/no_evaluation, quotas/rate limits, consumed index and terminal quarantine, CLI/wiki access, compile-only refresh behavior, declarative retention with enforcement=none, typed-facts-only context and shared appendix budget, rollout, and recovery.
5. Add one append-only wiki change fragment and update source-backed navigation without editing compiled wiki/log.md directly.

Execution note: Use fixtures for deterministic regression proof; any optional live proposal exercise is supplementary and must not activate, publish, or revert a skill/workflow.

Test scenarios:

• Covers AE1. The recall-improving review prompt is accepted from the configured authority and appears consistently everywhere without changing the prompt.
• Covers AE2. The target-improving but threshold-breaking planning prompt is rejected, retains both positive and negative evidence, and is discoverable through all three access paths.
• Covers AE3. The successor has a distinct linked ID, and rollback preserves historical acceptance plus the external revert reference without executing a revert.
• Covers AE4. Conflicting decisions admit one, compilation is byte-stable, and malformed neighbors do not block valid results.
• Continuous evaluation appends do not starve a decision over a fixed considered set; a lifecycle race still makes it stale.
• An unevaluated candidate can reach terminal rejected state only through the authority-gated no_evaluation rationale and appears in the U6 acceptance matrix.
• Crash-left worktree files are ignored/cleaned, committed receipts replay exactly, revoked-after-admission evaluations ingest, permanent failures become visible quarantine, and consumed-history growth does not increase scan work.
• Proposal-only refresh bursts resolve the primary checkout, launch no provider, consume no ordinary pending budget, and leave refresh --check worktrees clean.
• A clean existing project initializes no proposal files and imports no historical task; its first new task-bound submission lazily creates the v1 namespace and durable source receipt.
• Security fixtures prove classification requests cannot widen policy and stored text cannot change terminal, Markdown, JSON, or prompt structure.
• Documentation examples and JSON fixtures validate against the shipped schemas and match actual CLI output.

Verification: The complete acceptance suite passes through production composition roots rather than hand-written events, source-backed wiki documentation matches the implemented contract, active stores remain byte-identical, and the repository's focused, integration, broad test, exact coverage, formatting, and documentation gates are green.

Verification Contract

Verification must proceed from narrow domain proof to real cross-boundary behavior, then to the repository gate. No result from a stubbed store, a hand-written event, a live wiki worktree, or an LLM-generated summary can replace the corresponding production-path proof.

1. Schema and domain gate: Proposal record/event/index and CLI schemas are registered, closed, and covered. Store, projection, quarantine, idempotency, lineage, privacy, and deterministic replay unit tests pass.
2. Event and transaction gate: Versioned durable attempt/subject/evaluator bindings, Producer-owned snapshots, committed source authority, additional_pathspecs: compatibility, exact commit replay, worktree-remnant cleanup, consumed index, terminal quarantine, quotas/rates, and no-backfill tests pass.
3. Authority and concurrency gate: Historical dispatch admission, same-user operator/policy capability, lifecycle-head plus considered-set CAS, streaming evaluations, conflicting decision, evaluated/no_evaluation rejection, retry, supersession, and rollback tests pass.
4. Compiler and wiki gate: Registered schemas, mixed-validity byte stability, pinned state source, primary-checkout resolution, proposal-only compile queue without provider/breaker budget, one-commit publication, external --check scratch, and loop suppression pass.
5. CLI and context gate: Human/JSON list/show/filter/action tests, head version/digest contracts, quarantine visibility, renderer encoding, typed-facts-only selection, shared appendix remaining-byte bounds, receipt preservation, provenance, redaction, and provider parity pass.
6. Acceptance and regression gate: AE1-AE4 pass end to end, active skill/workflow snapshots are unchanged, no historical data is imported, and the default repository suite, exact coverage gate, formatting checks, schema drift checks, and wiki tests pass in a neutral environment.

No release, deployment, package publication, activation, or external revert is part of verification.

Risks

Definition of Done

• Every R1-R15 requirement is implemented and traced to passing unit or integration evidence.
• AE1-AE4 pass through real task/attempt binding, producer, source inbox, canonical-store, authority, query, compiler, CLI, context, and wiki-refresh composition roots.
• Canonical proposal records/events remain immutable and replayable; malformed inputs are isolated with deterministic safe diagnostics.
• Concurrent evaluations survive without starving decisions; lifecycle mutations use lifecycle-head plus considered-set CAS, and accepted history survives supersession and rollback.
• wiki/proposals.json and wiki/proposals.md are byte-stable products of one pinned source projection and become public together through one ordinary llm-wiki commit.
• CLI and wiki expose rejected and rolled-back lessons, while automatic future context exposes only closed typed facts under the shared appendix budget, without classification widening, restricted evidence, secret leakage, structural injection, or prompt-instruction authority.
• Active skill and workflow stores remain byte-identical across every proposal lifecycle and compile operation.
• Existing projects are not backfilled, and the first new task-bound proposal source event initializes the v1 namespace lazily.
• Source-backed wiki documentation, schemas, and append-only change history describe the verified implementation accurately.
• Focused tests, integration tests, the repository's broad/default gate, exact coverage requirement, formatting, schema-drift checks, and wiki checks are green.
• Abandoned experimental code, unused compatibility layers, generated scratch files, and duplicate projection/query paths are absent from the final diff.
• No release, deployment, tag, publication, activation, revert execution, or version change has been performed.