@etiquekit/etq 1.0.12 → 1.0.14

package/packages/protocol/src/types.ts

@@ -0,0 +1,434 @@
+export const SLICE_STATES = [
+  'draft',
+  'planned',
+  'split',
+  'assigned',
+  'in_progress',
+  'integration',
+  'validated',
+  'closed',
+] as const;
+
+export const TASK_STATES = [
+  'incoming',
+  'claimed',
+  'in_progress',
+  'evidence_ready',
+  'accepted',
+  'countered',
+  'blocked',
+  'resolved',
+] as const;
+
+export const PACKET_STATES = ['PROPOSED', 'ACCEPTED', 'LOCKED', 'PROVISIONED'] as const;
+export const SCRUTINY_STATES = ['OPEN', 'IN_PROGRESS', 'BLOCKED', 'DEFERRED', 'RESOLVED', 'VERIFIED', 'WONT_FIX'] as const;
+export const SCRUTINY_KINDS = ['issue', 'feature', 'feature_set', 'readiness_gate', 'dependency', 'risk', 'research', 'decision', 'migration', 'cleanup'] as const;
+export const CORE_SURFACES = ['backend', 'bff', 'android', 'ios', 'integration'] as const;
+export const ACTOR_KINDS = ['owner', 'worker', 'secretary', 'integrator', 'reviewer'] as const;
+
+export type SliceState = (typeof SLICE_STATES)[number];
+export type TaskState = (typeof TASK_STATES)[number];
+export type PacketState = (typeof PACKET_STATES)[number];
+export type ScrutinyState = (typeof SCRUTINY_STATES)[number];
+export type ScrutinyKind = (typeof SCRUTINY_KINDS)[number];
+export type CoreSurface = (typeof CORE_SURFACES)[number];
+export type Surface = string;
+export type ActorKind = (typeof ACTOR_KINDS)[number];
+
+export interface Actor {
+  actorId: string;
+  kind: ActorKind;
+  displayName: string;
+}
+
+export interface Dependency {
+  taskId: string;
+  kind: 'blocked-by' | 'depends-on';
+}
+
+export interface StateTransition {
+  state: string;
+  actorId: string;
+  at: string;
+  note?: string;
+}
+
+export interface EvidenceItem {
+  kind: 'report' | 'receipt' | 'sample' | 'artifact' | 'note';
+  path: string;
+  summary: string;
+}
+
+export interface EvidenceBundle {
+  bundleId: string;
+  taskId: string;
+  status: 'pending' | 'ready' | 'accepted';
+  items: EvidenceItem[];
+}
+
+export interface Verdict {
+  verdictId: string;
+  sliceId: string;
+  taskId?: string;
+  outcome: 'accepted' | 'countered' | 'blocked' | 'completed';
+  by: string;
+  at: string;
+  note?: string;
+}
+
+export interface WorkBounds {
+  repoRoots: string[];
+  ownedPaths: string[];
+  forbiddenPaths: string[];
+  checks: string[];
+  evidenceFiles: string[];
+}
+
+export interface SliceTask {
+  taskId: string;
+  surface: Surface;
+  title: string;
+  summary: string;
+  scrutinyId: string;
+  state: TaskState;
+  packetId?: string;
+  worktreePath?: string;
+  branchName?: string;
+  owner?: string;
+  workerRole?: string;
+  bounds: WorkBounds;
+  dependencies: Dependency[];
+  transitions: StateTransition[];
+}
+
+export interface Slice {
+  schemaVersion: 'discipline-slice.v1';
+  sliceId: string;
+  projectId: string;
+  title: string;
+  objective: string;
+  scrutinyId: string;
+  state: SliceState;
+  repoRoots: string[];
+  handshakeStorePath: string;
+  tasks: SliceTask[];
+  transitions: StateTransition[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SurfaceDefaults {
+  owner: string;
+  workerRole: string;
+  repoRoots: string[];
+  ownedPaths: string[];
+  forbiddenPaths: string[];
+  checks: string[];
+  evidenceFiles: string[];
+  worktreeTemplate: string;
+}
+
+export interface SliceTaskBlueprint {
+  title: string;
+  summary: string;
+  repoRoots?: string[];
+  ownedPaths?: string[];
+  forbiddenPaths?: string[];
+  checks?: string[];
+  evidenceFiles?: string[];
+  worktreePath?: string;
+  workerRole?: string;
+  owner?: string;
+  dependencies?: Dependency[];
+}
+
+export interface SliceBlueprint {
+  title: string;
+  objective: string;
+  scrutinyId: string;
+  repoRoots?: string[];
+  tasks: Record<string, SliceTaskBlueprint>;
+}
+
+export type WorkerScripts = Record<string, string>;
+
+export interface ProjectManifest {
+  schemaVersion: 'discipline-project.v1';
+  projectId: string;
+  title: string;
+  projectRoot: string;
+  handshakeStorePath: string;
+  logixRepoRoot?: string;
+  scrutinyWorkflowPath: string;
+  defaultWorktreeRoot: string;
+  workerScripts: WorkerScripts;
+  surfaces: Record<string, SurfaceDefaults>;
+  slices: Record<string, SliceBlueprint>;
+}
+
+export interface TaskPacketSpec {
+  packetId: string;
+  sliceId: string;
+  task: SliceTask;
+  project: ProjectManifest;
+}
+
+export interface TaskLedgerRecord {
+  task_id: string;
+  status: 'incoming' | 'pending' | 'resolved';
+  source: string;
+  packet_id: string;
+  action: string;
+  actor: string;
+  created_at: string;
+  ingested_at: string;
+  claimed_by: string | null;
+  claimed_at: string | null;
+  resolved_by: string | null;
+  resolved_at: string | null;
+  resolution_note: string | null;
+  summary: string;
+  chat_text: string;
+}
+
+export interface SliceStatusSnapshot {
+  sliceId: string;
+  sliceState: SliceState;
+  scrutinyState: ScrutinyState;
+  packetStates: Record<PacketState, number>;
+  taskStates: Record<TaskState, number>;
+  unresolvedTasks: string[];
+  readyToClose: boolean;
+  blockers: string[];
+}
+
+export interface SecretaryAction {
+  level: 'info' | 'action' | 'blocked';
+  taskId?: string;
+  surface?: string;
+  summary: string;
+}
+
+export interface SecretarySummary {
+  sliceId: string;
+  actions: SecretaryAction[];
+}
+
+// ============================================================================
+// Supervision (Phase 1)
+// Authority: etiquette/internal/docs/supervision/PHASE1.md
+// Doctrine: llm-substrate/governance/shared-live-supervision.md
+// ============================================================================
+
+export const SESSION_STATUSES = [
+  'running',
+  'paused',
+  'blocked',
+  'awaiting_human',
+  'closed',
+] as const;
+export type SessionStatus = (typeof SESSION_STATUSES)[number];
+
+export const TURN_STATUSES = ['open', 'closed'] as const;
+export type TurnStatus = (typeof TURN_STATUSES)[number];
+
+export const TURN_RESULTS = [
+  'done',
+  'blocked',
+  'handed_off',
+  'stopped',
+  'timed_out',
+] as const;
+export type TurnResult = (typeof TURN_RESULTS)[number];
+
+export const SUPERVISION_COMMANDS = [
+  'status',
+  'pause',
+  'resume',
+  'stop',
+  'approve_next_turn',
+  'redirect_owner',
+  'request_summary',
+  'mark_blocked',
+  'escalate_to_human',
+] as const;
+export type SupervisionCommand = (typeof SUPERVISION_COMMANDS)[number];
+
+export const COMMAND_STATUSES = [
+  'queued',
+  'applied',
+  'rejected',
+  'expired',
+] as const;
+export type CommandStatus = (typeof COMMAND_STATUSES)[number];
+
+export const ACTION_CLASSES = [
+  'coordination_only',
+  'read_only_local',
+  'bounded_verification',
+  'bounded_product_mutation',
+  'human_only',
+] as const;
+export type ActionClass = (typeof ACTION_CLASSES)[number];
+
+export const ALLOWED_COMMAND_IDS = [
+  'inspect_repo',
+  'run_verify',
+  'write_projection',
+  'append_evidence',
+  'write_product_files',
+  'launch_runtime_target',
+] as const;
+export type AllowedCommandId = (typeof ALLOWED_COMMAND_IDS)[number];
+
+export const PROJECTION_POLICIES = [
+  'on_state_change',
+  'on_command_only',
+] as const;
+export type ProjectionPolicy = (typeof PROJECTION_POLICIES)[number];
+
+export const SUPERVISION_EVENT_TYPES = [
+  'session.opened',
+  'session.status_changed',
+  'session.next_owner_changed',
+  'turn.opened',
+  'turn.closed',
+  'command.queued',
+  'command.applied',
+  'command.rejected',
+  'projection.rendered',
+  'rebuild.completed',
+] as const;
+export type SupervisionEventType = (typeof SUPERVISION_EVENT_TYPES)[number];
+
+export const RUNTIME_KINDS = [
+  'codex',
+  'claude-code',
+  'human-mobile',
+  'human-desktop',
+  'other',
+] as const;
+export type RuntimeKind = (typeof RUNTIME_KINDS)[number];
+
+export type SupervisionAudience =
+  | 'all'
+  | 'lead'
+  | 'responder'
+  | 'escalation_owner'
+  | `seat:${string}`;
+
+export interface SupervisionSession {
+  sessionId: string;
+  campaignRoot: string;
+  topic: string;
+  objective: string;
+  status: SessionStatus;
+  leadSeat: string;
+  responderSeat: string;
+  escalationOwner: string;
+  timeCapMinutes: number;
+  turnCap: number;
+  currentTurnId: string | null;
+  nextOwnerHint: string | null;
+  approvedNextTurnJson: string | null;
+  lastBlockerJson: string | null;
+  sourceRefs: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SupervisionTurn {
+  turnId: string;
+  sessionId: string;
+  sequenceNo: number;
+  status: TurnStatus;
+  ownerSeat: string;
+  allowedActionClass: ActionClass;
+  maxDurationMinutes: number;
+  allowedCommands: AllowedCommandId[];
+  repoRoots: string[];
+  ownedPaths: string[];
+  forbiddenPaths: string[];
+  verifyCommands: string[];
+  requiresHumanApproval: boolean;
+  projectionPolicy: ProjectionPolicy;
+  startedAt: string;
+  endedAt: string | null;
+  result: TurnResult | null;
+  summary: string | null;
+  evidenceRefs: string[];
+}
+
+export interface SupervisionCommandRecord {
+  commandId: string;
+  sessionId: string;
+  turnId: string | null;
+  issuedBy: string;
+  command: SupervisionCommand;
+  payloadJson: string;
+  status: CommandStatus;
+  issuedAt: string;
+  appliedAt: string | null;
+  rejectionReason: string | null;
+}
+
+export interface SupervisionEvent {
+  eventId: string;
+  sessionId: string;
+  turnId: string | null;
+  commandId: string | null;
+  eventType: SupervisionEventType;
+  actor: string;
+  audience: SupervisionAudience;
+  at: string;
+  payload: unknown;
+}
+
+export interface SeatCapabilityManifest {
+  schemaVersion: 'discipline-supervision-seat-capabilities.v1';
+  seatId: string;
+  displayName: string;
+  runtimeKind: RuntimeKind;
+  canReadHandshake: boolean;
+  canWriteHandshake: boolean;
+  canReadProductRepo: boolean;
+  canRunBuilds: boolean;
+  canWriteProductRepo: boolean;
+  canLaunchRuntimeTargets: boolean;
+  canAcceptMobileSteering: boolean;
+  allowedActionClasses: ActionClass[];
+  defaultRequiresHumanApprovalForProductMutation: boolean;
+  updatedAt: string;
+}
+
+export interface SupervisionProjection {
+  sessionId: string;
+  renderedAt: string;
+  sessionSnapshot: SupervisionSession;
+  currentTurn: SupervisionTurn | null;
+  pendingCommands: SupervisionCommandRecord[];
+}
+
+export interface ApprovedNextTurnPayload {
+  ownerSeat: string;
+  allowedActionClass: ActionClass;
+  maxDurationMinutes: number;
+  allowedCommands: AllowedCommandId[];
+  repoRoots: string[];
+  ownedPaths: string[];
+  forbiddenPaths: string[];
+  verifyCommands: string[];
+  requiresHumanApproval: boolean;
+  projectionPolicy: ProjectionPolicy;
+  issuedBy: string;
+  issuedAt: string;
+  expiresAt: string | null;
+}
+
+export interface BlockerPayload {
+  reason: string;
+  raisedBy: string;
+  raisedAt: string;
+  escalationOwner: string;
+  evidenceRefs: string[];
+}

package/release/lineage.v0.json

@@ -0,0 +1,15 @@
+{
+  "schema": "etq-release-lineage.v0",
+  "package_name": "@etiquekit/etq",
+  "candidate_version": "1.0.14",
+  "distribution_mode": "bun-typescript-source",
+  "source_repository": "git+https://github.com/leepickdev/etq-devkit.git",
+  "distribution_repository": "git+https://github.com/leepickdev/etq.git",
+  "source_base_commit": "b2384dc782548ce0d712da3bd33e108d977adb44",
+  "registry_floor": "1.0.13",
+  "required_bins": [
+    "etq",
+    "etiquette",
+    "etiquette-core"
+  ]
+}

package/scripts/release-candidate-verify.sh

@@ -0,0 +1,175 @@
+#!/bin/sh
+# Prove the reviewed package tarball from an isolated install. Never publishes.
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+TMPDIR_ROOT=${TMPDIR:-/tmp}
+TMP=$(mktemp -d "$TMPDIR_ROOT/etq-release-candidate.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT INT TERM
+
+LINEAGE="$ROOT/release/lineage.v0.json"
+PACKAGE_NAME=$(node -e 'const m=require(process.argv[1]); process.stdout.write(m.package_name)' "$LINEAGE")
+VERSION=$(node -e 'const m=require(process.argv[1]); process.stdout.write(m.candidate_version)' "$LINEAGE")
+
+cd "$ROOT"
+
+if [ -n "$(git status --porcelain)" ]; then
+  echo "release-candidate: worktree must be clean" >&2
+  exit 1
+fi
+
+bun packages/control/src/cli.ts release readiness --project . --fail-on-blocked >/dev/null
+
+REGISTRY_VERSION=$(npm view "$PACKAGE_NAME" version --json | node -e 'let d=""; process.stdin.on("data",c=>d+=c).on("end",()=>process.stdout.write(JSON.parse(d)))')
+node -e '
+const parse = value => {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  if (!match) throw new Error(`invalid GA version: ${value}`);
+  return match.slice(1).map(Number);
+};
+const candidate = parse(process.argv[1]);
+const current = parse(process.argv[2]);
+for (let i = 0; i < 3; i += 1) {
+  if (candidate[i] > current[i]) process.exit(0);
+  if (candidate[i] < current[i]) process.exit(1);
+}
+process.exit(1);
+' "$VERSION" "$REGISTRY_VERSION" || {
+  echo "release-candidate: $VERSION is not newer than registry $REGISTRY_VERSION" >&2
+  exit 1
+}
+
+TAG_MATCH=$(git ls-remote --tags origin "refs/tags/v$VERSION" "refs/tags/v$VERSION^{}")
+if [ -n "$TAG_MATCH" ]; then
+  echo "release-candidate: remote tag v$VERSION already exists" >&2
+  exit 1
+fi
+
+PACK_DIR="$TMP/pack"
+PREFIX="$TMP/prefix"
+SCRATCH="$TMP/scratch"
+mkdir -p "$PACK_DIR" "$PREFIX" "$SCRATCH"
+
+npm pack --pack-destination "$PACK_DIR" >/dev/null
+TGZ=$(find "$PACK_DIR" -maxdepth 1 -name '*.tgz' -type f -print | sort | sed -n '1p')
+if [ -z "$TGZ" ]; then
+  echo "release-candidate: npm pack produced no tarball" >&2
+  exit 1
+fi
+
+tar -tzf "$TGZ" > "$TMP/files.txt"
+grep -Fxq 'package/release/lineage.v0.json' "$TMP/files.txt"
+grep -Fxq 'package/packages/control/src/cli.ts' "$TMP/files.txt"
+grep -Fxq 'package/packages/protocol/src/index.ts' "$TMP/files.txt"
+if grep -Eq '^package/lib/' "$TMP/files.txt"; then
+  echo "release-candidate: compiled lib output contradicts source-shipping mode" >&2
+  exit 1
+fi
+
+tar -xzOf "$TGZ" package/package.json | node -e '
+let d="";
+process.stdin.on("data", c => d += c).on("end", () => {
+  const p = JSON.parse(d);
+  const expectedName = process.argv[1];
+  const expectedVersion = process.argv[2];
+  if (p.name !== expectedName || p.version !== expectedVersion) process.exit(1);
+  for (const name of ["etq", "etiquette", "etiquette-core"]) {
+    if (!p.bin || typeof p.bin[name] !== "string") process.exit(1);
+  }
+  if (p.prepack || (p.scripts && (p.scripts.prepack || p.scripts["release:build"]))) process.exit(1);
+});
+' "$PACKAGE_NAME" "$VERSION"
+
+npm install --prefix "$PREFIX" --ignore-scripts --no-audit --no-fund "$TGZ" >/dev/null
+ETQ_BIN="$PREFIX/node_modules/.bin/etq"
+ETIQUETTE_BIN="$PREFIX/node_modules/.bin/etiquette"
+CORE_BIN="$PREFIX/node_modules/.bin/etiquette-core"
+for binary in "$ETQ_BIN" "$ETIQUETTE_BIN" "$CORE_BIN"; do
+  if [ ! -x "$binary" ]; then
+    echo "release-candidate: installed binary missing: $binary" >&2
+    exit 1
+  fi
+done
+
+REAL_ETQ=$(node -e 'process.stdout.write(require("fs").realpathSync(process.argv[1]))' "$ETQ_BIN")
+REAL_PREFIX=$(node -e 'process.stdout.write(require("fs").realpathSync(process.argv[1]))' "$PREFIX")
+case "$REAL_ETQ" in
+  "$REAL_PREFIX"/*) ;;
+  *) echo "release-candidate: etq resolved outside isolated prefix" >&2; exit 1 ;;
+esac
+
+EXPECTED="etiquette $VERSION ($PACKAGE_NAME)"
+[ "$($ETQ_BIN --version)" = "$EXPECTED" ]
+[ "$($ETIQUETTE_BIN version)" = "$EXPECTED" ]
+
+PROFILE="$SCRATCH/profile.yaml"
+DRAFT="$SCRATCH/candidate-review.md"
+cat > "$PROFILE" <<'YAML'
+schema: packet-profile.v0
+format: markdown-frontmatter
+filename:
+  pattern: "{{created_at}}-{{kind}}"
+  extension: .md
+frontmatter:
+  fields:
+    - key: kind
+      required: true
+    - key: work_id
+      required: true
+    - key: author
+      required: true
+    - key: recipient
+      required: true
+    - key: created_at
+      required: true
+    - key: changes_state
+      default: false
+title:
+  derive: "{{work_id}} {{kind}}"
+sections:
+  - key: summary
+    heading: Summary
+    required: true
+  - key: evidence
+    heading: Evidence
+    required: true
+  - key: next_step
+    heading: Next Step
+    required: true
+YAML
+
+(cd "$SCRATCH" && "$ETQ_BIN" post \
+  --profile "$PROFILE" \
+  --draft \
+  --out "$DRAFT" \
+  --kind review-return \
+  --work-id RELEASE-CANDIDATE \
+  --author candidate-seat \
+  --recipient review-seat \
+  --summary 'Candidate package installed from the reviewed tarball.' \
+  --evidence 'Exact package identity and isolated executable provenance passed.' \
+  --next-step 'Run the consumer lint bridge.' \
+  --at '2026-07-13T14:00:00.000Z' >/dev/null)
+
+[ -f "$DRAFT" ]
+[ ! -e "$SCRATCH/.etiquette" ]
+grep -Fq 'changes_state: false' "$DRAFT"
+
+mkdir -p "$ROOT/dist"
+TARGET="$ROOT/dist/$(basename "$TGZ")"
+cp "$TGZ" "$TARGET"
+(cd "$ROOT/dist" && shasum -a 256 "$(basename "$TARGET")" > SHA256SUMS)
+rm -f \
+  "$ROOT/dist/SHA256SUMS.sig" \
+  "$ROOT/dist/SHA256SUMS.hmac" \
+  "$ROOT/dist/SIGNATURE_MANIFEST.txt" \
+  "$ROOT/dist/SIGNATURE_REQUIRED.txt"
+SHA256=$(shasum -a 256 "$TARGET" | awk '{print $1}')
+printf 'release-candidate: ok\n'
+printf 'package: %s@%s\n' "$PACKAGE_NAME" "$VERSION"
+printf 'registry_floor_observed: %s\n' "$REGISTRY_VERSION"
+printf 'tarball: %s\n' "$TARGET"
+printf 'checksums: %s\n' "$ROOT/dist/SHA256SUMS"
+printf 'sha256: %s\n' "$SHA256"
+printf 'installed_etq: %s\n' "$REAL_ETQ"
+printf 'draft: %s\n' "$DRAFT"

package/scripts/release-checksum.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# Create a fresh npm tarball and checksum manifest under ignored dist/.
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+TMPDIR_ROOT=${TMPDIR:-/tmp}
+TMP=$(mktemp -d "$TMPDIR_ROOT/etiquette-release-checksum.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT INT TERM
+
+cd "$ROOT"
+sh scripts/release-pack-canary.sh >/dev/null
+mkdir -p dist
+npm pack --pack-destination "$TMP" >/dev/null
+
+TGZ=$(find "$TMP" -maxdepth 1 -name '*.tgz' -print | sort | sed -n '1p')
+if [ -z "$TGZ" ]; then
+  echo "release-checksum: npm pack did not produce a tarball" >&2
+  exit 1
+fi
+
+TARGET="dist/$(basename "$TGZ")"
+cp "$TGZ" "$TARGET"
+(cd dist && shasum -a 256 "$(basename "$TARGET")" > SHA256SUMS)
+
+echo "release-checksum: wrote $TARGET and dist/SHA256SUMS"