@bradheitmann/odin-sentinel 0.2.1 → 0.4.2

package/protocol/delegation.yaml

@@ -1,4 +1,4 @@
-version: 0.2.1
+version: 0.3.0
 delegation_contract:
   required_fields:
     - receipt_type
@@ -36,3 +36,6 @@ delegation_contract:
     - Delegation must include exact authority and scope.
     - Terminal text left in an input bar is not delivery.
     - QA acceptance cannot be delegated to the same role that implemented the deliverable.
+    - Staffing actions (spawn, rename, kill, reassign, move-surface) are the sole authority of A/EXEC-PM and may not be delegated to TEAM PMs or workers.
+    - Surface custodianship (new-split, new-surface, move-surface, close-surface) is held exclusively by A/EXEC-PM.
+    - TEAM PMs needing more staff must escalate to A/EXEC-PM rather than act.

package/protocol/receipts/boot-receipt.yaml

@@ -21,3 +21,20 @@ recommended_fields:
   - delegates_to
   - prohibited_paths
   - proof_source
+  - staffed_by
+  - parent_surface_ref
+  - column_index
+  - team_letter
+staffing_audit:
+  description: >-
+    For any role outside the executive office (team != "A"), the boot receipt
+    must record who staffed the agent (staffed_by) and which CMUX surface it
+    occupies (parent_surface_ref, column_index, team_letter). Receipts missing
+    these fields on non-exec roles produce ODIN warnings. EXEC PM is the sole
+    canonical staffing authority.
+  required_for_non_exec_team:
+    - staffed_by
+    - parent_surface_ref
+    - column_index
+    - team_letter
+  staffed_by_canonical_value: A/EXEC-PM

package/protocol/roles.yaml

@@ -1,4 +1,4 @@
-version: 0.2.1
+version: 0.3.0
 roles:
   EXEC_PM:
     title: EXEC PM
@@ -6,12 +6,75 @@ roles:
     may_implement_default: false
     may_qa_accept_default: false
     purpose: Intent, priority, authorization, escalation, and claim framing.
+    authority:
+      sole_staffing_authority:
+        active: true
+        scope: >-
+          A/EXEC-PM is the only role that may spawn, name, kill, rename,
+          reassign, or move agents on any team. No TEAM PM may staff its own
+          pod or any other pod. Worker roles never staff.
+      surface_custodianship:
+        sole_custodian: true
+        includes:
+          - cmux new-split
+          - cmux new-surface
+          - cmux move-surface
+          - cmux close-surface
+          - cmux drag-surface-to-split
+      pre_staffing_gate:
+        required: true
+        steps:
+          - call odin.compute_surface_layout for the target team count
+          - call odin.compute_surface_layout_gate to retrieve the transition checklist
+          - execute the required cmux split operations
+          - confirm each new surface is empty and addressable via cmux list-pane-surfaces
+          - dispatch the spawn only after surface confirmation
+        violation_class: protocol_breach_high
+      meta_governance:
+        role_in_org_strategy: org_strategy_dev
+        supervisor: A/EXEC-ODIN
   EXEC_ODIN:
     title: EXEC ODIN
     layer: meta_control
     may_implement_default: false
     may_qa_accept_default: false
     purpose: Governance health, polling, delivery proof, role boundaries, and closeout hygiene.
+    authority:
+      intervention_authority:
+        may_issue_halt: true
+        halt_targets:
+          - A/EXEC-PM
+          - any TEAM PM
+          - any worker on any pod
+          - any ODIN agent
+        halt_triggers:
+          - staffing without the surface layout gate
+          - hidden agent creation
+          - QA acceptance by implementer
+          - context window exceeds hard threshold without compaction or handoff
+          - boot receipt missing required staffing audit fields
+          - team manifest topology drift from default_topology contract
+        receiving_role_obligation: >-
+          The role receiving a HALT directive must stop the offending action
+          and reply with a remediation plan before resuming. Continuing past a
+          HALT without remediation is itself a protocol breach.
+      health_escalation:
+        round_robin_minutes: 10
+        thresholds:
+          missed_heartbeat_warn: 1
+          missed_heartbeat_escalate: 2
+          missed_heartbeat_lockdown: 3
+        lockdown_effect: >-
+          On lockdown, the affected agent is suspended from new dispatch and
+          A/EXEC-PM is required to restaff or close the surface.
+      context_window_budgeting:
+        per_agent_soft_pct: 70
+        per_agent_hard_pct: 90
+        on_soft: warn_and_request_compaction
+        on_hard: force_handoff_or_lockdown
+      mesh_aggregator: A/EXEC-ODIN
+      meta_governance:
+        role_in_org_strategy: org_strategy_qa
   EXEC_ASST:
     title: EXEC ASST
     layer: executive_support
@@ -36,12 +99,54 @@ roles:
     may_implement_default: false
     may_qa_accept_default: false
     purpose: Pod task routing, worker activation, and reporting.
+    forbidden_actions:
+      - spawn agents on own pod or any other pod
+      - rename, kill, or reassign agents on own pod
+      - split, move, or close any surface
+      - accept own pod's QA work
+      - delegate staffing or surface operations to workers
+    constraint_rationale: >-
+      Staffing and surface custodianship are the sole authority of A/EXEC-PM.
+      Any TEAM PM staffing or surface action without an explicit A/EXEC-PM
+      directive is a protocol breach and will be HALTed by the supervising
+      ODIN role.
+    escalation_path:
+      need_more_staff: report to A/EXEC-PM with rationale; do not act
+      surface_misconfigured: report to A/EXEC-PM and own pod's ODIN
   TEAM_ODIN:
     title: TEAM ODIN
     layer: meta_control
     may_implement_default: false
     may_qa_accept_default: false
     purpose: Pod health monitoring, polling, blockers, freezes, and lateral ODIN mesh awareness.
+    authority:
+      intervention_authority:
+        may_issue_halt: true
+        halt_targets:
+          - own pod TEAM PM
+          - own pod workers
+        halt_triggers:
+          - QA acceptance by implementer
+          - context window exceeds hard threshold without compaction
+          - delivery without evidence
+          - hidden subagent creation
+        receiving_role_obligation: >-
+          Same as EXEC_ODIN. Pod role receiving a HALT must stop and remediate
+          before resuming.
+      health_escalation:
+        reports_to: A/EXEC-ODIN via odin_mesh aggregator
+        thresholds:
+          missed_heartbeat_warn: 1
+          missed_heartbeat_escalate: 2
+          missed_heartbeat_lockdown: 3
+      context_window_budgeting:
+        per_agent_soft_pct: 70
+        per_agent_hard_pct: 90
+        on_soft: warn_and_request_compaction
+        on_hard: force_handoff_or_lockdown
+      meta_governance:
+        role_in_org_strategy: org_strategy_qa
+        reports_to: A/EXEC-ODIN
   DEV_WORKER:
     title: DEV WORKER
     layer: implementation

package/protocol/topology.yaml

@@ -1,4 +1,4 @@
-version: 0.2.1
+version: 0.3.0
 default_topology:
   executive_office:
     team: A
@@ -20,3 +20,37 @@ default_topology:
     bootstrap_identity_exchange: true
     health_round_robin_minutes: 10
     aggregator: A/EXEC-ODIN
+surface_layout:
+  description: >-
+    Canonical CMUX surface layout rule for EXEC PM. Teams arrive as letters
+    (Team A is executive; Team B onward are development pods). Columns are
+    equal width. Surfaces stack vertically inside a column with at most two
+    surfaces per column. Team A always occupies column 0. When the team count
+    is odd and at least 3, column 0 holds only Team A (the "tall column").
+  rules:
+    max_surfaces_per_column: 2
+    column_widths: equal
+    exec_team_column: 0
+    tall_column_when_odd_team: A
+  custodianship:
+    sole_custodian: A/EXEC-PM
+    includes:
+      - cmux new-split
+      - cmux new-surface
+      - cmux move-surface
+      - cmux close-surface
+  pre_staffing_gate: >-
+    Before adding any agent beyond A/EXEC, EXEC PM must (1) call
+    odin.compute_surface_layout for teamCount=N+1, (2) execute the splits
+    required to reach that layout via cmux, (3) confirm each new surface
+    is empty and addressable via cmux list-pane-surfaces, and only then
+    (4) dispatch the spawn to the newly created surface.
+  reference_layouts:
+    teams_1: "[A]"
+    teams_2: "[A] [B]"
+    teams_3: "[A] [B/C]"
+    teams_4: "[A/D] [B/C]"
+    teams_5: "[A] [B/C] [D/E]"
+    teams_6: "[A/F] [B/C] [D/E]"
+    teams_7: "[A] [B/C] [D/E] [F/G]"
+    teams_8: "[A/H] [B/C] [D/E] [F/G]"

package/scripts/audit/public-surface.mjs

@@ -33,12 +33,20 @@ function filesToAudit() {
 
 const publicFiles = filesToAudit();
 
+// Per-rule file exemptions. The bundled bootstrap protocol document is
+// user-authored content that legitimately references multiple agent harness
+// config dirs (the dot-prefixed home subdirs of codex, claude, and friends)
+// and uses tilde home paths in its install instructions.
+const BUNDLED_DOC = new Set([
+  "protocol/bootstrap-" + "sk" + "ill.md",
+  "plugins/sentinel-coordination-protocol/" + "sk" + "ills/sentinel-coordination-protocol/SK" + "ILL.md"
+]);
+
 const forbidden = [
   { name: "macOS home path", pattern: new RegExp(`/${"Users"}/[A-Za-z0-9._-]+/`) },
   { name: "Linux home path", pattern: /\/home\/[A-Za-z0-9._-]+\// },
-  { name: "tilde home path", pattern: /~\// },
-  { name: "local agent config path", pattern: new RegExp(`\\.${"codex"}|\\.${"claude"}|\\.${"agents"}`, "i") },
-  { name: "legacy extension terminology", pattern: new RegExp(`\\b${"sk" + "ill"}\\b|${"SK" + "ILL"}\\.md|export_${"sk" + "ill"}_snapshot`, "i") },
+  { name: "tilde home path", pattern: /~\//, exemptFiles: BUNDLED_DOC },
+  { name: "local agent config path", pattern: new RegExp(`\\.${"codex"}|\\.${"claude"}|\\.${"agents"}`, "i"), exemptFiles: BUNDLED_DOC },
   {
     name: "private project or account marker",
     pattern: new RegExp(
@@ -54,6 +62,7 @@ const findings = [];
 for (const file of publicFiles) {
   const text = readFileSync(file, "utf8");
   for (const rule of forbidden) {
+    if (rule.exemptFiles?.has(file)) continue;
     if (rule.pattern.test(text)) {
       findings.push(`${file}: ${rule.name}`);
     }

package/scripts/audit/verify-pack.mjs

@@ -25,7 +25,8 @@ const requiredProtocolFiles = [
   "protocol/closeout.yaml",
   "protocol/delegation.yaml",
   "protocol/receipts/boot-receipt.yaml",
-  "protocol/receipts/team-manifest.yaml"
+  "protocol/receipts/team-manifest.yaml",
+  "protocol/bootstrap-skill.md"
 ];
 
 const requiredFiles = [