Plan intent boundary guardrails

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a028de-e2c8-7732-8521-46a7fc5db82f

history/2026-08-23-scope-against-intent-assessment.md

@@ -235,3 +235,17 @@ operations around that bridge. Those additions are useful and controlled, but
 INTENT must name them precisely so future contributors can distinguish accepted
 operational state from prohibited task lifecycle and accepted bounded actions
 from a general executor.
+
+## Follow-up workplan
+
+`ACTIVITY-WP-0035` addresses the locally actionable and boundary-defining gaps:
+
+- G1 operational delivery state vs work-item lifecycle;
+- G2 bounded-operation admission and workflow separation;
+- G6 truthful review-worthy output semantics;
+- G7 bounded instruction audit promises; and
+- G8 misleading compatibility surfaces.
+
+G3 remains with ACTIVITY-WP-0031, G4 with ACTIVITY-WP-0032, G5 with the State
+Hub retirement program after ACTIVITY-WP-0029's completed port slice, and G9
+with ACTIVITY-WP-0034's natural-run acceptance gate.

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

@@ -0,0 +1,304 @@
+---
+id: ACTIVITY-WP-0035
+type: workplan
+title: "Make the execution boundary enforceable and the review contract truthful"
+domain: infotech
+repo: activity-core
+status: ready
+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
+---
+
+# 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: todo
+priority: high
+```
+
+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: wait
+priority: high
+```
+
+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: wait
+priority: high
+```
+
+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: todo
+priority: medium
+```
+
+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: todo
+priority: medium
+```
+
+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: wait
+priority: medium
+```
+
+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: todo
+priority: low
+```
+
+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: wait
+priority: high
+```
+
+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
+
+- [ ] `INTENT.md` explicitly distinguishes work-item lifecycle from ops-run delivery state
+- [ ] The bounded-operation exception is governed by a reviewed contract, not convention
+- [ ] Definition sync refuses unknown or incomplete mutating operation declarations
+- [ ] Context resolvers are read-only; mutations run in an explicit bounded-operation phase
+- [ ] Instruction audit wording matches persisted evidence and raw sensitive payloads remain excluded
+- [ ] `review_required` has truthful, tested hold/release or advisory-only semantics
+- [ ] Misleading executor/CRUD/README surfaces are removed or precisely qualified
+- [ ] Full tests pass and production rollout preserves current schedules and evidence
+
+## 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.