activity-core/workplans/ACTIVITY-WP-0035-intent-boundary-guardrails.md

---
id: ACTIVITY-WP-0035
type: workplan
title: "Make the execution boundary enforceable and the review contract truthful"
domain: infotech
repo: activity-core
status: active
owner: codex
topic_slug: activity-core
priority: high
created: "2026-08-23"
updated: "2026-08-23"
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
quality_dor_note: "The 2026-08-23 implementation audit identified locally actionable boundary gaps. Existing provider, Glas, State Hub retirement, and natural SBOM-run work remain with their current workplans and are not duplicated here."
related:
  - ACT-ADR-003
  - ACT-ADR-005
  - ACT-ADR-006
  - ACTIVITY-WP-0023
  - ACTIVITY-WP-0029
  - ACTIVITY-WP-0031
  - ACTIVITY-WP-0032
  - ACTIVITY-WP-0034
state_hub_workstream_id: "fbcc10a9-bc1e-50b2-ba86-47adcb18666d"
---

# Make the Execution Boundary Enforceable and the Review Contract Truthful

## Origin

The 2026-08-23 assessment in
`history/2026-08-23-scope-against-intent-assessment.md` found that the product
still fulfills its Event Bridge purpose, but two implemented capabilities are
described only as exceptions:

1. `ops_runs` has a machine delivery lifecycle even though `INTENT.md` says
   activity-core does not track task lifecycle.
2. SBOM ingest, Forgejo package prune, and CNPG backup perform real bounded
   operations even though `INTENT.md` says activity-core does not execute work.

The audit also found two truthfulness gaps: the promised instruction audit is
stronger than the safe persisted evidence, and `review_required` sounds like a
hold/release mechanism even though it is metadata only.

These are more important than cosmetic cleanup because they determine which
future features are admissible. If the boundary remains implicit, a generic
shell executor or a second task database can arrive one reasonable-looking
change at a time.

## Goal

Make the accepted execution-delivery boundary explicit in governing documents
and enforce it in definition admission and workflow structure. At completion:

- an `ops_run` is unambiguously runtime delivery state, never a work-item record;
- a small, reviewable registry is the only way activity-core may perform a
  bounded operation;
- context resolution is read-only in semantics and mutating work has an
  explicit workflow stage;
- instruction audit promises match the non-secret data actually retained; and
- review-worthy output has either a real downstream hold/release contract or a
  name that truthfully communicates advisory-only metadata.

## Non-goals and existing owners

- Do not rotate the OpenRouter key or duplicate ACTIVITY-WP-0031.
- Do not repair the Glas/sand-boxer runtime or duplicate ACTIVITY-WP-0032.
- Do not manually fire the controlled-source SBOM schedule or duplicate
  ACTIVITY-WP-0034.
- Do not reopen the completed ACTIVITY-WP-0029 hub-port work. Remaining general
  State Hub progress migration belongs to the State Hub retirement program.
- Do not add workplan/task lifecycle, a project model, a general agent loop, a
  credential store, or a local mirror of Glas profiles.
- Do not persist raw prompts, provider responses, tool output, or secrets merely
  to satisfy an audit wording mismatch.

## Decision rules

1. Existing safe behavior wins over stale prose; reconcile prose without
   weakening the safety boundary.
2. A bounded operation must be named and statically admissible. “Shell command
   from definition data” is never an acceptable extension mechanism.
3. Every mutating operation needs fixed target selection, an idempotency model,
   a timeout/retry ceiling, credential ownership, and non-secret evidence.
4. `review_required` must not imply that output was held unless a downstream
   owner actually acknowledges and releases it.
5. Compatibility fields may be deprecated gradually, but new definitions must
   use the final semantics once selected.

## Align INTENT with the accepted runtime-delivery plane

```task
id: ACTIVITY-WP-0035-T01
status: done
priority: high
state_hub_task_id: "f091521c-1658-5be3-b6b4-44d0c498438d"
```

Reconcile `INTENT.md`, `SCOPE.md`, ACT-ADR-005, ACT-ADR-006, and
`docs/execution-queue-boundary.md` so they use one distinction:

- workplan/tracker tasks are durable human/work-item records owned downstream;
- `ops_runs` are durable runtime automation delivery records owned here, with
  claim/lease/retry/outcome state; and
- delivery state must never grow assignment, commitments, dependencies,
  project phases, or manual task-status semantics.

Record whether bounded operations are an accepted fourth part of the governing
principle or a narrowly specified implementation exception. If the latter,
write an ADR with the exception and its removal/review criteria.

Done when a reader can determine from `INTENT.md` alone why `ops_runs` do not
violate the task-lifecycle boundary and why a named bounded operation may run
without making activity-core a general executor.

## Add a bounded-operation admission contract

```task
id: ACTIVITY-WP-0035-T02
status: done
priority: high
state_hub_task_id: "2aaa5a74-2550-5a62-9ee3-86ada7c839f9"
```

Depends on T01. Introduce a central code-owned registry for the currently
accepted operation classes:

- controlled SBOM Nexus ingest;
- Forgejo package prune; and
- CNPG Option A backup.

For each class declare and validate the applicable safety fields: mutating vs
dry-run, maximum/fixed target selection, required idempotency input, timeout
ceiling, retry semantics, evidence sink requirement, and credential route
reference. Definition sync must reject unknown mutating queries and incomplete
operation declarations before database or Temporal projection.

Do not silently reinterpret existing production definitions. Provide a
compatibility validation report first, migrate the three definitions, then make
the stricter admission mode the production default.

Done when no new mutating operation can enter through a generic context/shell
query without an explicit reviewed registry entry and tests prove each refusal.

## Separate context reads from bounded mutations

```task
id: ACTIVITY-WP-0035-T03
status: done
priority: high
state_hub_task_id: "dacf1010-3d15-56f3-8f37-dd1296088e48"
```

Depends on T02. Make workflow phases match their names:

1. resolve and freeze read-only context;
2. execute an explicitly admitted bounded operation, if declared;
3. merge only its normalized outcome into the context snapshot;
4. persist mandatory non-secret evidence; then
5. evaluate rules/instructions and emit outputs.

Move mutating Forgejo prune and CNPG backup dispatch out of the generic `shell`
context resolver path. Preserve Temporal determinism, operation-specific
idempotency, existing dry-run/apply protections, fixed SBOM selection across
retries, and failure visibility. Do not create a generic subprocess activity
whose command comes from definition data.

Done when resolver interfaces are read-only by contract and all three admitted
operations pass unit, retry, redaction, and workflow-order tests.

## Reconcile instruction audit promises with safe evidence

```task
id: ACTIVITY-WP-0035-T04
status: done
priority: medium
state_hub_task_id: "db904650-a5fb-510f-8d7d-e65b4aa4e335"
```

Update the governing audit language to promise the evidence actually retained:
definition id/version, context snapshot or its bounded projection, prompt hash,
model/route metadata, validation outcome, emission refs, and normalized
execution evidence. Decide and document whether these inputs make the rendered
prompt reproducible; if not, describe the residual explicitly.

Add an audit-contract test proving that raw rendered prompts, model messages,
provider responses, tool output, and credential-shaped fields cannot enter
`activity_runs`, `task_spawn_log`, `ops_runs.result`, progress, or the public
run projection. Do not solve this task by storing raw prompts.

Done when `INTENT.md`, ADR-003, the runbook, and tests make the same bounded
audit claim.

## Decide the review-worthy output contract

```task
id: ACTIVITY-WP-0035-T05
status: done
priority: medium
state_hub_task_id: "d5903717-bf70-5970-81d1-ee11f47ef5a9"
```

Inventory every checked-in definition and API consumer of `review_required`,
then choose and record exactly one contract:

- **Hold/release:** a named downstream owner exposes an idempotent proposal,
  review decision, and release reference; activity-core does not emit the task
  through the normal sink before release.
- **Advisory only:** deprecate the misleading name in favor of an explicitly
  advisory field, preserve a bounded compatibility projection, and state that
  no hold occurred.

Consult issue-core/work-record and hub-core port owners before selecting a
hold/release destination. Do not implement a pending-review task database in
activity-core and do not equate a State Hub progress event with approval.

Done when the selected owner, schema, idempotency key, failure behavior, and
migration path are recorded in ADR-003 or a successor ADR.

## Implement and prove the selected review disposition

```task
id: ACTIVITY-WP-0035-T06
status: done
priority: medium
state_hub_task_id: "15e30f42-76a3-50e3-ab81-cb95a3d0ab6f"
```

Depends on T05. Implement the selected contract with fail-closed behavior:

- for hold/release, prove that review-required tasks cannot reach the normal
  task/ops-run emission path before an acknowledged release; or
- for advisory-only, migrate definitions and output schemas so operators cannot
  mistake the field for a queue or gate.

Cover task outputs, report-only instructions, invalid LLM output, partial item
recovery, retries, sink failures, and audit projections. Capture one bounded
production proof after provider-backed execution is healthy; until then,
deterministic tests and report-only production evidence are acceptable but do
not close the live acceptance item.

## Retire misleading compatibility surfaces

```task
id: ACTIVITY-WP-0035-T07
status: done
priority: low
state_hub_task_id: "79d1be4e-ec34-5c01-b5ac-dfb7dbafe827"
```

Reduce the remaining low-grade drift attractors:

1. Replace the seed-only `README.md` with accurate orientation and links to
   `INTENT.md`, `SCOPE.md`, runbook, API, and the `activity` CLI.
2. Label ActivityDefinition REST CRUD as basic row administration, or make it
   round-trip the full rules/instructions contract. Do not leave it presented
   as equivalent to markdown authoring.
3. Inventory live/dev use and row count for `TaskExecutorWorkflow` and
   `task_instances`. If zero and no supported caller remains, remove the stub,
   feature flag, registration path, persistence activity, and table in a normal
   forward migration. Otherwise record the exact compatibility owner and a
   dated removal gate.

Done when no public orientation or enabled-by-flag surface suggests that
activity-core is a general task executor.

## Verification and rollout

```task
id: ACTIVITY-WP-0035-T08
status: progress
priority: high
state_hub_task_id: "2ae1aca9-1c86-5b1a-b9fd-95059a24cd65"
```

Depends on T02–T07 as applicable.

- Run focused parser, workflow, rule/instruction, sink, ops-run, and API tests.
- Run the complete repository suite and migration upgrade/downgrade/upgrade
  test if T07 removes `task_instances`.
- Render and sync all checked-in definitions under strict bounded-operation
  admission before deployment.
- Deploy without manually firing schedules whose acceptance requires a natural
  run.
- Verify the deterministic automation status surface and record non-secret
  evidence for one read-only definition plus each admitted operation class at
  its next safe run.

## Acceptance

- [x] `INTENT.md` explicitly distinguishes work-item lifecycle from ops-run delivery state
- [x] The bounded-operation exception is governed by a reviewed contract, not convention
- [x] Definition sync refuses unknown or incomplete mutating operation declarations
- [x] Context resolvers are read-only; mutations run in an explicit bounded-operation phase
- [x] Instruction audit wording matches persisted evidence and raw sensitive payloads remain excluded
- [x] `review_required` has truthful, tested hold/release or advisory-only semantics
- [x] Misleading executor/CRUD/README surfaces are removed or precisely qualified
- [ ] Full tests pass and production rollout preserves current schedules and evidence

## Implementation evidence — 2026-08-23

- ACT-ADR-007 accepted and recorded as State Hub decision
  `2b1f0c01-1d6f-4fdc-b3e7-537ce0a0a1f8`.
- Strict parsing admitted all 12 checked-in definitions; refusal tests cover
  unknown shell queries, missing operation declarations, arbitrary script
  paths, missing evidence, target/limit bounds, and multiple mutations.
- Full suite: `453 passed, 1 skipped` in 139.62 seconds; subsequent API
  admission/render-focused suite: `40 passed`.
- PostgreSQL migration `0008 → 0009 → 0008 → 0009` passed in an isolated
  PostgreSQL 16 database. The final state has no `task_instances` table and has
  `task_spawn_log.review_advisory`.
- Production removal inventory before migration: zero `task_instances`, no
  worker feature flag, and zero Temporal `TaskExecutorWorkflow` executions.
- Compatibility detail is retained in
  `history/2026-08-23-bounded-operation-compatibility-report.md`.
- Production rollout imported image digest
  `sha256:1a267fed1c5ea09c93d90728336b5c6976df2fbf1b8d757fb8fc89aff8ec5e9c`,
  applied migration `0009`, strictly synced 27 local/external definitions with
  zero errors, and rolled API/worker/event-router to Ready. The worker now
  advertises only `orchestrator-tq`; DB inspection confirms the three admitted
  operation ids and the retired table/renamed audit column.
- Deterministic production status after rollout reports API/DB/Temporal healthy.
  Natural post-rollout operation evidence remains open: CNPG and SBOM next run
  2026-08-24; Forgejo prune next run 2026-08-30. No schedule was manually fired.

## Gap disposition

| 2026-08-23 gap | This workplan |
| --- | --- |
| G1 operational state boundary | T01 |
| G2 bounded side effects | T01–T03, T08 |
| G6 review routing | T05–T06 |
| G7 audit wording | T04 |
| G8 legacy/partial surfaces | T07 |

G3, G4, G5, and G9 retain their existing external/program/scheduled owners and
are dependencies or rollout context, not duplicate tasks here.