fix(agent-context): support multiple context files safely

[AustinZ21]

Summary

This PR lets the bundled agent-context extension manage more than one coding-agent context file from the same Spec Kit run.

The motivating workflow is a repo that uses Claude Code and Codex interchangeably and wants Spec Kit's generated context block synced to both CLAUDE.md and AGENTS.md. The implementation keeps the existing singular context_file behavior, while adding an optional context_files list for projects that intentionally keep multiple agent anchors in sync.

What Changed

• Added optional context_files support to the agent-context config template.
• Updated the bash and PowerShell update scripts to refresh every configured context file.
• Updated Python integration setup/removal paths to upsert and remove the managed block across configured files.
• Rendered command templates with a readable multi-file context target when context_files is configured.
• Preserved existing non-empty context_files during integration switches.
• Added project-root containment validation for context file paths:
  • rejects absolute paths
  • rejects Windows drive paths
  • rejects backslash separators
  • rejects .. path segments
  • confirms the resolved target stays inside the project root
• Kept specify extension disable agent-context as a full opt-out: disabled projects skip upsert/removal and ignore stale context_files during command rendering.
• Updated agent-context docs and command help to describe multi-file configuration and safety behavior.

Why

Today Spec Kit stores one managed context block target in context_file. That works well for a single coding agent, but mixed-agent projects can need more than one context anchor. For example, Codex reads AGENTS.md, while Claude-oriented setups often use CLAUDE.md. Without first-class multi-file support, teams have to choose one anchor or maintain duplicate context manually.

This change makes the multi-agent case explicit and configurable without hard-coding any specific agent names or file paths.

Safety Notes

The script and Python integration paths now enforce matching path constraints so a configured context file cannot escape the project root. The disabled-extension path also avoids validating stale config before the opt-out gate, so disabling agent-context remains a complete opt-out even if old config contains invalid paths.

Validation

• bash -n extensions/agent-context/scripts/bash/update-agent-context.sh
• python -m compileall -q src\specify_cli
• pytest tests/extensions/test_extension_agent_context.py -q
  • 50 passed
• pytest tests/integrations/test_integration_codex.py::TestCodexInitFlow::test_plan_skill_references_configured_context_files tests/integrations/test_integration_codex.py::TestCodexInitFlow::test_plan_skill_ignores_context_files_when_agent_context_disabled -q
  • 2 passed
• pytest tests/test_agent_config_consistency.py -q
  • 28 passed
• specify --help
• Manual PowerShell smoke test:
  • configured context_files: [AGENTS.md, CLAUDE.md]
  • ran update-agent-context.ps1 specs/123-test/plan.md
  • verified both files were updated
• Manual bash smoke test:
  • configured context_files: [AGENTS.md, CLAUDE.md]
  • ran update-agent-context.sh specs/123-test/plan.md
  • verified both files were updated

Known Existing Test Failure

The broader Codex integration slice still has two inventory failures:

• TestCodexIntegration.test_complete_file_inventory_sh
• TestCodexIntegration.test_complete_file_inventory_ps

Both failures reproduce on a clean upstream/main worktree at 1b0556c, before this PR's changes. They expect bundled agent-context extension artifacts in the generated project, but the generated project does not include them. The focused tests added by this PR pass.

AI Assistance Disclosure

I used Codex/ChatGPT to inspect the integration paths, draft the implementation, and generate test coverage. I reviewed the code paths and validated the behavior locally with automated and manual checks.