Clarify verify and capability warning semantics

Author: amittell

docs/architecture.md

@@ -68,6 +68,7 @@ Each provider file auto-registers with its registry on import (side-effect regis
 - **Phase 4.5: Authorization** (optional) -- invoke external policy engine (OPA, Cedar, Topaz) when an authorization block is configured. Decisions: `permit`, `deny`, `require-escalation`. Skipped entirely when no authorization block resolves for the task.
 - **Phase 5: Execution** -- run the tool, capture stdout/stderr/exit code/duration, compute hashes.
 - **Phase 6: Evidence Generation** -- build canonical evidence payload, attest execution, verify evidence if required.
+- **Phase 6.5: Post-exec Verify** (optional) -- run `workflow.verify` / `task.verify` after a successful command. This is an operator-local postcondition check recorded separately from evidence; verify failures can still fail the task or downgrade to warnings according to `verify.on_failure`.
 - **Phase 7: Audit** -- write structured append-only audit record with declared/resolved identity, authorization proof summary, delegation chain, trust level, authorization decision, and runtime instance attribution.
 - **Phase 8: Cleanup** -- delete temporary files, destroy ephemeral materialization and derived handoff credentials.
 

docs/execution-identity.md

@@ -1722,6 +1722,14 @@ Evidence verification occurs after execution (Phase 5) has already completed. A
 - when `verify.required` is `false`, a verification failure is recorded as a warning but does not affect the exit code
 - the evidence envelope (including the failed verification status) is always written to the audit record so that operators can investigate
 
+### Phase 6.5: Post-execution Verify
+
+- only enter this phase when the main command exited successfully and a workflow/task `verify` block resolves
+- run the declared verify shell in the task's effective execution context
+- treat `verify` as an operator-local postcondition separate from evidence attestation; the attested evidence payload reflects the main command result, not the later verify shell outcome
+- when `verify.on_failure` is `error`, return a non-zero status after cleanup and audit
+- when `verify.on_failure` is `warn`, record the verify failure as a warning without changing the exit code
+
 ### Phase 7: Audit
 
 - write append-only audit record

docs/field-reference.md

@@ -274,12 +274,16 @@ When `ref` is present, the referenced profile is loaded first, then inline field
 |-------|------|----------|--------|-------------|
 | `child_credential_policy` | string | No | `none`, `inherit`, `downscope`, `independent` | Controls how a child task receives or derives credentials relative to its parent. Workflow-level values act as defaults for tasks. |
 
+`child_credential_policy: "downscope"` is validated as a capability warning when a backend lacks `credential_handoff`: the scheduler can still persist the job, but child narrowing will not be enforceable at dispatch. This is intentionally softer than `identity.presentation.handoff != "none"`, which is a hard compatibility requirement because the active runtime/backend must advertise explicit handoff semantics up front.
+
 ---
 
 ## Task Verify Fields
 
 Runs a shell command after the main task succeeds. Workflow-level `verify` acts as the default for tasks; a task-level `verify` replaces the workflow block and omitted optional fields fall back to built-in defaults.
 
+In the v0.2 execution pipeline, `verify` runs after evidence generation. Evidence and attestation therefore describe the main command result; the `verify` outcome is recorded separately and can still flip the final task status according to `on_failure`. If operators need end-to-end proof that includes the verification step, model that requirement in the evidence payload rather than assuming `verify` is part of the attested result.
+
 | Field | Type | Required | Values | Description |
 |-------|------|----------|--------|-------------|
 | `shell` | string | Yes | -- | Shell command to run after a successful task execution. |
@@ -346,6 +350,8 @@ Runs a shell command after the main task succeeds. Workflow-level `verify` acts
 | `cleanup` | string | No | `always`, `on-success`, `on-failure`, `never` | When credential cleanup runs. |
 | `default_redaction` | boolean | No | -- | Whether credential values are redacted by default in audit output. |
 
+`identity.presentation.handoff` is stricter than `child_credential_policy`: any non-`none` handoff mode requires explicit `credential_handoff` support from the active runtime/backend during capability negotiation, because the handoff boundary itself must be modeled first-class.
+
 ### Identity Presentation Bindings
 
 Each element in the `bindings` array is an object with these fields:

test/agentcli.test.js

@@ -7577,6 +7577,78 @@ test('applyManifestToScheduler includes capabilities metadata in result', async
   assert.strictEqual(result.capabilities.handoff_version, '2');
 });
 
+test('applyManifestToScheduler preserves capability warnings in structured result', async () => {
+  const manifest = {
+    version: '0.2',
+    workflows: [{
+      id: 'warning-wf',
+      name: 'Warning Workflow',
+      tasks: [{
+        id: 'child-task',
+        name: 'Downscope Child',
+        prompt: 'exercise capability warning path',
+        target: { session_target: 'isolated' },
+        schedule: { cron: '0 * * * *' },
+        delivery: { mode: 'none' },
+        child_credential_policy: 'downscope',
+      }]
+    }]
+  };
+  const runner = {
+    invocation: { label: 'fake-scheduler' },
+    queryCapabilities() {
+      return {
+        scheduler_version: '0.2.0',
+        schema_version: 22,
+        handoff_version: '2',
+        features: {
+          approvals: 'runtime',
+          runtime_execution: true,
+          identity_declaration: true,
+          runtime_identity_resolution: true,
+          trust_evaluation: true,
+          authorization_proof_verification: true,
+          authorization_hook: true,
+          evidence_generation: true,
+          delegation_validation: false,
+          credential_handoff: false,
+          audit_export: true
+        }
+      };
+    },
+    listJobs() {
+      return [];
+    },
+    addJob(spec) {
+      return { ok: true, job: spec };
+    },
+    updateJob(id, spec) {
+      return { ok: true, job: spec };
+    }
+  };
+
+  const stderrWrites = [];
+  const originalStderrWrite = process.stderr.write;
+  process.stderr.write = (chunk, ...args) => {
+    stderrWrites.push(String(chunk));
+    const cb = args.find(arg => typeof arg === 'function');
+    if (cb) cb();
+    return true;
+  };
+
+  try {
+    const result = await applyManifestToScheduler(manifest, { runner });
+    assert.strictEqual(result.ok, true);
+    assert.ok(Array.isArray(result.capabilities?.warnings));
+    assert.strictEqual(result.capabilities.warnings.length, 1);
+    assert.strictEqual(result.capabilities.warnings[0].feature, 'credential_handoff');
+    assert.ok(result.capabilities.warnings[0].message.includes('child_credential_policy="downscope"'));
+    assert.ok(stderrWrites.some(line => line.includes('child_credential_policy="downscope"')));
+  } finally {
+    process.stderr.write = originalStderrWrite;
+  }
+});
+
 test('applyManifestToScheduler skips runtime capability queries for pure v0.1 manifests', async () => {
   let capabilityCalls = 0;
   const runner = {