feat(mcp): return policy warnings for agent actions #37

Merged

pdurlej merged 1 commit from codex/mcp-policy-aware-actions into codex/columns-policies-and-wip

2026-05-10 13:44:42 +02:00

codex commented

2026-05-10 00:55:40 +02:00

Collaborator

Canary status: missing — fire 3+3 review before merge

Closes #13

Summary

Adds advisory policyWarnings to the narrow agent action result contract so Iskra can explain risky direct actions instead of silently treating every move as clean.

Scope

Adds structured warning codes for WIP limit breaches, blocked cards, target entry policy, source exit policy, and agentMovePolicy warnings/proposal-first states.
Returns policyWarnings from create_card and move_card results where relevant.
Persists the same warnings in agent_audit_event.result because the result object is audited before returning.
Updates MCP tool descriptions to tell callers that create/move actions may return advisory warnings.
Documents warning semantics in docs/agent-mcp-contract.md.
Adds cardRepo.getActiveCountByListId for WIP checks.

Non-goals

No hard policy enforcement in v1.
No autonomous repair, reprioritization, or board restructuring.
No widening of the direct write surface.
No production token/scope changes.

Spec sources read

Forgejo issue #13 mcp/policy-aware-actions.
docs/agent-mcp-contract.md column policy and direct action surface sections.
Existing agent move/create/comment/relation paths in packages/api/src/routers/agent.ts.

Tests / smoke

pnpm --filter @kan/db build
pnpm --filter @kan/api build
pnpm --filter @kan/api typecheck
pnpm --filter @kan/db typecheck
pnpm --filter @kan/mcp typecheck
pnpm --filter @kan/api test -- integration-tests/agent.integration.test.ts agent.test.ts integration-tests/card-relations.integration.test.ts integration-tests/list-policies.integration.test.ts
pnpm --filter @kan/api test -- integration-tests/agent.integration.test.ts agent.test.ts
pnpm exec prettier --check packages/db/src/repository/card.repo.ts packages/api/src/routers/agent.ts packages/api/integration-tests/agent.integration.test.ts packages/mcp/src/index.ts docs/agent-mcp-contract.md
git diff --check

Rollback

Ignore policyWarnings client-side to preserve existing action behavior.
Revert commit 106413b if the response-shape change breaks a strict client before it is updated.

Owner gates

Piotr approval before production deploy.
Piotr approval before treating proposal_required as a hard block in production.
Piotr approval before issuing or rotating production machine identities/tokens.

Canary status: missing — fire 3+3 review before merge Closes #13 ## Summary Adds advisory `policyWarnings` to the narrow agent action result contract so Iskra can explain risky direct actions instead of silently treating every move as clean. ## Scope - Adds structured warning codes for WIP limit breaches, blocked cards, target entry policy, source exit policy, and `agentMovePolicy` warnings/proposal-first states. - Returns `policyWarnings` from `create_card` and `move_card` results where relevant. - Persists the same warnings in `agent_audit_event.result` because the result object is audited before returning. - Updates MCP tool descriptions to tell callers that create/move actions may return advisory warnings. - Documents warning semantics in `docs/agent-mcp-contract.md`. - Adds `cardRepo.getActiveCountByListId` for WIP checks. ## Non-goals - No hard policy enforcement in v1. - No autonomous repair, reprioritization, or board restructuring. - No widening of the direct write surface. - No production token/scope changes. ## Spec sources read - Forgejo issue #13 `mcp/policy-aware-actions`. - `docs/agent-mcp-contract.md` column policy and direct action surface sections. - Existing agent move/create/comment/relation paths in `packages/api/src/routers/agent.ts`. ## Tests / smoke - `pnpm --filter @kan/db build` - `pnpm --filter @kan/api build` - `pnpm --filter @kan/api typecheck` - `pnpm --filter @kan/db typecheck` - `pnpm --filter @kan/mcp typecheck` - `pnpm --filter @kan/api test -- integration-tests/agent.integration.test.ts agent.test.ts integration-tests/card-relations.integration.test.ts integration-tests/list-policies.integration.test.ts` - `pnpm --filter @kan/api test -- integration-tests/agent.integration.test.ts agent.test.ts` - `pnpm exec prettier --check packages/db/src/repository/card.repo.ts packages/api/src/routers/agent.ts packages/api/integration-tests/agent.integration.test.ts packages/mcp/src/index.ts docs/agent-mcp-contract.md` - `git diff --check` ## Rollback - Ignore `policyWarnings` client-side to preserve existing action behavior. - Revert commit `106413b` if the response-shape change breaks a strict client before it is updated. ## Owner gates - Piotr approval before production deploy. - Piotr approval before treating `proposal_required` as a hard block in production. - Piotr approval before issuing or rotating production machine identities/tokens.

codex added 1 commit

2026-05-10 00:55:40 +02:00

feat(mcp): return policy warnings for agent actions 106413bfa3

codex referenced this pull request

2026-05-10 00:55:48 +02:00

mcp/policy-aware-actions #13

codex commented

2026-05-10 08:48:13 +02:00

Author

Collaborator

3+3 Review Result

Status: NOT READY / OWNER CHECKPOINT

Review lanes completed: tech-ollama-1, tech-ollama-2, tech-codex, product-ollama-1, product-ollama-2, product-claude-opus.

Deterministic checks on current stack tip:

PASS: @kan/db typecheck/build
PASS: @kan/shared typecheck/build
PASS: @kan/mcp typecheck/build
PASS: @kan/api typecheck/build and focused agent tests: 28/28
FAIL: targeted web ESLint currently reports apps/web/src/views/card/components/ActivityList.tsx:374 unused isAdmin
FAIL, known broader baseline: @kan/web typecheck still has existing bootstrap/workspace typing errors

Canary gate: current automated canary is not green for the draft stack; treat this as a review/checkpoint result, not merge approval.

Review notes:

Product blocker: proposal_required is semantically misleading because direct agent actions still apply and only return warnings. Choose one: enforce, require explicit override, or rename to proposal-preferred/proposal-warning.

## 3+3 Review Result Status: **NOT READY / OWNER CHECKPOINT** Review lanes completed: tech-ollama-1, tech-ollama-2, tech-codex, product-ollama-1, product-ollama-2, product-claude-opus. Deterministic checks on current stack tip: - PASS: `@kan/db` typecheck/build - PASS: `@kan/shared` typecheck/build - PASS: `@kan/mcp` typecheck/build - PASS: `@kan/api` typecheck/build and focused agent tests: 28/28 - FAIL: targeted web ESLint currently reports `apps/web/src/views/card/components/ActivityList.tsx:374` unused `isAdmin` - FAIL, known broader baseline: `@kan/web typecheck` still has existing bootstrap/workspace typing errors Canary gate: current automated canary is **not green** for the draft stack; treat this as a review/checkpoint result, not merge approval. Review notes: - Product blocker: proposal_required is semantically misleading because direct agent actions still apply and only return warnings. Choose one: enforce, require explicit override, or rename to proposal-preferred/proposal-warning.

codex referenced this pull request

2026-05-10 08:48:13 +02:00

feat(web): show blocked and policy board cues #38