microsoft / microsoft/hve-core

docs: update security agent-overview.md for new state fields and phase gates

Open Beginner friendly
#1,877 0 comments 0 reactions 0 assignees View on GitHub
documentation needs-triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.