Skip to content
ClearedStack

Platform · J.4 Component specifications

Countersign specification

Design

Technical specification for Countersign, the human-accountability queue worker powering tool determinations and anonymous edit approvals on /guides/#decide.

J.4.113 min readLast revised November 2026

Status: Design. A specification. It describes how the component is meant to work, not something you can use on this site today. What the labels mean.

Registry entry · Stage 04

Holds scored candidates and edit proposals until a person decides.

Formerly
cs-04-decide, then Gavel
Namespace
cs-workers
Repository
countersign
Container image
lazarette.clearedstack.svc.cluster.local:5000/countersign
Depends on
Muster
Depended on by
Nothing else in the platform
Boundaries
  • Leases scored candidates and pending proposals from Muster
  • Presents them to the owner and records the decision, with a reason for any override

From the naming registry, which is the one place this component’s name is written down.

On this page
  1. Overview & Role
  2. Runtime & Resource Budget
  3. Interfaces & State Transitions
  4. Sub-Tools & Failure Modes
  5. Security & Clean-Room Boundaries
  6. Related pages

Overview & Role#

Countersign (v0.1.0-draft) powers the human owner's decision and anonymous edit-approval inbox surfaced on /platform/public-edits/ and /platform/public-edits/, replacing the original Stage 6 (Decide). Implemented in the Countersign repository under the MIT License, it records authoritative human determinations for evaluated candidates and gates visitor-submitted ✎ edit proposals before any code or configuration touches Plainforge.

Unlike upstream automated workers, Countersign never makes autonomous judgment calls: final accountability for building, linking, merging, parking, rejecting, overriding, or accepting public edits belongs strictly to the human project owner.

Runtime & Resource Budget#

Countersign runs in the cs-workers Kubernetes namespace under the Standard (Workers) priority class.

AttributeValue
Worker ID / RepoCountersign (countersign)
Namespacecs-workers
Kind / Versionworker · v0.1.0-draft
RAM Budget30 MiB (always-on Go pod)
Runtime AI Calls0 (human-in-the-loop gate + deterministic state routing)
Local Spool/var/spool/cs (buffers pending decision acknowledgments across Muster restarts)
Build & DeployBuilt with ko (no Docker) by Keelworks, signed with cosign in Lazarette, deployed by Shipkeeper via Server-Side Apply

Interfaces & State Transitions#

Countersign interacts with Muster in the clearedstack namespace over ServiceAccount-authenticated HTTP (CONTRACT_VERSION=v1) and surfaces two transparent queues via pub.* read-only views on clearedstack.com:

  1. Tool Determinations Queue (scored and screened-out overrides):
    • Approve (Build) → approved: Advances the candidate to Waybill for provenance stamping and clean-room spec compilation.
    • Link → linked: Records an existing free, private external tool in the catalog (Chartroom) without rebuilding.
    • Merge → merged: Folds scope into an existing or planned parent tool repository.
    • Park → parked: Defers a viable idea with a named blocker for scheduled Tidegauge revisit.
    • Reject → rejected: Permanently archives the candidate with its rubric score and rationale.
    • Override → observed: Returns a screened-out item to observed only when accompanied by an explicit written reason logged publicly.
  2. Anonymous Public Edit Proposals (core.edit_proposal, pending_approval):
    • Receives DATA, CONFIG, and ISSUE proposals (≤ 4 KB) submitted via any ✎ button after they clear Muster's 5-layer anti-spam shield.
    • On owner Approve, dispatches Bellbuoy on the urgent lane (Proposed → Approved → Building → Live). Declined proposals are logged without altering Plainforge or core.* data.

Sub-Tools & Failure Modes#

Countersign intentionally has zero sub-tools (subTools: []), because final product determinations and edit approvals are human decisions rather than automated pattern rules.

Sanitized Failure Modes

Error CodeTriggerPlatform Behavior
E_PARSEMalformed determination payload, missing written rationale on an override, or invalid ownership_map.json target on an edit proposal.Rejected cleanly by Muster; item remains in its current queue state with a fingerprinted error logged.
E_TIMEOUTTransient timeout reaching Muster during decision commit.Buffered in /var/spool/cs and retried in order until acknowledged.

Because Countersign has no tools/<case>/ sub-tools, it never enters needs_subtool (E_NEEDS_SUBTOOL).

Security & Clean-Room Boundaries#

  • 5-layer anti-spam gate before Countersign: Anonymous ✎ edit proposals must pass browser Proof-of-Work, a hidden honeypot field, daily-salted IP hash rate limiting (zero raw IPs stored), and strict 4 KB schema validation against ownership_map.json (with HTML/scripts stripped) before entering pending_approval.
  • Zero unreviewed cluster mutations: No anonymous edit or external submission can touch Plainforge, core.* state, or running pods until explicitly approved in Countersign.
  • Public accountability & pod hardening: All decisions, overrides, and edit outcomes are visible in read-only pub.* views without login. The pod runs non-root with dropped capabilities, a read-only root filesystem (except /var/spool/cs), zero database credentials, and default-deny NetworkPolicy.

Found a mistake, or something that has gone out of date? Open an issue or write to [email protected]. This page is a text file you can read and correct: Source of this page.