diff --git a/canon/standards/autonomy-lanes_v0.1.md b/canon/standards/autonomy-lanes_v0.1.md new file mode 100644 index 0000000..c594953 --- /dev/null +++ b/canon/standards/autonomy-lanes_v0.1.md @@ -0,0 +1,98 @@ +--- +id: canon-autonomy-lanes +type: standard +title: "Autonomy Lanes (Fleet) v0.1" +domain: custodian +status: draft +version: "0.1" +created: "2026-07-20" +updated: "2026-07-20" +scope: fleet +related_workplans: + - CUST-WP-0060 +supersedes: none +origin: binky-control/AutonomyPolicy.md (ratified for Binky 2026-07-16, DEC-2026-001) +--- + +# Autonomy Lanes (Fleet) v0.1 + +> Draft pending founder ratification (CUST-WP-0060-T01). Promotes the +> binky-control AutonomyPolicy lane model to fleet canon, unchanged in +> substance. binky-control's `AutonomyPolicy.md` remains the company-level +> policy instance; this standard makes the lane vocabulary and enforcement +> rules fleet-wide. + +## The rule + +> If the responsible human is unavailable, the system must either continue +> safely, prepare the next decision, or explicitly defer with evidence. It +> must not silently idle. + +Valid states: `proceeding` | `prepared for review` | `deferred by policy`. +Invalid state: `waiting because unsure`. Uncertainty triggers research, +comparison, preparation, or risk classification — not paralysis. +"Ask the human" is never the default. + +## Lanes + +| Lane | Name | Agent may | Human involvement | +| --- | --- | --- | --- | +| **green** | Safe autonomous | research, summarize, classify, draft, organize, test, prepare | none (human-on-the-loop via logs) | +| **blue** | Reversible execution | internal docs, backlog updates, local scripts, reports, local commits | none, but logged | +| **yellow** | Deferred approval | prepare external emails, invoices, offers, releases, payments | async approval via decision records | +| **orange** | Time-window approval | customer/legal/accounting/banking actions needing business hours | engagement records, batched into command days | +| **red** | Human-only | signing, strategic commitments, bank/credential changes, sensitive legal/HR/security | always; agents prepare packages only | + +Optimization target: **maximize green+blue throughput, queue yellow, batch +orange, protect red from automation.** Risk-tiered gating (in-the-loop for +irreversible actions, on-the-loop for recoverable ones) is the only +oversight pattern that scales. + +## Lane as a spine field + +`lane` is a **mandatory field on every work record** (see +`work-record-types_v0.1.md`) and on every agent instance manifest. The +chain is closed end-to-end: + +``` +work record.lane → view routing (autopilot / decision / engagement) + → harness tool profile (enforced allow-list) + → ops-warden credential lane (catalog access) +``` + +Declaring a lane an item does not hold is a policy violation the harness +must catch (tool profile refuses the run). + +## Approval packages (yellow and above) + +An agent hitting a lane boundary prepares a complete decision package, +never a bare question: recommended action, reason, evidence links, risk +level, reversibility, deadline (`needed_by`), attention cost, fallback if +no response, options. + +## Human attention is a WIP-limited workstation + +The responsible human's capacity is modeled like any lane capacity: +attention budget (minutes/day, max decisions/day, max deep topics/day) and +availability as first-class state (`available | evening_window | +unavailable | office_hour_day`), with an explicit escalation allow-list +when unavailable (critical security incident, payment failure, legal +deadline). Yellow routes to the decision view, orange to the engagement +view, both subject to that capacity. + +**Time-boxing is hub-owned:** `needed_by` / `fallback_if_no_response` +windows are watched by the hub → NATS → activity-core; a lapsed window +raises the escalation or executes the declared fallback — never a human +re-reading a file. + +## Raising autonomy + +Autonomy per area is raised only after the system proves reliable there, +by explicit human decision recorded as a decision work record. Lane +assignments are auditable history; lowering a lane needs no approval. + +## References + +- `binky-control/AutonomyPolicy.md` (origin instance) +- `canon/standards/work-record-types_v0.1.md` +- `research/2026-07-19-work-orchestration-best-practices.md` §2 diff --git a/canon/standards/work-record-types.yaml b/canon/standards/work-record-types.yaml new file mode 100644 index 0000000..982f95e --- /dev/null +++ b/canon/standards/work-record-types.yaml @@ -0,0 +1,57 @@ +# Machine copy of canon/standards/work-record-types_v0.1.md (kind registry). +# CI and fix-consistency validate id patterns against this file. +# New kinds/prefixes land here by canon PR only. +version: "0.1" +status: draft +kinds: + - kind: workplan + id_patterns: + - "^[A-Z]+-WP-[0-9]{4}$" + lifecycle: [proposed, ready, active, blocked, backlog, finished, archived] + - kind: task + id_patterns: + - "^[A-Z]+-WP-[0-9]{4}-T[0-9]{2,3}$" + - "^ADHOC-[0-9]{4}-[0-9]{2}-[0-9]{2}-T[0-9]{2}$" + lifecycle: [wait, todo, progress, done, cancel] + - kind: intake + id_patterns: + - "^[A-Z]+-IN-[0-9]{4}$" + lifecycle: [open, vetted, routed, closed] + closed_outcomes: [promoted, declined, absorbed] + legacy_patterns: + - pattern: "^AWQ-[0-9]{3}$" + source: binky-control AutopilotWorkQueue + grandfathered: true + - kind: decision + id_patterns: + - "^[A-Z]+-DEC-[0-9]{4}-[0-9]{3}$" + lifecycle: [prepared, resolved] + resolved_outcomes: [approved, rejected, revised, deferred] + legacy_patterns: + - pattern: "^DEC-[0-9]{4}-[0-9]{3}$" + source: binky-control DecisionQueue + grandfathered: true + - kind: engagement + id_patterns: + - "^[A-Z]+-ENG-[0-9]{4}-[0-9]{3}$" + lifecycle: [queued, prepared, done] + legacy_patterns: + - pattern: "^OH-[0-9]{4}-[0-9]{3}$" + source: binky-control OfficeHourQueue + grandfathered: true + - kind: register-entry + id_patterns: + - "^RISK-[0-9]{3}$" + - "^TD-[0-9]+$" + - "^CAP-[0-9]+$" + - "^CCR-[0-9]{4}-[0-9]{4}$" + - "^ADR-[0-9]{3}$" + lifecycle: per-register-convention +spine_fields: + required: [id, kind, lane, status, owner, repo] + hub_assigned: [uuid] + optional: [tags, created, updated] +lanes: [green, blue, yellow, orange, red] +tags: + derived: [stalled, stale, overdue-decision, budget-breached, orphaned] + policy: [automatable, needs-human, unclear-implementation, red-adjacent, compliance-relevant] diff --git a/canon/standards/work-record-types_v0.1.md b/canon/standards/work-record-types_v0.1.md new file mode 100644 index 0000000..ab2f546 --- /dev/null +++ b/canon/standards/work-record-types_v0.1.md @@ -0,0 +1,169 @@ +--- +id: canon-work-record-types +type: standard +title: "Work Record Types & Identity (Fleet) v0.1" +domain: custodian +status: draft +version: "0.1" +created: "2026-07-20" +updated: "2026-07-20" +scope: fleet +related_workplans: + - CUST-WP-0060 +supersedes: none +machine_copy: canon/standards/work-record-types.yaml +--- + +# Work Record Types & Identity (Fleet) v0.1 + +> Draft pending founder ratification (CUST-WP-0060-T01). Source: +> `research/WorkOrchestrationArchitectureDraft.md` v0.2 (founder-reviewed +> 2026-07-20). Extends — does not replace — +> `workplan-terminology-fleet_v0.1.md` and ADR-001/ADR-005. + +## Purpose + +Define **work record** as the umbrella term for every identified, +lifecycle-bearing coordination artefact in the fleet; register the closed +list of work-record **kinds**, their id schemes and abstract lifecycles; +and fix the two-layer identity rule. This is the backbone convention for +all work — planning, development, testing, operations, security & +compliance, controlling, billing, marketing, sales — under one conceptual +framework (different demands are met by flow profiles and kind-specific +fields, never by parallel ontologies). + +## Core definition + +A **work record** is any identified, lifecycle-bearing coordination +artefact. A **task** is one *kind* of work record — the smallest executable +unit. Every work record, regardless of kind, carries the **conventional +spine**: + +| Field | Convention | +| --- | --- | +| `id` | canonical name per the type registry below | +| `uuid` | UUIDv7, hub-assigned at first index, written back to the source file | +| `kind` | one of the registered kinds | +| `lane` | autonomy lane (`autonomy-lanes_v0.1.md`) | +| `status` | abstract lifecycle of the kind (below) | +| `owner` | agent identity (`agt-…`) or human | +| `repo` | owning repo (ADR-001/ADR-005 anchor) | +| `tags` | policy + derived tags (§ Tags) | +| `created` / `updated` | dates (UUIDv7 supplies fine-grained internal time) | + +Kind-specific fields (budget, evidence, counterparty, deadline_pressure, +attention_cost, …) extend the spine; they never replace it. + +## Kind registry (closed list) + +| Kind | Id scheme | Meaning | Absorbs / legacy | +| --- | --- | --- | --- | +| `workplan` | `{PREFIX}-WP-NNNN` | structured, dependency-bearing body of work | — | +| `task` | `{WP-ID}-TNN` (workplan) · `ADHOC-YYYY-MM-DD-TNN` | smallest executable unit | issue-core issues become external projections only | +| `intake` | `{PREFIX}-IN-NNNN` | spark: idea, finding, directive, request | hub suggestions (legacy, read-only close-out); `AWQ-NNN` (grandfathered) | +| `decision` | `{PREFIX}-DEC-YYYY-NNN` | approval package + resolution | `DEC-YYYY-NNN` (binky, grandfathered as-is) | +| `engagement` | `{PREFIX}-ENG-YYYY-NNN` | scheduled external interaction (counterparty, prepared material, time window) | `OH-YYYY-NNN` (grandfathered) | +| `register-entry` | existing schemes: `RISK-NNN`, `TD-…`, `CAP-…`, `CCR-YYYY-NNNN`, `ADR-NNN` | risks, technical debt, capability requests, credential change requests, architecture decisions | unchanged semantics, brought under the spine | + +Rules: + +1. **The registry is closed.** An id pattern not registered in + `work-record-types.yaml` fails CI and `fix-consistency` (the *sidetrack + detector*). New kinds/prefixes are added by canon PR — deliberately + cheap (one YAML entry + one schema) so the legitimate path is easier + than any workaround. +2. **Grandfathering:** existing ids are never renamed. Legacy prefixes map + to kinds in the registry; retirement of a *scheme* (never of records) + follows the legacy-meter discipline of + `workplan-terminology-fleet_v0.1.md`. + +## Identity layering + +- **UUIDv7 is primary** for bookkeeping, relations, dependencies, and + history. It is stable across renames, migrations, and terminology + transitions. +- **Canonical names are primary for humans and agents** — UI, CLI, API + output, prose, commits. UUIDs stay inspectable on demand but are never + required reading. +- The hub writes the UUID back into the source file at first index + (pattern: today's `state_hub_*_id` fields). + +## Abstract lifecycles (canon-fixed, minimal) + +| Kind | Lifecycle | +| --- | --- | +| task | `wait → todo → progress → done \| cancel` (InfoTechCanon) | +| workplan | `proposed → ready → active → blocked → backlog → finished → archived` | +| intake | `open → vetted → routed → closed(promoted \| declined \| absorbed)` | +| decision | `prepared → resolved(approved \| rejected \| revised \| deferred)` | +| engagement | `queued → prepared → done` | +| register-entry | per existing register conventions (unchanged) | + +**Promotion is a first-class transition:** `intake.routed → +workplan | task | decision | engagement`, executed by one CLI/MCP call that +writes both artefacts, sets `promoted_to` / `origin` back-links, and +re-syncs. Manual transcription of an intake item into other kinds is a +process defect. + +**Kind-specific rigor lives in flow profiles**, not extra states: named +task-flow-engine workstation definitions whose entry/exit assertions encode +per-work-kind gates (e.g. compliance tasks cannot exit `progress` without +an evidence link). Profiles are YAML in repos, in the same reconciliation +loop. + +## Source files, index, and views + +1. **Any repo file is a potential source of work records.** Records are + authored as schema-valid YAML blocks in context — thematic live + documents, meeting notes, design docs, triage logs. The schema is the + contract, not the location. Workplans keep dedicated files. +2. **A generated per-repo work-record index** references every registered + record in its source location (transclusion-style; markitect-family + tooling). It is the "everything across all files" orientation view and a + concurrency cross-check. +3. **Every working list is a generated view** (`[auto]`-marked) over + indexed records — autopilot views, decision queues, engagement batches, + briefs. Hand-maintained completed-logs and queue tails are retired. +4. Ordering of views is **lane + priority + age** by default; dependency + capture optional; WSJF optional and situational (overload triage only). + +## Tags + +Two classes, both in `tags`, never in `status`: + +- **Derived tags** — computed, read-only in files: `stalled`, `stale`, + `overdue-decision`, `budget-breached`, `orphaned`. +- **Policy tags** — assigned under tagging policies: `automatable`, + `needs-human`, `unclear-implementation`, `red-adjacent`, + `compliance-relevant`. + +States migrate badly; tags migrate trivially. Anything situational is a tag. + +## Budgets + +Guardrail envelopes resolve programmatically at run start: +workplan-frontmatter override → per-repo `budgets.yaml` (lane/default +envelopes) → **global best-guess default**. Nothing runs unbounded. Budget +resolution and enforcement is automation infrastructure, never agentic +effort; metering via token events; breach ⇒ `budget-breached` + escalation. + +## Reconciliation loop (normative) + +``` +author (any repo file) → CI schema validation → commit + → fix-consistency: register/sync, UUID write-back + → hub read model → generated index + views → NATS events → activity-core +``` + +The hub remains a read model per ADR-001; runtime operations data (logs, +metrics, run histories, token events) is the sanctioned DB-only exception. + +## References + +- `research/WorkOrchestrationArchitectureDraft.md` (v0.2) +- `research/2026-07-19-work-orchestration-infrastructure-survey.md` +- `research/2026-07-19-work-orchestration-best-practices.md` +- `canon/architecture/adr-001-workplans-as-repo-artefacts.md`, `adr-005-…` +- `canon/standards/workplan-terminology-fleet_v0.1.md` +- `canon/standards/autonomy-lanes_v0.1.md` +- `state-hub/docs/task-flow-engine-spec.md` diff --git a/workplans/CUST-WP-0060-work-record-canonization.md b/workplans/CUST-WP-0060-work-record-canonization.md new file mode 100644 index 0000000..b78fe0d --- /dev/null +++ b/workplans/CUST-WP-0060-work-record-canonization.md @@ -0,0 +1,137 @@ +--- +id: CUST-WP-0060 +type: workplan +title: "Work-record canonization — unified ontology, stages 1–2" +domain: infotech +status: ready +owner: codex +topic_slug: custodian +planning_priority: high +planning_order: 60 +created: "2026-07-20" +updated: "2026-07-20" +state_hub_workstream_id: "4555741c-7c54-4262-859f-7815b34cc647" +--- + +# Work-record canonization — unified ontology, stages 1–2 + +Execute stages 1 (canonize) and 2 (schema + CI) of +`research/WorkOrchestrationArchitectureDraft.md` v0.2 (founder-reviewed +2026-07-20): ratify the work-record umbrella ontology as canon and make it +machine-enforced, with **binky-control as pilot** — its AWQ/DEC/OH queue +items become schema-valid, hub-indexed work records without renaming a +single id. Stages 3–6 (hub intake entity, generated views/index, tags & +flow metrics, legacy retirement) follow in successor workplans once this +foundation holds. + +Origin: AWQ-010 sidetrack reintegration (2026-07-19); every artefact this +plan lands exists to make that class of manual reintegration structurally +unnecessary. + +## Task: Founder ratification of the two canon standards + +Present `work-record-types_v0.1.md` (+ `work-record-types.yaml`) and +`autonomy-lanes_v0.1.md` for founder review; apply edits; flip both from +`status: draft` to `status: active`. Ratification is a decision work record +(hub decision, red lane — canon change per constitution review gate). +Yellow lane (preparation); resolution founder-only. + +```task +id: CUST-WP-0060-T01 +status: todo +priority: high +state_hub_task_id: "90de8017-436e-4251-ae64-904a6f617623" +``` + +## Task: Extend workplan-terminology standard, don't fork it + +Add the work-record umbrella and kind vocabulary to +`workplan-terminology-fleet_v0.1.md` as a v0.2 revision (workplan and task +definitions unchanged; new terms cross-referenced to +`work-record-types_v0.1.md`). Update the terminology scan tooling exclusion +list if needed. Green lane. + +```task +id: CUST-WP-0060-T02 +status: todo +priority: medium +state_hub_task_id: "772a1777-d90f-4d13-9966-50344287db10" +``` + +## Task: YAML block schemas per kind + +Author JSON-Schema definitions for the authored YAML block of each kind +(intake, decision, engagement; task/workplan blocks already parsed by +state-hub — align, don't duplicate). Schemas live in +`canon/standards/schemas/work-records/` with the machine registry as the +pattern source. Include the spine-field requirements and grandfathered +legacy patterns (AWQ-/DEC-/OH-). Green lane. + +```task +id: CUST-WP-0060-T03 +status: todo +priority: high +state_hub_task_id: "c394bde6-dc8b-4ce6-97b8-a73b3cab300a" +``` + +## Task: Forgejo CI validation action + +A reusable Forgejo workflow (`repo-seed` + rollout to control-plane repos) +that validates all work-record YAML blocks in changed files against the +schemas and the id-pattern registry on push/PR — the GitOps +"validate before apply" gate and the first half of the sidetrack detector. +Must be fast (<5 s), zero-config when the repo has no records. Blue lane. + +```task +id: CUST-WP-0060-T04 +status: todo +priority: high +state_hub_task_id: "b5f03759-c285-4b83-9037-fdf0ac669274" +``` + +## Task: fix-consistency sidetrack detector (C-25) + +Extend `statehub fix-consistency` with a check that scans registered repos +for id-like patterns (`[A-Z]+-[A-Z]+-[0-9]+` heuristic) **not** matching the +type registry and warns with the reintegration-cost message. No +registration yet (that is stage 3) — detection only, so new species surface +the day they appear. Green/Blue lane, lands in state-hub per its +governance. + +```task +id: CUST-WP-0060-T05 +status: todo +priority: medium +state_hub_task_id: "43bcef67-c3e9-48e2-8de0-5cbd2f85c175" +``` + +## Task: binky-control pilot — queues schema-valid + +Bring binky-control's live documents (AutopilotWorkQueue, DecisionQueue, +OfficeHourQueue, RiskRegister) to schema validity: add missing spine fields +(`kind`, `lane`, `owner` where absent) to open items, wire the CI action, +run fix-consistency clean with the new checks. **No id renames, no format +migration** — grandfathered patterns must pass as-is; that is the +acceptance test for the grandfathering design. Blue lane (binky-control +commits). + +```task +id: CUST-WP-0060-T06 +status: todo +priority: high +state_hub_task_id: "7edac718-b659-4708-9868-b6c44364a928" +``` + +## Task: Closure — stage-3 handoff package + +Closure review per ADR-001; write the stage-3 successor workplan seed +(state-hub intake entity, promotion transition CLI/MCP, generated per-repo +index) with evidence from the pilot: schema friction observed, CI runtimes, +detector findings across the fleet. Green lane. + +```task +id: CUST-WP-0060-T07 +status: todo +priority: medium +state_hub_task_id: "e27e7d69-c51d-48c0-8a82-57a198e0a668" +```