microsoft / microsoft/hve-core
docs: update security agent-overview.md for new state fields and phase gates
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Component
Documentation
## Bug Description
PR #1642 (commit `f4f6b3c`) added several new fields to the Security Planner state schema and introduced differentiated phase gates, but `docs/agents/security/agent-overview.md` has not been updated to reflect these changes.
**Missing state fields in the State Fields table:**
- `disclaimerShownAt` — ISO 8601 timestamp recording when the startup disclaimer was shown
- `phaseGates` — object tracking gate type (`hard` vs `summary-and-advance`) and confirmation timestamps for each phase
- `raiRecommendationShown` — boolean distinguishing between showing the RAI recommendation and actually dispatching the RAI Planner
- `signingRequested` — boolean recording whether artifact signing was requested
- `signingManifestPath` — path to the generated signing manifest
The doc also states _"over 16 fields"_ which is now a significant undercount.
**Interaction Model — phase gate nuance not documented:**
The Interaction Model table contains a guardrail _"No phase advance without confirmation"_ that implies all phase transitions require explicit user confirmation. The implementation now uses differentiated gates: phases 1, 4, and 6 are **hard gates** (explicit confirmation required and timestamp recorded), while phases 2, 3, and 5 are **summary-and-advance** gates (agent summarizes and advances automatically). This distinction is defined in `identity.instructions.md` and the `security-planner.agent.md` state schema but is absent from the documentation.
## Expected Behavior
After the update, `docs/agents/security/agent-overview.md` should:
- Include `disclaimerShownAt`, `phaseGates`, `raiRecommendationShown`, `signingRequested`, and `signingManifestPath` in the State Fields table with accurate type and description columns.
- Update the field count description from _"over 16 fields"_ to reflect the actual count.
- Add a row or note to the Interaction Model table distinguishing hard gates (phases 1, 4, 6) from summary-and-advance gates (phases 2, 3, 5).
## Steps to Reproduce
Triggered by commit `f4f6b3c52bc760bfc7b76f428f6980d549836224` (PR #1642 — `feat(agents): security-planner SSSC parity`).
Changes to review:
- `.github/agents/security/security-planner.agent.md` (state schema section)
- `.github/instructions/security/identity.instructions.md` (State Schema and Phase Gate sections)
## Additional Context
- Documentation file: `docs/agents/security/agent-overview.md` — State Management and Interaction Model sections
- Code files: `.github/agents/security/security-planner.agent.md`, `.github/instructions/security/identity.instructions.md`
> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/27178131000) · sonnet46 1.7M · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)
Contributor guide
Research direction
Read .github/agents/security/security-planner.agent.md and .github/instructions/security/identity.instructions.md, focusing on the State Schema and Phase Gate sections. Update docs/agents/security/agent-overview.md in its State Management and Interaction Model sections. Done means all five fields have accurate types and descriptions, the field count is corrected, and hard versus summary-and-advance gates are documented.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100