From a09ad2e4aef6682da780291cee86aa30a092aad2 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 21 Aug 2026 00:21:53 +0200 Subject: [PATCH] docs: define agent workforce execution boundary --- SCOPE.md | 180 +++++++++++++++++++++++++++++++--- WORK-RECORDS.md | 71 ++++++++++++++ workplans/ADHOC-2026-08-20.md | 72 ++++++++++++++ 3 files changed, 310 insertions(+), 13 deletions(-) create mode 100644 WORK-RECORDS.md create mode 100644 workplans/ADHOC-2026-08-20.md diff --git a/SCOPE.md b/SCOPE.md index ba633e7..297686a 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,32 +1,186 @@ # SCOPE -> This file was generated by `statehub register`. Refine it as the repository -> boundaries become clearer. +> Reviewed 2026-08-20 against the implemented Helix Forge loop and the +> cross-repository leadership/workforce architecture discussion. For the +> stable purpose and desired organizational outcome, see `INTENT.md`. ## One-liner -Iterating towards optimal agentic performance. +Agent-workforce performance and lifecycle management: learn from agent +execution, improve the fleet, and—once the proposed contracts are +implemented—plan and govern which agents fill which roles within +leadership-owned goals and delegated resource envelopes. ## Core Idea -agentic-resources exists to provide the capability described in INTENT.md. +`agentic-resources` treats AI agents as a managed digital workforce rather +than as isolated prompts or interchangeable runtime processes. -## In Scope +Its implemented Helix Forge subsystem captures coding sessions, finds +repeated friction and successful techniques, curates and distributes reviewed +solution patterns, measures their effectiveness, and produces fleet +retrospectives. This is already the performance-and-development loop described +by `INTENT.md`. -- Maintain the repository's primary implementation. -- Keep docs, tests, and operational metadata current. +The recommended next boundary extends that evidence base into agent inventory, +selection, assignment, capacity planning, development, portfolio review, +rebalancing, and retirement. This repository may translate authorized goals +and constraints into a workforce plan, but it does not create organizational +strategy, leadership authority, money, technical capacity, or execution +permissions. + +## Current Implemented Scope + +- Capture and normalize Claude, Codex, and Grok coding sessions. +- Retain session digests and raw evidence within explicit storage budgets. +- Detect recurring failure, friction, cost, and success signals across the + fleet. +- Curate evidence-backed solution patterns through a review and approval flow. +- Render approved patterns as agent-flavor-specific, reviewable distribution + proposals. +- Measure before/after pattern effectiveness and fleet trends. +- Publish weekly retrospectives and correlate fleet-level Helix Forge evidence + with project-level KaizenAgentic metrics by reference. + +## Recommended Workforce-Management Boundary + +The following concerns fit the intent and existing performance subsystem, but +their contracts and implementation do not yet exist in this repository: + +- Maintain an inventory of available agent capabilities, instances, status, + lifecycle stage, and evidence of fitness. +- Own the `RoleAssignment` control contract: which agent instance fills which + part of a role for which goals, under which leadership mandate and resource + envelope. +- Express execution needs through a versioned `glas-harness` profile reference + or compatible requirements contract, rather than coupling assignments to one + concrete rein or base model. +- Match agents, role duties, and Kaizen blueprints using explicit suitability + evidence; record unstaffed or deliberately human-owned duties. +- Allocate concurrent agent and duty capacity within authoritative financial, + technical-resource, token, time, and human-attention constraints. +- Aggregate outcomes, costs, refusals, and escalation quality by goal, role, + assignment, and duty. +- Maintain performance and development plans and recommend continue, coach, + refine, reallocate, pause, or retire decisions. +- Run portfolio reviews and propose rebalancing while requiring the authorized + leadership source to approve goal reprioritization, material envelope + changes, or wider authority. + +Consumer-owned assignment/instance manifests should remain the durable source +initially; this repository can validate, index, plan, and review them without +prematurely requiring a central workforce service. + +## Leadership and Workforce Relationship + +Leadership and workforce management are adjacent control layers, not synonyms: + +```text +organization intent + -> leadership-owned StrategicGoal + LeadershipMandate + -> delegated ResourceEnvelope + -> agentic-resources workforce plan + RoleAssignment + -> Kaizen blueprint + consumer-owned AgentInstance + -> activity-core scheduled work + -> glas-harness profile resolution + -> selected rein + base-model + sandbox constellation + -> outcome, cost, evidence, refusal, escalation + -> leadership review + workforce rebalance + blueprint improvement +``` + +- A `StrategicGoal` states the desired outcome, priority, horizon, and success + measures. Its authoritative source is the accountable organization or + engagement control plane. +- A `LeadershipMandate` states who may decompose goals, direct work, make which + decisions, delegate, pause, and escalate. A role title or agent prompt never + creates this authority. +- A `ResourceEnvelope` composes provenance-bearing limits from leadership, + `fin-hub`, `resource-control`, and runtime policy. Unknown capacity or budget + is never treated as unlimited. +- A `RoleAssignment` is the workforce decision within those inputs. It binds a + specific agent instance to selected role duties and records evidence, + limits, lifecycle, and review state. + +Agentic-resources therefore advises and administers the agent workforce; +leadership remains accountable for direction, priority, material commitments, +and expansion of authority. + +## Ecosystem Boundaries + +| Concern | Owning source | Relationship to agentic-resources | +|---|---|---| +| Organizational intent, goals, priorities, and leadership mandates | Contextual organization/engagement control source; for example `binky-control` for Binky Hedgehog GmbH | Consume stable references; return portfolio evidence and recommendations; never invent or silently reprioritize strategy | +| Organizational role definitions | `role-engine` | Consume pinned role revisions and duty/authority boundaries; do not redefine roles or grant permissions | +| Agent blueprints, protocols, and project metrics | `kaizen-agentic` | Consume versioned blueprints and run evidence; supply assignment and performance context | +| Agent workforce inventory, assignment, capacity, development, and portfolio review | `agentic-resources` (recommended boundary; not yet implemented beyond performance learning) | Own the workforce plan and assignment lifecycle | +| Human workforce lifecycle and mixed-team concerns | `human-resources` | Share compatible vocabulary and handoff contracts; keep human-sensitive, employment, welfare, and compensation records separate | +| Monetary budgets, commitments, burn, runway, and AI-plan booked cost | `fin-hub` | Consume authoritative constraint signals and publish attribution; do not copy the financial ledger or approve spending | +| Resource identity, demand, capacity, utilization, allocation evidence, and technical economics | `resource-control` | Consume planning/evidence signals; do not procure, operate, or invent capacity | +| Scheduling and durable claimable work | `activity-core` | Supply active assignment/duty context; do not own the clock, queue, retry, or task lifecycle | +| Harness contract, execution profiles, backend routing, sandbox coordination, and gateway evidence | `glas-harness` | Supply an approved, versioned profile or execution requirements; let Glas resolve the concrete rein and sandbox constellation; consume its unified result evidence | +| Concrete inner agentic loop and backend-specific credentials/policy | Selected rein under `glas-harness`; currently including `rein-aharness` and `rein-openweights` | Treat a rein as a replaceable execution backend, not the workforce architecture boundary; `rein-aharness` is the live Claude-Code-CLI rein, not the meta-framework | +| Identity, credentials, and authorization | Identity, OpenBao/credential-routing, and policy systems | Reference routes and policy profiles only; never store secrets or treat organizational wording as technical access | +| Base-model/provider execution and inference routing | `llm-connect`, the selected rein, and provider adapters under their declared boundaries | Select through the approved Glas execution profile/route; consume usage/outcome evidence; do not hard-code a vendor model into workforce records or become a model gateway | +| Durable coordination read model | Custodian State Hub | Publish/index work and evidence; do not replace source files or hub ownership | ## Out of Scope -- Own unrelated adjacent systems. -- Make irreversible operational decisions without human approval. +- Setting organizational strategy, goals, or cross-goal priorities. +- Granting leadership mandates, technical authorization, credentials, or tool + permissions. +- Owning human personnel records, hiring, compensation, employment decisions, + welfare, or human performance surveillance. +- Owning the canonical role catalog or treating a role definition as a live + assignment. +- Owning monetary budget truth, payment/commitment approval, procurement, + infrastructure inventory, or provider capacity. +- Owning schedules, queues, workflow/task lifecycle, LLM sessions, or runtime + policy enforcement. +- Selecting a concrete rein or base model outside the approved + `glas-harness` profile/route, or treating `rein-aharness` as the universal + execution architecture. +- Automatically applying self-modifications or retiring live agents without + the review and authority required by the relevant mandate. +- Replacing KaizenAgentic, role-engine, activity-core, `glas-harness`, its + concrete reins, State Hub, fin-hub, or resource-control with a monolithic + agent-management service. + +## Intent Relationship + +`INTENT.md` describes the desired organizational outcome: a trustworthy, +antifragile agent ecosystem that improves performance and augments human +ingenuity through lifecycle management, oversight, and continuous alignment. +It is deliberately broader than this repository's implementation ownership. + +This scope realizes that intent through a federated operating model. The repo +owns the agent-workforce performance and lifecycle concern while consuming +strategy, role, budget, resource, policy, runtime, and human-workforce facts +from their authoritative systems. ## Current State -- Status: active; implementation and stability should be verified by the repo agent. +- **Implemented:** the Helix Forge capture -> detect -> curate -> distribute -> + measure loop, weekly retrospectives, and Kaizen metrics correlation. +- **Completed work:** `AGENTIC-WP-0001` through `AGENTIC-WP-0011`; there are no + active normal workplans at the time of this review. +- **Architecture proposal:** accept agentic-resources as the workforce and + assignment owner, subject to cross-repository ratification. +- **Execution-layer implementation:** `GLAS-WP-0004` now provides strict + versioned requests/profiles, deterministic rein-registry validation, + explicit CLI/gateway selection, and one normalized evidence envelope. + `rein-aharness` is one current backend; workforce contracts preserve freedom + to choose a different rein, sandbox, tool policy, and base-model + constellation by changing the approved Glas profile reference. The + Claude-backed and open-weight profiles both have live success, real-commit, + and sandbox-cleanup evidence through the same Glas contract. +- **Implementation gap:** agent inventory, `RoleAssignment`, capacity + allocation, goal/resource-envelope correlation, development plans, and + portfolio/retirement workflows are not implemented yet. ## Getting Oriented -- Start with: INTENT.md -- Agent instructions: AGENTS.md -- Workplans: workplans/ +1. `INTENT.md` — stable organizational purpose. +2. `docs/PRD-helix-forge.md` — implemented product boundary and architecture. +3. `session_memory/README.md` — current operational capabilities. +4. `docs/DESIGN-session-memory.md` — detailed design and Kaizen correlation. +5. `workplans/` — implementation history and future work. diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md new file mode 100644 index 0000000..acb6a2c --- /dev/null +++ b/WORK-RECORDS.md @@ -0,0 +1,71 @@ +# Work Records — agentic-resources + +> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record +> stage 3). Do not edit by hand — edit the source file/block listed for +> each record and re-run fix-consistency to refresh this index. Archived +> workplans are omitted; closed decisions/intakes/engagements stay listed +> so recently-resolved work is still visible. [auto] + +| Kind | ID | Status | Lane | Source | +| --- | --- | --- | --- | --- | +| workplan | ADHOC-2026-08-20 | finished | — | workplans/ADHOC-2026-08-20.md | +| workplan | AGENTIC-WP-0001 | finished | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md | +| workplan | AGENTIC-WP-0002 | finished | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| workplan | AGENTIC-WP-0003 | finished | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| workplan | AGENTIC-WP-0004 | finished | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| workplan | AGENTIC-WP-0005 | finished | — | workplans/AGENTIC-WP-0005-detect-hardening.md | +| workplan | AGENTIC-WP-0006 | finished | — | workplans/AGENTIC-WP-0006-error-body-mining.md | +| workplan | AGENTIC-WP-0007 | finished | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md | +| workplan | AGENTIC-WP-0008 | finished | — | workplans/AGENTIC-WP-0008-read-before-edit-reflex.md | +| workplan | AGENTIC-WP-0009 | finished | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md | +| workplan | AGENTIC-WP-0010 | finished | — | workplans/AGENTIC-WP-0010-weekly-retro.md | +| workplan | AGENTIC-WP-0011 | finished | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md | +| task | ADHOC-2026-08-20-T01 | done | — | workplans/ADHOC-2026-08-20.md | +| task | ADHOC-2026-08-20-T02 | done | — | workplans/ADHOC-2026-08-20.md | +| task | AGENTIC-WP-0001-T01 | done | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md | +| task | AGENTIC-WP-0001-T02 | done | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md | +| task | AGENTIC-WP-0001-T03 | done | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md | +| task | AGENTIC-WP-0002-T01 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| task | AGENTIC-WP-0002-T02 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| task | AGENTIC-WP-0002-T03 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| task | AGENTIC-WP-0002-T04 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| task | AGENTIC-WP-0002-T05 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| task | AGENTIC-WP-0002-T06 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| task | AGENTIC-WP-0002-T07 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md | +| task | AGENTIC-WP-0003-T01 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0003-T02 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0003-T03 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0003-T04 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0003-T05 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0003-T06 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0003-T07 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0003-T08 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md | +| task | AGENTIC-WP-0004-T01 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| task | AGENTIC-WP-0004-T02 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| task | AGENTIC-WP-0004-T03 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| task | AGENTIC-WP-0004-T04 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| task | AGENTIC-WP-0004-T05 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| task | AGENTIC-WP-0004-T06 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| task | AGENTIC-WP-0004-T07 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md | +| task | AGENTIC-WP-0005-T01 | done | — | workplans/AGENTIC-WP-0005-detect-hardening.md | +| task | AGENTIC-WP-0005-T02 | done | — | workplans/AGENTIC-WP-0005-detect-hardening.md | +| task | AGENTIC-WP-0005-T03 | done | — | workplans/AGENTIC-WP-0005-detect-hardening.md | +| task | AGENTIC-WP-0006-T01 | done | — | workplans/AGENTIC-WP-0006-error-body-mining.md | +| task | AGENTIC-WP-0006-T02 | done | — | workplans/AGENTIC-WP-0006-error-body-mining.md | +| task | AGENTIC-WP-0006-T03 | done | — | workplans/AGENTIC-WP-0006-error-body-mining.md | +| task | AGENTIC-WP-0007-T01 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md | +| task | AGENTIC-WP-0007-T02 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md | +| task | AGENTIC-WP-0007-T03 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md | +| task | AGENTIC-WP-0007-T04 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md | +| task | AGENTIC-WP-0007-T05 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md | +| task | AGENTIC-WP-0008-T01 | done | — | workplans/AGENTIC-WP-0008-read-before-edit-reflex.md | +| task | AGENTIC-WP-0008-T02 | done | — | workplans/AGENTIC-WP-0008-read-before-edit-reflex.md | +| task | AGENTIC-WP-0009-T01 | done | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md | +| task | AGENTIC-WP-0009-T02 | done | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md | +| task | AGENTIC-WP-0009-T03 | done | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md | +| task | AGENTIC-WP-0010-T01 | done | — | workplans/AGENTIC-WP-0010-weekly-retro.md | +| task | AGENTIC-WP-0010-T02 | done | — | workplans/AGENTIC-WP-0010-weekly-retro.md | +| task | AGENTIC-WP-0010-T03 | done | — | workplans/AGENTIC-WP-0010-weekly-retro.md | +| task | AGENTIC-WP-0011-T01 | done | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md | +| task | AGENTIC-WP-0011-T02 | done | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md | +| task | AGENTIC-WP-0011-T03 | done | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md | diff --git a/workplans/ADHOC-2026-08-20.md b/workplans/ADHOC-2026-08-20.md new file mode 100644 index 0000000..57037b1 --- /dev/null +++ b/workplans/ADHOC-2026-08-20.md @@ -0,0 +1,72 @@ +--- +id: ADHOC-2026-08-20 +type: workplan +title: "Clarify agentic-resources scope for leadership and workforce architecture" +domain: infotech +repo: agentic-resources +status: finished +owner: codex +topic_slug: agent-workforce-governance +created: "2026-08-20" +updated: "2026-08-20" +--- + +# Clarify agentic-resources scope for leadership and workforce architecture + +## Review and refine the repository boundary + +```task +id: ADHOC-2026-08-20-T01 +status: done +priority: medium +``` + +Review the implemented Helix Forge subsystem, `INTENT.md`, and the current +cross-repository architecture proposal from KAIZEN-WP-0013. Replace the stale +generated `SCOPE.md` with an evidence-based operational boundary that: + +- distinguishes implemented agent-performance learning from proposed + workforce-management contracts; +- relates leadership-owned goals and mandates to agent workforce assignments; +- maps role, blueprint, budget, resource, scheduling, runtime, human-workforce, + and policy ownership without creating a monolithic control plane; and +- records the unimplemented inventory, `RoleAssignment`, capacity, + development, portfolio, and retirement gap. + +Completed 2026-08-20. `SCOPE.md` now documents the current implementation, the +recommended agent-workforce boundary, the leadership-to-execution control +spine, explicit ecosystem ownership, and current maturity gaps. + +## Correct the execution-layer abstraction + +```task +id: ADHOC-2026-08-20-T02 +status: done +priority: medium +``` + +Review `glas-harness` and `rein-aharness` implementation, intent, scope, +contracts, registry, and accepted ADRs. Correct the agentic-resources +architecture so the workforce and instance contracts target `glas-harness` as +the primary execution-layer abstraction rather than coupling directly to +`rein-aharness`. + +Completed 2026-08-20. The scope now identifies Glas as owner of the harness +contract, execution profiles, rein routing, sandbox coordination, and gateway +evidence. Concrete reins—including the live Claude-Code-based +`rein-aharness` and the implemented `rein-openweights` alternative—remain +replaceable inner-loop backends. Assignment and instance contracts should +reference a versioned Glas profile or compatible execution requirements so +the rein, sandbox, tool policy, and base-model constellation can vary without +rewriting workforce architecture. + +Follow-through later on 2026-08-20: `GLAS-WP-0004` implemented the referenced +contract as Glas contract `1.0`, including explicit versioned profiles for +`rein-aharness` and `rein-openweights`, common execution evidence, and +assignment/role/duty/goal/resource-envelope reference fields. The +agentic-resources boundary above is now an available execution integration, +not only an architectural target. + +Live follow-through completed 2026-08-21: both the Claude-backed and +open-weight profiles completed the same bounded task with real commits and +verified sandbox teardown through the Glas contract.