fix(cli): (1) Author docs/policies.md as a feature guide sourced fr... (#1581)

[aidandaly24]

Refs aws#1581

Issues

• docs: write docs/policies.md (Cedar policy engine + Bedrock guardrails) aws/agentcore-cli#1581 — The Policies & Guardrails feature (add policy-engine / add policy, Cedar engines, the form-based guardrail builder, content filters, prompt-attack and sensitive-info detection) ships fully working but has no dedicated user guide. README.md:191 lists the commands in a table yet, unlike payments/gateway/memory/knowledge-bases, links to no docs/policies.md. Separately, the vended AGENTS.md that every created project carries documents a PolicyEnforcementMode value PASSIVE that does not exist in the schema, so AI assistants and users are misled about valid enforcement modes.

Root cause

Verified by reading docs/policies/ (only IAM jsons), src/cli/tui/screens/policy/types.ts, src/schema/schemas/primitives/policy.ts:53, src/schema/schemas/mcp.ts:1043, README.md:191/211/234, docs/commands.md:645-710, src/assets/agents/AGENTS.md:84, CDKRenderer.ts:54-113, and git log aws#1577. Could not check GitHub for an open PR from this sandbox, but no local branch/ref adds docs/policies.md.

The fix

(1) Author docs/policies.md as a feature guide sourced from code, not the issue body: Cedar policy engines and add policy-engine flags incl. --attach-to-gateways/--attach-mode LOG_ONLY|ENFORCE (docs/commands.md:645); the four add policy source methods from POLICY_SOURCE_METHOD_OPTIONS (form/file/inline/generate, types.ts:238); the form-based guardrail builder's three categories from GUARDRAIL_CATEGORY_OPTIONS (types.ts:58) — contentFilter VIOLENCE|HATE|SEXUAL|MISCONDUCT|INSULTS (spell INSULTS, the aws#1571 regression guard at tests/types.test.ts:15-18), promptAttack JAILBREAK|PROMPT_INJECTION|PROMPT_LEAKAGE, sensitiveInformation (30 entity types types.ts:21-53); policy effects permit/forbid/suppressOutput with INITIATE vs RETURN_OUTPUT phase semantics (types.ts:103-135); enforcement modes ACTIVE|LOG_ONLY (NOT PASSIVE); validation modes FAIL_ON_ANY_FINDINGS|IGNORE_ALL_FINDINGS. (2) Add See [Policies & Guardrails](docs/policies.md) under README.md:191 and an entry in the README docs index (README.md:307-312) to match the payments/gateway pattern. (3) Resolve the brief's open design question with a definitive YES: fix the shipped PASSIVE defect at src/assets/agents/AGENTS.md:84 to 'ACTIVE' | 'LOG_ONLY' and run npm run test:update-snapshots (updates assets.snapshot.test.ts.snap:7176). This is a real shipped wrong value in a vended asset, not just an issue-body wording slip.

Files touched: New file docs/policies.md and README.md:191 + docs index README.md:307-312 (CLI repo /local/home/aidandal/workplace/issues/agentcore-cli). Content sourced from src/cli/tui/screens/policy/types.ts and docs/commands.md:645-710. Plus correct the vended asset src/assets/agents/AGENTS.md:84 (ACTIVE|PASSIVE -> ACTIVE|LOG_ONLY) and regenerate src/assets/tests/snapshots/assets.snapshot.test.ts.snap. No runtime code change required.

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

BEFORE (base HEAD): docs/policies.md absent; README had no "See [Policies & Guardrails]" link under its section nor a Policies docs-index entry; src/assets/agents/AGENTS.md:84 and snapshot read PolicyEnforcementMode: 'ACTIVE' | 'PASSIVE' — but schema src/schema/schemas/primitives/policy.ts:53 is z.enum(['ACTIVE','LOG_ONLY']), so PASSIVE is invalid (grep PASSIVE src/ matched at line 84). AFTER (branch fix/1581, built OK -> dist/cli/index.mjs): docs/policies.md exists, every claim sourced from code — Cedar engines + --attach-to-gateways/--attach-mode LOG_ONLY|ENFORCE (matches docs/commands.md:654-664); four source methods from POLICY_SOURCE_METHOD_OPTIONS (form/file/inline/generate); three guardrail categories from GUARDRAIL_CATEGORY_OPTIONS — contentFilter VIOLENCE|HATE|SEXUAL|MISCONDUCT|INSULTS (plural, matching CONTENT_FILTER_FILTERS and the aws#1571 guard), promptAttack JAILBREAK|PROMPT_INJECTION|PROMPT_LEAKAGE, sensitiveInformation; effects permit/forbid/suppressOutput with INITIATE vs RETURN_OUTPUT (matches POLICY_EFFECT_OPTIONS/authorizationPhaseForEffect); enforcement ACTIVE|LOG_ONLY; validation FAIL_ON_ANY_FINDINGS|IGNORE_ALL_FINDINGS. README.md:195 has the See-Policies line and the docs-index gained the Policies entry. AGENTS.md:84 and snapshot:7170 now read 'ACTIVE' | 'LOG_ONLY'; grep confirms NO PASSIVE anywhere under src/ or dist/. Tests: assets snapshot suite 126/126 pass (incl. agents/AGENTS.md snapshot); policy suite 21/21 pass incl. the aws#1571 INSULTS regression

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.16%	13594 / 36577
🔵	Statements	36.43%	14454 / 39667
🔵	Functions	31.82%	2335 / 7336
🔵	Branches	31.1%	9000 / 28932

Generated in workflow #113 for commit dc5e3c9 by the Vitest Coverage Report Action