feat(agentic-shell): freeze task object model + risk-based approval contract

.github/workflows/agentic-shell.yml

@@ -0,0 +1,53 @@
+name: agentic-shell
+
+on:
+  pull_request:
+    paths:
+      - 'schemas/agentic-task.schema.json'
+      - 'schemas/agentic-workset.schema.json'
+      - 'schemas/agentic-evidence-packet.schema.json'
+      - 'schemas/agentic-recommended-action.schema.json'
+      - 'examples/agentic-shell/**'
+      - 'scripts/validate_agentic_shell.py'
+      - '.github/workflows/agentic-shell.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'schemas/agentic-task.schema.json'
+      - 'schemas/agentic-workset.schema.json'
+      - 'schemas/agentic-evidence-packet.schema.json'
+      - 'schemas/agentic-recommended-action.schema.json'
+      - 'examples/agentic-shell/**'
+      - 'scripts/validate_agentic_shell.py'
+      - '.github/workflows/agentic-shell.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install jsonschema
+      - name: Validate positive examples
+        run: python scripts/validate_agentic_shell.py
+      - name: Assert high-risk-without-approval fixture fails (approval model bites)
+        run: |
+          if python scripts/validate_agentic_shell.py \
+              examples/agentic-shell/negative/agentic-recommended-action.high-risk-no-approval.fail.json; then
+            echo 'negative fixture unexpectedly passed: high-risk action without approval'
+            exit 1
+          fi
+      - name: Assert waiting-for-approval-without-requirements fixture fails
+        run: |
+          if python scripts/validate_agentic_shell.py \
+              examples/agentic-shell/negative/agentic-task.waiting-approval-empty.fail.json; then
+            echo 'negative fixture unexpectedly passed: waiting_for_approval without approvalRequirements'
+            exit 1
+          fi

docs/agentic-gitlab-style-shell.md

@@ -0,0 +1,72 @@
+# Agentic GitLab-Style Shell — object model (v0.1)
+
+This document records the first buildable slice of the *Agentic GitLab-Style Shell*
+spec (v0.1): freezing the **task object schema** and defining the **approval /
+policy contract** as machine-readable schemas in `sourceos-shell`.
+
+The spec redesigns the GitLab group/project shell from a navigation-first
+administrative interface into a supervisory-control workspace for cross-repository
+agentic operations. It makes the *task object* first-class so the shell can
+organize around supervision (what is the goal, what is the agent doing, why, on
+what evidence, what needs approval) rather than navigation.
+
+Per the spec's *Immediate next design steps*, step 1 ("Freeze the task object
+schema") and step 2 ("Define the approval and policy engine contract") are
+implemented here. The remaining steps (desktop shell anatomy, layout, keyboard
+model, clickable prototype, telemetry) are UI/runtime work tracked separately —
+see the linked issue.
+
+## What is frozen here
+
+| Object | Schema | Spec section |
+|---|---|---|
+| Task | `schemas/agentic-task.schema.json` | Object model → Task object; State model |
+| Workset | `schemas/agentic-workset.schema.json` | Object model → Workset |
+| Evidence packet | `schemas/agentic-evidence-packet.schema.json` | Object model → Evidence packet |
+| Recommended action | `schemas/agentic-recommended-action.schema.json` | State model; Approval model |
+
+### State model
+
+* **Task states**: `drafting`, `ready`, `running`, `waiting_for_evidence`,
+  `waiting_for_approval`, `blocked`, `completed`, `aborted`, `rolled_back`.
+* **Action states**: `proposed`, `staged`, `approved`, `executing`, `succeeded`,
+  `failed`, `reverted`.
+
+### Approval model (risk-based, explicit)
+
+Risk tiers `low` / `medium` / `high` drive approval. The schemas and validator
+enforce the spec's rule that risk-based approval must be explicit:
+
+* every recommended action must state **why** it fell into its risk tier
+  (`riskRationale`, non-empty);
+* `medium`/`high`-risk actions may not reach `approved` / `executing` /
+  `succeeded` without a non-empty `approvalRefs`;
+* `high`-risk actions additionally require richer evidence (non-empty
+  `evidenceRefs`);
+* a task in `waiting_for_approval` must carry non-empty `approvalRequirements`.
+
+These invariants live in `scripts/validate_agentic_shell.py` (beyond JSON Schema)
+and are proven to bite by negative fixtures under
+`examples/agentic-shell/negative/` that CI asserts must fail.
+
+## FIPS
+
+Any content digest (`auditLog[].contentDigest`, evidence `contentDigest`) is
+SHA-256 — `sha256:<64 hex>` — enforced by both schema pattern and validator.
+
+## Validate locally
+
+```bash
+python -m pip install jsonschema
+python scripts/validate_agentic_shell.py
+```
+
+## Not yet buildable (tracked)
+
+The desktop shell anatomy (five persistent regions: global objective bar, task
+status strip, left rail, center work canvas, right inspector, bottom timeline),
+layout spec, keyboard/accessibility model, primary workflows (group health audit,
+dependency update campaign, ownership remediation), preview/simulation and undo
+surfaces, and telemetry require a shell frontend + orchestration runtime that
+does not yet exist in this repo. These are filed as a follow-up issue with
+acceptance criteria.

examples/agentic-shell/agentic-evidence-packet.ci-failure.example.json

@@ -0,0 +1,18 @@
+{
+  "evidenceId": "urn:srcos:agentic-evidence:service-alpha-ci-fail-demo-0001",
+  "specVersion": "0.1.0",
+  "resourceId": "urn:srcos:repo:developers/service-alpha-demo",
+  "sourceType": "ci_run",
+  "sourcePointer": "urn:srcos:ci-run:developers/service-alpha-demo/pipeline-4821",
+  "contentDigest": "sha256:9f8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a493827160f5e4d3c2b1a0",
+  "extractedClaim": "CI pipeline #4821 failed on step 'lint' at 2026-08-03T08:40:00Z.",
+  "confidence": 0.97,
+  "freshness": {
+    "observedAt": "2026-08-03T08:45:00Z",
+    "ageSeconds": 900,
+    "stale": false
+  },
+  "policyRelevance": [
+    "urn:srcos:policy:open-issues-only-in-active-repos"
+  ]
+}

examples/agentic-shell/agentic-recommended-action.high-risk-approved.example.json

@@ -0,0 +1,27 @@
+{
+  "actionId": "urn:srcos:agentic-action:security-remediation-gateway-demo-0002",
+  "specVersion": "0.1.0",
+  "taskId": "urn:srcos:agentic-task:dep-update-campaign-demo-0002",
+  "worksetId": null,
+  "actionClass": "security-remediation",
+  "riskTier": "high",
+  "riskRationale": "Security remediation with service impact on a production gateway; requires explicit approval and richer evidence.",
+  "state": "approved",
+  "targetRef": "urn:srcos:service:services/gateway-demo",
+  "evidenceRefs": [
+    "urn:srcos:agentic-evidence:service-alpha-ci-fail-demo-0001"
+  ],
+  "preview": {
+    "diffRef": "urn:srcos:diff:gateway-demo-openssl-bump",
+    "draftPreviewRef": "urn:srcos:mr-draft:services/gateway-demo-bump-openssl",
+    "expectedBlastRadius": "gateway service + 3 downstream consumers",
+    "policyCompliant": true,
+    "rollbackPath": "revert MR + redeploy prior image"
+  },
+  "approvalRefs": [
+    "urn:srcos:approval:operator-demo-gateway-security-remediation-0002"
+  ],
+  "policyDecisionRefs": [
+    "urn:srcos:policy-decision:agentic-action-security-remediation-gateway-demo-0002"
+  ]
+}

examples/agentic-shell/agentic-recommended-action.low-risk-staged.example.json

@@ -0,0 +1,25 @@
+{
+  "actionId": "urn:srcos:agentic-action:create-issue-draft-alpha-demo-0001",
+  "specVersion": "0.1.0",
+  "taskId": "urn:srcos:agentic-task:group-health-audit-demo-0001",
+  "worksetId": "urn:srcos:agentic-workset:unowned-repos-demo-0001",
+  "actionClass": "create-issue-draft",
+  "riskTier": "low",
+  "riskRationale": "Creates an issue draft only; does not open it and touches no production surface.",
+  "state": "staged",
+  "targetRef": "urn:srcos:repo:developers/service-alpha-demo",
+  "evidenceRefs": [
+    "urn:srcos:agentic-evidence:service-alpha-ci-fail-demo-0001"
+  ],
+  "preview": {
+    "diffRef": null,
+    "draftPreviewRef": "urn:srcos:issue-draft:service-alpha-demo-ci-fail",
+    "expectedBlastRadius": "single repo, draft only",
+    "policyCompliant": true,
+    "rollbackPath": "discard draft"
+  },
+  "approvalRefs": [],
+  "policyDecisionRefs": [
+    "urn:srcos:policy-decision:agentic-action-create-issue-draft-alpha-demo-0001"
+  ]
+}

examples/agentic-shell/agentic-task.running-audit.example.json

@@ -0,0 +1,50 @@
+{
+  "taskId": "urn:srcos:agentic-task:group-health-audit-demo-0001",
+  "specVersion": "0.1.0",
+  "goal": "Audit all repos in Developers for failing CI, stale dependencies, and missing owners. Draft issues but do not open them.",
+  "scope": {
+    "scopeRef": "urn:srcos:group:developers-demo",
+    "selectionQuery": "group:Developers",
+    "resourceRefs": [
+      "urn:srcos:repo:developers/service-alpha-demo",
+      "urn:srcos:repo:developers/service-beta-demo"
+    ]
+  },
+  "policies": [
+    "urn:srcos:policy:no-prod-writes-without-approval",
+    "urn:srcos:policy:open-issues-only-in-active-repos"
+  ],
+  "autonomyLevel": "stage_low_risk",
+  "budget": {
+    "timeCapSeconds": 3600,
+    "actionCap": 50,
+    "costCapUnits": null
+  },
+  "owner": "urn:srcos:subject:operator-demo",
+  "state": "running",
+  "createdAt": "2026-08-03T09:00:00Z",
+  "updatedAt": "2026-08-03T09:04:00Z",
+  "outputs": [],
+  "auditLog": [
+    {
+      "at": "2026-08-03T09:00:00Z",
+      "event": "task.materialized_scope",
+      "actorRef": "urn:srcos:subject:operator-demo",
+      "contentDigest": "sha256:3b1f2c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7089a1b2c3d4e5f"
+    },
+    {
+      "at": "2026-08-03T09:03:00Z",
+      "event": "task.health_matrix_populated",
+      "actorRef": null,
+      "contentDigest": null
+    }
+  ],
+  "confidenceSummary": {
+    "score": 0.82,
+    "uncertaintyNote": "Ownership signal ambiguous for 2 of 14 repos."
+  },
+  "approvalRequirements": [],
+  "policyDecisionRefs": [
+    "urn:srcos:policy-decision:agentic-task-group-health-audit-demo-0001"
+  ]
+}

examples/agentic-shell/agentic-task.waiting-for-approval.example.json

@@ -0,0 +1,46 @@
+{
+  "taskId": "urn:srcos:agentic-task:dep-update-campaign-demo-0002",
+  "specVersion": "0.1.0",
+  "goal": "Find all services with outdated critical dependencies. Prepare patch branches and draft MRs only for services with passing tests.",
+  "scope": {
+    "scopeRef": "urn:srcos:group:services-demo",
+    "selectionQuery": "dependency.severity:critical AND tests:passing",
+    "resourceRefs": [
+      "urn:srcos:service:services/gateway-demo"
+    ]
+  },
+  "policies": [
+    "urn:srcos:policy:no-prod-writes-without-approval"
+  ],
+  "autonomyLevel": "suggest",
+  "budget": null,
+  "owner": "urn:srcos:subject:operator-demo",
+  "state": "waiting_for_approval",
+  "createdAt": "2026-08-03T10:00:00Z",
+  "updatedAt": "2026-08-03T10:12:00Z",
+  "outputs": [
+    "urn:srcos:mr-draft:services/gateway-demo-bump-openssl"
+  ],
+  "auditLog": [
+    {
+      "at": "2026-08-03T10:11:00Z",
+      "event": "task.escalated_high_risk",
+      "actorRef": null,
+      "contentDigest": null
+    }
+  ],
+  "confidenceSummary": {
+    "score": 0.9,
+    "uncertaintyNote": null
+  },
+  "approvalRequirements": [
+    {
+      "requirementRef": "urn:srcos:approval-req:gateway-demo-dependency-touches-build-config",
+      "riskTier": "medium",
+      "reason": "Dependency update touches build config."
+    }
+  ],
+  "policyDecisionRefs": [
+    "urn:srcos:policy-decision:agentic-task-dep-update-campaign-demo-0002"
+  ]
+}

examples/agentic-shell/agentic-workset.unowned-repos.example.json

@@ -0,0 +1,17 @@
+{
+  "worksetId": "urn:srcos:agentic-workset:unowned-repos-demo-0001",
+  "specVersion": "0.1.0",
+  "taskId": "urn:srcos:agentic-task:group-health-audit-demo-0001",
+  "selectionQuery": "show only unowned repos with critical vulns and no release in 90 days",
+  "resources": [
+    "urn:srcos:repo:developers/service-alpha-demo",
+    "urn:srcos:repo:developers/service-gamma-demo"
+  ],
+  "aggregateRisk": "high",
+  "recommendedActionRefs": [
+    "urn:srcos:agentic-action:create-issue-draft-alpha-demo-0001"
+  ],
+  "blockedReasons": [
+    "No CODEOWNERS present; owner cannot be auto-assigned."
+  ]
+}

examples/agentic-shell/negative/agentic-recommended-action.high-risk-no-approval.fail.json

@@ -0,0 +1,14 @@
+{
+  "actionId": "urn:srcos:agentic-action:prod-config-change-demo-9001",
+  "specVersion": "0.1.0",
+  "taskId": "urn:srcos:agentic-task:dep-update-campaign-demo-0002",
+  "worksetId": null,
+  "actionClass": "prod-config-change",
+  "riskTier": "high",
+  "riskRationale": "Production config change.",
+  "state": "approved",
+  "targetRef": "urn:srcos:service:services/gateway-demo",
+  "evidenceRefs": [],
+  "approvalRefs": [],
+  "policyDecisionRefs": []
+}

examples/agentic-shell/negative/agentic-task.waiting-approval-empty.fail.json

@@ -0,0 +1,17 @@
+{
+  "taskId": "urn:srcos:agentic-task:bad-waiting-approval-demo-9002",
+  "specVersion": "0.1.0",
+  "goal": "Apply mass permission changes across all repositories.",
+  "scope": {
+    "scopeRef": "urn:srcos:group:developers-demo"
+  },
+  "autonomyLevel": "suggest",
+  "owner": "urn:srcos:subject:operator-demo",
+  "state": "waiting_for_approval",
+  "createdAt": "2026-08-03T11:00:00Z",
+  "updatedAt": "2026-08-03T11:05:00Z",
+  "approvalRequirements": [],
+  "policyDecisionRefs": [
+    "urn:srcos:policy-decision:agentic-task-bad-waiting-approval-demo-9002"
+  ]
+}