Skip to content

Commit 99a86de

Browse files
mdhellermdheller
committed
feat(agentic-shell): freeze task object model + risk-based approval contract
Integrate the buildable-now slice of the "Agentic GitLab-Style Shell v0.1" spec: make the task object first-class as machine-readable contracts with enforcement teeth. Covers the spec's Immediate next design steps 1 (freeze the task object schema) and 2 (define the approval/policy engine contract). Schemas (draft 2020-12, urn:srcos:* + sourceos.ai $id conventions): - agentic-task: goal, scope, policies, autonomyLevel, budget, owner, state, outputs, auditLog, confidenceSummary, approvalRequirements - agentic-workset: task-scoped collection for comparison / batch action - agentic-evidence-packet: the trust surface for findings/actions - agentic-recommended-action: risk tier + rationale + action lifecycle state Teeth (scripts/validate_agentic_shell.py, beyond JSON Schema): - every action must state why it fell into its risk tier - medium/high-risk actions cannot reach approved/executing/succeeded without non-empty approvalRefs; high-risk also requires richer evidence - waiting_for_approval tasks require non-empty approvalRequirements - content digests are SHA-256 (FIPS) Negative fixtures under examples/agentic-shell/negative/ prove the gate bites; CI (.github/workflows/agentic-shell.yml) asserts they fail. Desktop shell anatomy, layout, keyboard model, workflows, preview/undo and telemetry are UI/runtime work tracked in a follow-up issue.
1 parent a81bc8a commit 99a86de

15 files changed

Lines changed: 843 additions & 0 deletions

‎.github/workflows/agentic-shell.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: agentic-shell
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'schemas/agentic-task.schema.json'
7+
- 'schemas/agentic-workset.schema.json'
8+
- 'schemas/agentic-evidence-packet.schema.json'
9+
- 'schemas/agentic-recommended-action.schema.json'
10+
- 'examples/agentic-shell/**'
11+
- 'scripts/validate_agentic_shell.py'
12+
- '.github/workflows/agentic-shell.yml'
13+
push:
14+
branches:
15+
- main
16+
paths:
17+
- 'schemas/agentic-task.schema.json'
18+
- 'schemas/agentic-workset.schema.json'
19+
- 'schemas/agentic-evidence-packet.schema.json'
20+
- 'schemas/agentic-recommended-action.schema.json'
21+
- 'examples/agentic-shell/**'
22+
- 'scripts/validate_agentic_shell.py'
23+
- '.github/workflows/agentic-shell.yml'
24+
workflow_dispatch:
25+
26+
permissions:
27+
contents: read
28+
29+
jobs:
30+
validate:
31+
runs-on: ubuntu-latest
32+
steps:
33+
- uses: actions/checkout@v4
34+
- uses: actions/setup-python@v5
35+
with:
36+
python-version: '3.11'
37+
- run: python -m pip install jsonschema
38+
- name: Validate positive examples
39+
run: python scripts/validate_agentic_shell.py
40+
- name: Assert high-risk-without-approval fixture fails (approval model bites)
41+
run: |
42+
if python scripts/validate_agentic_shell.py \
43+
examples/agentic-shell/negative/agentic-recommended-action.high-risk-no-approval.fail.json; then
44+
echo 'negative fixture unexpectedly passed: high-risk action without approval'
45+
exit 1
46+
fi
47+
- name: Assert waiting-for-approval-without-requirements fixture fails
48+
run: |
49+
if python scripts/validate_agentic_shell.py \
50+
examples/agentic-shell/negative/agentic-task.waiting-approval-empty.fail.json; then
51+
echo 'negative fixture unexpectedly passed: waiting_for_approval without approvalRequirements'
52+
exit 1
53+
fi

‎docs/agentic-gitlab-style-shell.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Agentic GitLab-Style Shell — object model (v0.1)
2+
3+
This document records the first buildable slice of the *Agentic GitLab-Style Shell*
4+
spec (v0.1): freezing the **task object schema** and defining the **approval /
5+
policy contract** as machine-readable schemas in `sourceos-shell`.
6+
7+
The spec redesigns the GitLab group/project shell from a navigation-first
8+
administrative interface into a supervisory-control workspace for cross-repository
9+
agentic operations. It makes the *task object* first-class so the shell can
10+
organize around supervision (what is the goal, what is the agent doing, why, on
11+
what evidence, what needs approval) rather than navigation.
12+
13+
Per the spec's *Immediate next design steps*, step 1 ("Freeze the task object
14+
schema") and step 2 ("Define the approval and policy engine contract") are
15+
implemented here. The remaining steps (desktop shell anatomy, layout, keyboard
16+
model, clickable prototype, telemetry) are UI/runtime work tracked separately —
17+
see the linked issue.
18+
19+
## What is frozen here
20+
21+
| Object | Schema | Spec section |
22+
|---|---|---|
23+
| Task | `schemas/agentic-task.schema.json` | Object model → Task object; State model |
24+
| Workset | `schemas/agentic-workset.schema.json` | Object model → Workset |
25+
| Evidence packet | `schemas/agentic-evidence-packet.schema.json` | Object model → Evidence packet |
26+
| Recommended action | `schemas/agentic-recommended-action.schema.json` | State model; Approval model |
27+
28+
### State model
29+
30+
* **Task states**: `drafting`, `ready`, `running`, `waiting_for_evidence`,
31+
`waiting_for_approval`, `blocked`, `completed`, `aborted`, `rolled_back`.
32+
* **Action states**: `proposed`, `staged`, `approved`, `executing`, `succeeded`,
33+
`failed`, `reverted`.
34+
35+
### Approval model (risk-based, explicit)
36+
37+
Risk tiers `low` / `medium` / `high` drive approval. The schemas and validator
38+
enforce the spec's rule that risk-based approval must be explicit:
39+
40+
* every recommended action must state **why** it fell into its risk tier
41+
(`riskRationale`, non-empty);
42+
* `medium`/`high`-risk actions may not reach `approved` / `executing` /
43+
`succeeded` without a non-empty `approvalRefs`;
44+
* `high`-risk actions additionally require richer evidence (non-empty
45+
`evidenceRefs`);
46+
* a task in `waiting_for_approval` must carry non-empty `approvalRequirements`.
47+
48+
These invariants live in `scripts/validate_agentic_shell.py` (beyond JSON Schema)
49+
and are proven to bite by negative fixtures under
50+
`examples/agentic-shell/negative/` that CI asserts must fail.
51+
52+
## FIPS
53+
54+
Any content digest (`auditLog[].contentDigest`, evidence `contentDigest`) is
55+
SHA-256 — `sha256:<64 hex>` — enforced by both schema pattern and validator.
56+
57+
## Validate locally
58+
59+
```bash
60+
python -m pip install jsonschema
61+
python scripts/validate_agentic_shell.py
62+
```
63+
64+
## Not yet buildable (tracked)
65+
66+
The desktop shell anatomy (five persistent regions: global objective bar, task
67+
status strip, left rail, center work canvas, right inspector, bottom timeline),
68+
layout spec, keyboard/accessibility model, primary workflows (group health audit,
69+
dependency update campaign, ownership remediation), preview/simulation and undo
70+
surfaces, and telemetry require a shell frontend + orchestration runtime that
71+
does not yet exist in this repo. These are filed as a follow-up issue with
72+
acceptance criteria.

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"evidenceId": "urn:srcos:agentic-evidence:service-alpha-ci-fail-demo-0001",
3+
"specVersion": "0.1.0",
4+
"resourceId": "urn:srcos:repo:developers/service-alpha-demo",
5+
"sourceType": "ci_run",
6+
"sourcePointer": "urn:srcos:ci-run:developers/service-alpha-demo/pipeline-4821",
7+
"contentDigest": "sha256:9f8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a493827160f5e4d3c2b1a0",
8+
"extractedClaim": "CI pipeline #4821 failed on step 'lint' at 2026-08-03T08:40:00Z.",
9+
"confidence": 0.97,
10+
"freshness": {
11+
"observedAt": "2026-08-03T08:45:00Z",
12+
"ageSeconds": 900,
13+
"stale": false
14+
},
15+
"policyRelevance": [
16+
"urn:srcos:policy:open-issues-only-in-active-repos"
17+
]
18+
}

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"actionId": "urn:srcos:agentic-action:security-remediation-gateway-demo-0002",
3+
"specVersion": "0.1.0",
4+
"taskId": "urn:srcos:agentic-task:dep-update-campaign-demo-0002",
5+
"worksetId": null,
6+
"actionClass": "security-remediation",
7+
"riskTier": "high",
8+
"riskRationale": "Security remediation with service impact on a production gateway; requires explicit approval and richer evidence.",
9+
"state": "approved",
10+
"targetRef": "urn:srcos:service:services/gateway-demo",
11+
"evidenceRefs": [
12+
"urn:srcos:agentic-evidence:service-alpha-ci-fail-demo-0001"
13+
],
14+
"preview": {
15+
"diffRef": "urn:srcos:diff:gateway-demo-openssl-bump",
16+
"draftPreviewRef": "urn:srcos:mr-draft:services/gateway-demo-bump-openssl",
17+
"expectedBlastRadius": "gateway service + 3 downstream consumers",
18+
"policyCompliant": true,
19+
"rollbackPath": "revert MR + redeploy prior image"
20+
},
21+
"approvalRefs": [
22+
"urn:srcos:approval:operator-demo-gateway-security-remediation-0002"
23+
],
24+
"policyDecisionRefs": [
25+
"urn:srcos:policy-decision:agentic-action-security-remediation-gateway-demo-0002"
26+
]
27+
}

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"actionId": "urn:srcos:agentic-action:create-issue-draft-alpha-demo-0001",
3+
"specVersion": "0.1.0",
4+
"taskId": "urn:srcos:agentic-task:group-health-audit-demo-0001",
5+
"worksetId": "urn:srcos:agentic-workset:unowned-repos-demo-0001",
6+
"actionClass": "create-issue-draft",
7+
"riskTier": "low",
8+
"riskRationale": "Creates an issue draft only; does not open it and touches no production surface.",
9+
"state": "staged",
10+
"targetRef": "urn:srcos:repo:developers/service-alpha-demo",
11+
"evidenceRefs": [
12+
"urn:srcos:agentic-evidence:service-alpha-ci-fail-demo-0001"
13+
],
14+
"preview": {
15+
"diffRef": null,
16+
"draftPreviewRef": "urn:srcos:issue-draft:service-alpha-demo-ci-fail",
17+
"expectedBlastRadius": "single repo, draft only",
18+
"policyCompliant": true,
19+
"rollbackPath": "discard draft"
20+
},
21+
"approvalRefs": [],
22+
"policyDecisionRefs": [
23+
"urn:srcos:policy-decision:agentic-action-create-issue-draft-alpha-demo-0001"
24+
]
25+
}

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"taskId": "urn:srcos:agentic-task:group-health-audit-demo-0001",
3+
"specVersion": "0.1.0",
4+
"goal": "Audit all repos in Developers for failing CI, stale dependencies, and missing owners. Draft issues but do not open them.",
5+
"scope": {
6+
"scopeRef": "urn:srcos:group:developers-demo",
7+
"selectionQuery": "group:Developers",
8+
"resourceRefs": [
9+
"urn:srcos:repo:developers/service-alpha-demo",
10+
"urn:srcos:repo:developers/service-beta-demo"
11+
]
12+
},
13+
"policies": [
14+
"urn:srcos:policy:no-prod-writes-without-approval",
15+
"urn:srcos:policy:open-issues-only-in-active-repos"
16+
],
17+
"autonomyLevel": "stage_low_risk",
18+
"budget": {
19+
"timeCapSeconds": 3600,
20+
"actionCap": 50,
21+
"costCapUnits": null
22+
},
23+
"owner": "urn:srcos:subject:operator-demo",
24+
"state": "running",
25+
"createdAt": "2026-08-03T09:00:00Z",
26+
"updatedAt": "2026-08-03T09:04:00Z",
27+
"outputs": [],
28+
"auditLog": [
29+
{
30+
"at": "2026-08-03T09:00:00Z",
31+
"event": "task.materialized_scope",
32+
"actorRef": "urn:srcos:subject:operator-demo",
33+
"contentDigest": "sha256:3b1f2c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7089a1b2c3d4e5f"
34+
},
35+
{
36+
"at": "2026-08-03T09:03:00Z",
37+
"event": "task.health_matrix_populated",
38+
"actorRef": null,
39+
"contentDigest": null
40+
}
41+
],
42+
"confidenceSummary": {
43+
"score": 0.82,
44+
"uncertaintyNote": "Ownership signal ambiguous for 2 of 14 repos."
45+
},
46+
"approvalRequirements": [],
47+
"policyDecisionRefs": [
48+
"urn:srcos:policy-decision:agentic-task-group-health-audit-demo-0001"
49+
]
50+
}

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"taskId": "urn:srcos:agentic-task:dep-update-campaign-demo-0002",
3+
"specVersion": "0.1.0",
4+
"goal": "Find all services with outdated critical dependencies. Prepare patch branches and draft MRs only for services with passing tests.",
5+
"scope": {
6+
"scopeRef": "urn:srcos:group:services-demo",
7+
"selectionQuery": "dependency.severity:critical AND tests:passing",
8+
"resourceRefs": [
9+
"urn:srcos:service:services/gateway-demo"
10+
]
11+
},
12+
"policies": [
13+
"urn:srcos:policy:no-prod-writes-without-approval"
14+
],
15+
"autonomyLevel": "suggest",
16+
"budget": null,
17+
"owner": "urn:srcos:subject:operator-demo",
18+
"state": "waiting_for_approval",
19+
"createdAt": "2026-08-03T10:00:00Z",
20+
"updatedAt": "2026-08-03T10:12:00Z",
21+
"outputs": [
22+
"urn:srcos:mr-draft:services/gateway-demo-bump-openssl"
23+
],
24+
"auditLog": [
25+
{
26+
"at": "2026-08-03T10:11:00Z",
27+
"event": "task.escalated_high_risk",
28+
"actorRef": null,
29+
"contentDigest": null
30+
}
31+
],
32+
"confidenceSummary": {
33+
"score": 0.9,
34+
"uncertaintyNote": null
35+
},
36+
"approvalRequirements": [
37+
{
38+
"requirementRef": "urn:srcos:approval-req:gateway-demo-dependency-touches-build-config",
39+
"riskTier": "medium",
40+
"reason": "Dependency update touches build config."
41+
}
42+
],
43+
"policyDecisionRefs": [
44+
"urn:srcos:policy-decision:agentic-task-dep-update-campaign-demo-0002"
45+
]
46+
}

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"worksetId": "urn:srcos:agentic-workset:unowned-repos-demo-0001",
3+
"specVersion": "0.1.0",
4+
"taskId": "urn:srcos:agentic-task:group-health-audit-demo-0001",
5+
"selectionQuery": "show only unowned repos with critical vulns and no release in 90 days",
6+
"resources": [
7+
"urn:srcos:repo:developers/service-alpha-demo",
8+
"urn:srcos:repo:developers/service-gamma-demo"
9+
],
10+
"aggregateRisk": "high",
11+
"recommendedActionRefs": [
12+
"urn:srcos:agentic-action:create-issue-draft-alpha-demo-0001"
13+
],
14+
"blockedReasons": [
15+
"No CODEOWNERS present; owner cannot be auto-assigned."
16+
]
17+
}

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"actionId": "urn:srcos:agentic-action:prod-config-change-demo-9001",
3+
"specVersion": "0.1.0",
4+
"taskId": "urn:srcos:agentic-task:dep-update-campaign-demo-0002",
5+
"worksetId": null,
6+
"actionClass": "prod-config-change",
7+
"riskTier": "high",
8+
"riskRationale": "Production config change.",
9+
"state": "approved",
10+
"targetRef": "urn:srcos:service:services/gateway-demo",
11+
"evidenceRefs": [],
12+
"approvalRefs": [],
13+
"policyDecisionRefs": []
14+
}

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"taskId": "urn:srcos:agentic-task:bad-waiting-approval-demo-9002",
3+
"specVersion": "0.1.0",
4+
"goal": "Apply mass permission changes across all repositories.",
5+
"scope": {
6+
"scopeRef": "urn:srcos:group:developers-demo"
7+
},
8+
"autonomyLevel": "suggest",
9+
"owner": "urn:srcos:subject:operator-demo",
10+
"state": "waiting_for_approval",
11+
"createdAt": "2026-08-03T11:00:00Z",
12+
"updatedAt": "2026-08-03T11:05:00Z",
13+
"approvalRequirements": [],
14+
"policyDecisionRefs": [
15+
"urn:srcos:policy-decision:agentic-task-bad-waiting-approval-demo-9002"
16+
]
17+
}

0 commit comments

Comments
 (0)