wowbagger 0.1.0-alpha.1

package/skills/wowbagger/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: wowbagger
+description: Use when coordinating work through a wowbagger ledger — reading the ready queue, inspecting or filing an item, transitioning one through its lifecycle, taking a work claim, or publishing claimed work. Triggers on "ready queue", "what should I work on", "file a ledger item", "close this item", "claim this work", "publish claimed work", or any mention of a wowbagger ledger. Not for general backlog talk where no wowbagger ledger exists.
+---
+
+# Wowbagger
+
+A work ledger that is plain Markdown in Git. Every item is a file; every change
+is a reviewable diff. The core is read-only unless you explicitly ask it to
+publish something.
+
+## Before anything else: check the core
+
+This skill does **not** bundle the wowbagger core. It drives an installed one,
+so a version mismatch is detectable rather than silent.
+
+```sh
+wowbagger capabilities --json
+```
+
+Read `contract_version` from the result. **This skill requires
+`contract_version: 2`.**
+
+- Command not found → the core is not installed. Tell the user, point them at
+  <https://github.com/lstutzman/wowbagger>, and stop. Do not fall back to
+  editing ledger files by hand — hand-edits bypass validation and atomic
+  publication, which is the whole point of the tool.
+- `contract_version` is anything other than `2` → stop and say so plainly. A
+  core reporting `1` predates schema version 2, where `depends_on` records
+  declared prerequisites rather than only live blockers; an older or newer core
+  may have changed the request or response shape. Do not guess.
+
+Run this once per session before the first ledger command, not before every
+command.
+
+## Reading
+
+These never modify anything. Prefer them.
+
+```sh
+wowbagger validate --ledger <dir> --json
+wowbagger ready     --ledger <dir> --as-of <YYYY-MM-DD> --json
+wowbagger inspect   --ledger <dir> --id wb_... --json
+wowbagger capabilities --json
+```
+
+- `ready` is the source of truth for what is workable. Never infer the queue by
+  reading files yourself — dependency and parent rules decide it, and a
+  directory listing does not.
+- `--as-of` is a real calendar date. Use today's date; do not invent one to make
+  an item appear.
+- `validate` returns `{"valid":true,"errors":[]}` on a clean ledger and exits
+  nonzero on a broken one. Run it after any change you make.
+- `inspect` returns a lossless byte snapshot plus a SHA-256 revision. That
+  revision is what `transition` compares against, so inspect immediately before
+  transitioning.
+
+## Writing
+
+Every write is an explicit, reviewable Git change. Show the user the command
+before running it.
+
+```sh
+wowbagger create     --ledger <dir> --input request.json --json
+wowbagger transition --ledger <dir> --input request.json --json
+```
+
+- `create` publishes only a caller-supplied canonical ID, atomically and
+  no-clobber. It will not invent an ID for you.
+- `transition` changes **one** item. If the change would require touching a
+  dependent or a child, it refuses. That refusal is correct — make it a
+  reviewable multi-file Git change instead of forcing it.
+- See `docs/mutation-contract.md` in the wowbagger repository for the request
+  and response shapes.
+- After any write, run `validate` and show the user the resulting diff.
+
+## Work claims are merge-coordinated
+
+```sh
+wowbagger provision --ledger <dir> --json
+wowbagger claim capabilities --ledger <dir> --json
+wowbagger claim read|acquire|renew|release --ledger <dir> --input request.json --json
+wowbagger publish-claimed --ledger <dir> --input request.json --json
+wowbagger claim-verify --ledger <dir> --json
+```
+
+The Git-backed capability reports `mode: "merge-coordinated"` and
+`safe_exclusive_dispatch: false`. Say both facts plainly. An acquire uses
+observed-state compare-and-swap, and a claimed publication checks the active
+owner generation and expected item revision. This protects cooperating
+worktrees that use the protocol.
+
+It is not exclusive coordination. Direct filesystem writes, hostile processes,
+other clones, and alternate tools can bypass the protocol. Never present a
+claim as a lock or build a dispatch loop that requires exclusive ownership.
+
+Use the claimed write path as one complete loop:
+
+1. Run `provision` once for the ledger. Keep its `ledger_namespace`.
+2. Run `claim capabilities --ledger <dir> --json`. Stop if the namespace is
+   absent or the mode is not `merge-coordinated`.
+3. Read the current claim record. Acquire with its observed state in
+   `expected`; keep the returned `owner_id`, `epoch`, and expiry as the fence.
+4. Renew before the lease expires if the work continues.
+5. Inspect the item again. Build the complete desired item bytes.
+6. Call `publish-claimed` with a unique operation ID, the exact inspected
+   revision, the candidate bytes and digest, and the active claim fence. Never
+   retry with only the operation ID; retry the complete request.
+7. Commit the item change, or merge the worker commit into the coordinating
+   branch.
+8. Run `claim-verify` after the commit or merge. It finalizes the Git outcome,
+   repairs response-loss cases, and reports later revision drift. Run it again
+   before the next fenced operation if the prior outcome was not final.
+9. Release the claim with its current observed state.
+10. Run `validate` and show the resulting diff.
+
+Legacy `create` refuses an ID with claim history. Legacy `transition` refuses an
+item with an active claim. Do not bypass those refusals. Read
+`docs/work-claim-contract.md` in the wowbagger repository for exact request and
+response envelopes, refusal precedence, and recovery rules.
+
+## Working the unclaimed loop
+
+1. `validate` the ledger.
+2. `ready --as-of <today>` to see what is actually workable.
+3. `inspect` the item you intend to take, and read its body — the acceptance
+   criteria live there, not in the metadata.
+4. Do the work.
+5. `inspect` again for the current revision, then `transition` to close it.
+6. `validate`, then show the diff.
+
+## Friction is a finding
+
+If the tool makes something harder than doing it by hand, that is a defect worth
+recording. File it as a ledger item rather than leaving it in a transcript —
+that is what the ledger is for, and it is how this tool is meant to improve.

package/src/adapter/approval.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+
+import { hasExactMembers } from './schema-helpers.js';
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const NONCE = /^[A-Za-z0-9._-]{16,128}$/;
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const SAFE_ID = /^[A-Za-z0-9._-]{1,128}$/;
+
+function refuse(error_code, detail = {}) {
+  return { ok: false, error_code, detail };
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function decodeCanonicalBase64(value) {
+  if (typeof value !== 'string' || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    return null;
+  }
+  const bytes = Buffer.from(value, 'base64');
+  return bytes.toString('base64') === value ? bytes : null;
+}
+
+function validCanonicalTime(value) {
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) && new Date(parsed).toISOString().replace('.000Z', 'Z') === value;
+}
+
+function validInvocationBinding(value) {
+  if (!hasExactMembers(value, [
+    'request_id', 'adapter', 'core', 'workspace', 'limits',
+    'instruction_set_digest', 'handoff_digest',
+  ]) || !SAFE_ID.test(value.request_id)) return false;
+  if (!hasExactMembers(value.adapter, ['id', 'version', 'contract_version'])
+    || typeof value.adapter.id !== 'string'
+    || typeof value.adapter.version !== 'string'
+    || !Number.isSafeInteger(value.adapter.contract_version)) return false;
+  if (!hasExactMembers(value.core, [
+    'executable_identity', 'contract_version', 'argv', 'input_base64',
+  ])
+    || !DIGEST.test(value.core.executable_identity)
+    || !Number.isSafeInteger(value.core.contract_version)
+    || !Array.isArray(value.core.argv)
+    || !value.core.argv.every((argument) => typeof argument === 'string')
+    || decodeCanonicalBase64(value.core.input_base64) === null) return false;
+  if (!hasExactMembers(value.workspace, ['id', 'root', 'cwd', 'ledger'])
+    || !Object.values(value.workspace).every((member) => typeof member === 'string')) return false;
+  if (!hasExactMembers(value.limits, [
+    'context_bytes', 'stdout_bytes', 'stderr_bytes', 'timeout_ms',
+  ])
+    || !Object.values(value.limits).every((member) => Number.isSafeInteger(member) && member >= 0)
+    || value.limits.timeout_ms < 1) return false;
+  return DIGEST.test(value.instruction_set_digest)
+    && (value.handoff_digest === null || DIGEST.test(value.handoff_digest));
+}
+
+function approvalSchemaError(value) {
+  if (!hasExactMembers(value, [
+    'approval_version', 'source', 'nonce', 'issued_at', 'expires_at', 'invocation_digest',
+  ])) return true;
+  return value.approval_version !== 1
+    || typeof value.source !== 'string'
+    || typeof value.nonce !== 'string'
+    || !NONCE.test(value.nonce)
+    || !DIGEST.test(value.invocation_digest)
+    || !RFC3339.test(value.issued_at)
+    || !validCanonicalTime(value.issued_at)
+    || !RFC3339.test(value.expires_at)
+    || !validCanonicalTime(value.expires_at);
+}
+
+export function canonicalInvocationDigest(binding) {
+  if (!validInvocationBinding(binding)) throw new TypeError('invalid invocation binding');
+  const canonical = canonicalJson(binding);
+  return {
+    canonical,
+    digest: `sha256:${createHash('sha256').update(Buffer.from(canonical)).digest('hex')}`,
+  };
+}
+
+export function verifyTrustedApproval({
+  approval,
+  binding,
+  now,
+  redeemedNonces,
+  trustedSources = new Set(['consumer']),
+}) {
+  if (approvalSchemaError(approval)) return refuse('invalid-approval');
+  if (!(trustedSources instanceof Set)
+    || trustedSources.size !== 1
+    || !trustedSources.has('consumer')
+    || approval.source !== 'consumer') {
+    return refuse('approval-source-untrusted', { source: approval.source });
+  }
+  if (!RFC3339.test(now) || !validCanonicalTime(now)) {
+    return refuse('invalid-approval-time', { member: 'now' });
+  }
+  const issued = Date.parse(approval.issued_at);
+  const expires = Date.parse(approval.expires_at);
+  const current = Date.parse(now);
+  if (issued >= expires) return refuse('invalid-approval-time-order');
+  if (current < issued) return refuse('approval-not-yet-valid', { issued_at: approval.issued_at });
+  if (current >= expires) return refuse('approval-expired', { expires_at: approval.expires_at });
+  if (!(redeemedNonces instanceof Set)) return refuse('invalid-approval');
+  if (redeemedNonces.has(approval.nonce)) {
+    return refuse('approval-replayed', { nonce: approval.nonce });
+  }
+  let invocationDigest;
+  try {
+    invocationDigest = canonicalInvocationDigest(binding).digest;
+  } catch {
+    return refuse('invalid-approval-binding');
+  }
+  if (invocationDigest !== approval.invocation_digest) return refuse('approval-binding-mismatch');
+  redeemedNonces.add(approval.nonce);
+  return { ok: true, nonce: approval.nonce };
+}
+
+export function verifyMutationAuthority({ command, approval, approvalOptions }) {
+  if (command !== 'create' && command !== 'transition' && command !== 'patch') {
+    return { ok: true, authority: [] };
+  }
+  if (approval === null || approval === undefined) {
+    return refuse('consumer-approval-required', { command });
+  }
+  const verified = verifyTrustedApproval({ approval, ...approvalOptions });
+  if (!verified.ok) return verified;
+  return { ok: true, authority: [`core:${command}`], nonce: verified.nonce };
+}

package/src/adapter/bootstrap.js

@@ -0,0 +1,43 @@
+import { normalizeJsonValue, parseJsonRequest } from '../request.js';
+
+// The bootstrap wire (contract section 3.3): exactly one strict UTF-8 JSON
+// object in on stdin, then stdin closes; exactly one strict JSON object plus
+// one LF out on stdout. `readBootstrapRequest` collects bounded stream
+// bytes before parsing — `parseJsonRequest` decodes UTF-8 fatally and reports
+// duplicate members and trailing bytes through `issues` rather than
+// throwing, so a non-empty `issues` array is the only acceptable-parse gate.
+export async function readBootstrapRequest(stream, { maxBytes, errorCode = 'invalid-describe-request' } = {}) {
+  const chunks = [];
+  let byteLength = 0;
+  // A stream error must surface as a refusal, never as an uncaught rejection: the
+  // entrypoint has to emit exactly one JSON object plus one LF and exit zero on
+  // every path (§3.3), including a stdin read failure.
+  try {
+    for await (const chunk of stream) {
+      byteLength += chunk.length;
+      if (maxBytes !== undefined && byteLength > maxBytes) {
+        return {
+          ok: false,
+          error_code: errorCode,
+          detail: { member: 'request', reason: 'byte-limit-exceeded', limit_bytes: maxBytes },
+        };
+      }
+      chunks.push(chunk);
+    }
+  } catch {
+    return { ok: false, error_code: errorCode, detail: { member: 'request', reason: 'stream-error' } };
+  }
+  const bytes = Buffer.concat(chunks);
+  const parsed = parseJsonRequest(bytes);
+  if (parsed.issues.length > 0) {
+    return { ok: false, error_code: errorCode, detail: { member: 'request_json' } };
+  }
+  return { ok: true, request: normalizeJsonValue(parsed.value), bytes };
+}
+
+// Writes exactly one JSON object plus one trailing LF, and nothing else.
+export function writeBootstrapResponse(stream, response) {
+  return new Promise((resolve, reject) => {
+    stream.write(`${JSON.stringify(response)}\n`, (error) => (error ? reject(error) : resolve()));
+  });
+}

package/src/adapter/context.js

@@ -0,0 +1,34 @@
+import { validateHandoffCarrier } from './handoff.js';
+import { validateInstructionInput } from './instructions.js';
+
+function refuse(error_code, detail = {}) {
+  return { ok: false, error_code, detail };
+}
+
+export function validateInvokeContext({
+  instruction_input: instructionInput,
+  handoff_carrier: handoffCarrier,
+  context_bytes: contextBytes,
+  instruction_limits: instructionLimits,
+  handoff_options: handoffOptions,
+}) {
+  const instructions = validateInstructionInput(instructionInput, instructionLimits);
+  if (!instructions.ok) return instructions;
+  const handoff = handoffCarrier === null
+    ? { ok: true, byte_length: 0 }
+    : validateHandoffCarrier(handoffCarrier, handoffOptions);
+  if (!handoff.ok) return handoff;
+  if (handoffCarrier !== null
+    && handoffCarrier.resume_request.instruction_set_digest !== instructions.instruction_set_digest) {
+    return refuse('handoff-instruction-set-mismatch');
+  }
+  const totalBytes = instructions.total_bytes + handoff.byte_length;
+  if (totalBytes > contextBytes) {
+    return refuse('context-limit-exceeded', {
+      instruction_bytes: instructions.total_bytes,
+      handoff_bytes: handoff.byte_length,
+      context_bytes: contextBytes,
+    });
+  }
+  return { ok: true, total_bytes: totalBytes, instructions, handoff };
+}

package/src/adapter/core-probe.js

@@ -0,0 +1,231 @@
+import { hasExactMembers } from './schema-helpers.js';
+
+// The version 2 core command list, in the fixed advertising order (contract
+// section 3). `describe.js` also needs this order to validate the
+// `core.commands` subset it accepts, so it is exported from here.
+export const CORE_COMMAND_ORDER = Object.freeze([
+  'capabilities', 'create', 'inspect', 'patch', 'ready', 'transition', 'validate',
+]);
+export const CORE_CONTRACT_VERSION = 2;
+
+function refuse(error_code, detail) {
+  return { ok: false, error_code, detail };
+}
+
+function backendIssue(backend) {
+  if (!hasExactMembers(backend, ['name', 'coordination_scope'])
+    || backend.name !== 'local-filesystem'
+    || backend.coordination_scope !== 'same-working-copy-cooperative-writers') {
+    return 'result.backend';
+  }
+  return null;
+}
+
+function inspectOperationIssue(inspect) {
+  if (!hasExactMembers(inspect, ['supported', 'write_scope', 'cas_scope'])
+    || inspect.supported !== true
+    || inspect.write_scope !== 'none'
+    || inspect.cas_scope !== 'none') {
+    return 'result.operations.inspect';
+  }
+  return null;
+}
+
+function createOperationIssue(create) {
+  if (!hasExactMembers(create, [
+    'supported', 'write_scope', 'cas_scope', 'publication_visibility', 'publication_probe',
+  ])
+    || create.supported !== true
+    || create.write_scope !== 'single-item'
+    || create.cas_scope !== 'requested-id-lock'
+    || create.publication_visibility !== 'atomic-no-clobber-or-fail'
+    || create.publication_probe !== 'per-ledger-operation') {
+    return 'result.operations.create';
+  }
+  return null;
+}
+
+function transitionOperationIssue(transition) {
+  if (!hasExactMembers(transition, ['supported', 'write_scope', 'cas_scope'])
+    || transition.supported !== true
+    || transition.write_scope !== 'single-item'
+    || transition.cas_scope !== 'exact-byte-sha256') {
+    return 'result.operations.transition';
+  }
+  return null;
+}
+
+function patchOperationIssue(patch) {
+  if (!hasExactMembers(patch, ['supported', 'write_scope', 'cas_scope'])
+    || patch.supported !== true
+    || patch.write_scope !== 'single-item'
+    || patch.cas_scope !== 'exact-byte-sha256') {
+    return 'result.operations.patch';
+  }
+  return null;
+}
+
+// Every member except `supported` is a permanent advisory-claims invariant:
+// claims never protect publication, never fence writers, and must never
+// advertise safe exclusive dispatch.
+function workClaimOperationIssue(workClaim) {
+  if (!hasExactMembers(workClaim, [
+    'supported', 'api_version', 'mode', 'claim_protected_publication',
+    'fencing_enforced_at', 'safe_exclusive_dispatch',
+  ])
+    || typeof workClaim.supported !== 'boolean'
+    || workClaim.api_version !== 1
+    || workClaim.mode !== 'advisory'
+    || workClaim.claim_protected_publication !== false
+    || workClaim.fencing_enforced_at !== 'none'
+    || workClaim.safe_exclusive_dispatch !== false) {
+    return 'result.operations.work_claim';
+  }
+  return null;
+}
+
+function operationsIssue(operations) {
+  if (!hasExactMembers(operations, ['inspect', 'create', 'transition', 'patch', 'work_claim'])) {
+    return 'result.operations';
+  }
+  return inspectOperationIssue(operations.inspect)
+    || createOperationIssue(operations.create)
+    || transitionOperationIssue(operations.transition)
+    || patchOperationIssue(operations.patch)
+    || workClaimOperationIssue(operations.work_claim);
+}
+
+function durabilityIssue(durability) {
+  if (!hasExactMembers(durability, [
+    'temporary_file_sync', 'directory_sync', 'post_publication_verification', 'power_loss_guarantee',
+  ])
+    || durability.temporary_file_sync !== 'required-before-publication'
+    || durability.directory_sync !== 'best-effort-when-supported'
+    || durability.post_publication_verification !== 'exact-bytes-required'
+    || durability.power_loss_guarantee !== 'none') {
+    return 'result.durability';
+  }
+  return null;
+}
+
+function limitsIssue(limits) {
+  if (!hasExactMembers(limits, [
+    'multi_item_atomicity', 'cross_clone_coordination', 'cross_worktree_coordination',
+    'cross_machine_coordination', 'noncooperating_writer_protection', 'automatic_stale_lock_breaking',
+  ])
+    || limits.multi_item_atomicity !== false
+    || limits.cross_clone_coordination !== false
+    || limits.cross_worktree_coordination !== false
+    || limits.cross_machine_coordination !== false
+    || limits.noncooperating_writer_protection !== false
+    || limits.automatic_stale_lock_breaking !== false) {
+    return 'result.limits';
+  }
+  return null;
+}
+
+function coreProbeSchemaIssue(probe) {
+  if (!hasExactMembers(probe, ['ok', 'command', 'contract_version', 'result'])) {
+    return 'members';
+  }
+  if (probe.ok !== true) {
+    return 'ok';
+  }
+  if (probe.command !== 'capabilities') {
+    return 'command';
+  }
+  if (probe.contract_version !== CORE_CONTRACT_VERSION) {
+    return 'contract_version';
+  }
+  const result = probe.result;
+  if (!hasExactMembers(result, ['backend', 'operations', 'durability', 'limits'])) {
+    return 'result';
+  }
+  return backendIssue(result.backend)
+    || operationsIssue(result.operations)
+    || durabilityIssue(result.durability)
+    || limitsIssue(result.limits);
+}
+
+function sameCommandOrder(commands) {
+  return Array.isArray(commands)
+    && commands.length === CORE_COMMAND_ORDER.length
+    && commands.every((command, index) => command === CORE_COMMAND_ORDER[index]);
+}
+
+// verifyCoreProbe(describe, probe) checks the independently-launched core
+// `capabilities --json` probe against an already-validated describe
+// result (contract section 3): the probe must match the exact version 2
+// envelope, its contract version must match the required core contract
+// version, its command list must match the advertised one, and neither
+// optional feature may be elevated beyond what the probe actually supports.
+export function verifyCoreProbe(describe, probe) {
+  const schemaIssue = coreProbeSchemaIssue(probe);
+  if (schemaIssue) {
+    return refuse('core-protocol-error', { member: schemaIssue });
+  }
+  const required = describe?.core?.required_core_contract_version;
+  if (probe.contract_version !== required) {
+    return refuse('core-contract-version-mismatch', { required, probed: probe.contract_version });
+  }
+  if (!sameCommandOrder(describe.core.commands)) {
+    return refuse('core-contract-version-mismatch', { member: 'core.commands' });
+  }
+  if (describe.optional_features?.claims !== probe.result.operations.work_claim.supported) {
+    return refuse('core-contract-version-mismatch', { member: 'optional_features.claims' });
+  }
+  if (describe.optional_features?.policy !== false) {
+    return refuse('core-contract-version-mismatch', { member: 'optional_features.policy' });
+  }
+  return { ok: true };
+}
+
+// The engine's own core capability snapshot: this repository's core is a
+// same-process, same-working-copy `local-filesystem` backend. Advisory
+// work-claim visibility is independent of this mutation-coordination scope
+// (contract section 3: "optional_features.claims is derived only from
+// operations.work_claim.supported").
+export function coreCapabilities() {
+  return {
+    ok: true,
+    command: 'capabilities',
+    contract_version: CORE_CONTRACT_VERSION,
+    result: {
+      backend: { name: 'local-filesystem', coordination_scope: 'same-working-copy-cooperative-writers' },
+      operations: {
+        inspect: { supported: true, write_scope: 'none', cas_scope: 'none' },
+        create: {
+          supported: true,
+          write_scope: 'single-item',
+          cas_scope: 'requested-id-lock',
+          publication_visibility: 'atomic-no-clobber-or-fail',
+          publication_probe: 'per-ledger-operation',
+        },
+        transition: { supported: true, write_scope: 'single-item', cas_scope: 'exact-byte-sha256' },
+        patch: { supported: true, write_scope: 'single-item', cas_scope: 'exact-byte-sha256' },
+        work_claim: {
+          supported: false,
+          api_version: 1,
+          mode: 'advisory',
+          claim_protected_publication: false,
+          fencing_enforced_at: 'none',
+          safe_exclusive_dispatch: false,
+        },
+      },
+      durability: {
+        temporary_file_sync: 'required-before-publication',
+        directory_sync: 'best-effort-when-supported',
+        post_publication_verification: 'exact-bytes-required',
+        power_loss_guarantee: 'none',
+      },
+      limits: {
+        multi_item_atomicity: false,
+        cross_clone_coordination: false,
+        cross_worktree_coordination: false,
+        cross_machine_coordination: false,
+        noncooperating_writer_protection: false,
+        automatic_stale_lock_breaking: false,
+      },
+    },
+  };
+}