microsoft / microsoft/hve-core

feat: Add project lifecycle phase awareness to Security Planner (MVE / MVP / Beta)

Open
#1,591 1 comment 0 reactions 1 assignee Claimed by @WilliamBerryiii View on GitHub
needs-triage security
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Background

The Security Planner currently applies identical analysis depth, standards scope, and backlog generation to every project **regardless** of where it sits in the product lifecycle. A two-week MVE proof-of-concept receives the same treatment as a production system approaching GA which if not careful, will produce backlog noise.

**This following was observed directly**:

- The Security Planner was run against a greenfield project in an **MVE (Minimal Viable Experiment)** phase where MVP was explicitly out of scope. The agent produced a full-depth security plan with production-weight controls, creating significant analysis overhead for a disposable, hypothesis-driven experiment.

**Further justifications**:

- MVE artifacts are also **stale-by-construction** for later phases: MVP and Beta teams will work against different components, data flows, and trust boundaries, so any forward-looking stories generated during an MVE run would be wrong in subtle ways and create false confidence that "security is already planned." ~This is the primary reason the design defers MVP-phase analysis to a later Security Planner re-run rather than emitting speculative MVP backlog items.~

- The only **currently existing conditional behavior** in the agent is _AI Component Detection,_ which
sets `raiEnabled`, `raiScope`, and `raiTier` based on described system characteristics.

- Research confirmed that **no existing Phase 1 question reliably surfaces lifecycle phase.**
Proxy signals (compliance requirements, deployment model, PRD presence) are all unreliable
for MVE detection. Explicit discovery is required.

**Selected design**:

- Lightweight Conversation Change - one natural conversational Phase 1 question discovers project stage and maps free-text to a `projectPhase` enum (`mve | mvp | beta`). The field is stored in `state.json` with a `"mvp"` default for full backward compatibility. Phase 2–5 analysis depth and Phase 6 handoff advisory adapt based on this value.

Framework precedent: LINDDUN explicitly models three analysis depths (GO / PRO / MAESTRO)
that map directly to this three-tier lifecycle model. OWASP Let's Threat Model (Oct 2025)
also targets early-stage projects with a `categorize_only` lightweight mode.

---

## Required Changes

### 1. `.cspell.json`

Add `mve` and `mvp` (lowercase) to the `words` array. All-caps `MVE`/`MVP` already pass cspell; lowercase enum values in JSON code blocks within instruction files require explicit dictionary entries.

### 2. `.github/agents/security/security-planner.agent.md`

- Add `projectPhase` to the `state.json` schema block (after `aiComponents`):
```json
"projectPhase": "string (mve|mvp|beta), default: mvp"
```
- Extend the Phase 1 Scoping description to reference Project Stage Discovery logic and
note that Phase 2–5 behavior adapts based on `projectPhase`.

### 3. `.github/instructions/security/identity.instructions.md`

- Add `projectPhase` to the `### State Schema` JSON block (after `aiComponents`).
- Add `projectPhase` default (`"mvp"`) to the `### State Creation` bullet list.
- Add a new `#### Project Stage Discovery` subsection under Phase 1, including:
- One stage-discovery question
- Free-text-to-enum mapping rules for all three values (`mve`, `mvp`, `beta`)
- One ambiguity follow-up question
- An MVE scoping advisory message to display when `projectPhase` resolves to `"mve"`
- Add a new `#### MVE Phase-Transition Advisory` block to Phase 6 (Review and Handoff),
conditional on `projectPhase == "mve"`, that directs users to re-run Security Planner
at MVP because MVE-phase analysis is stale-by-construction once architecture, components,
and trust boundaries change at MVP then updates `nextActions` accordingly.

### 4. `.github/instructions/security/operational-buckets.instructions.md`

Append a new `## Project Phase Scoping` section with:
- **MVE**: Ask which buckets are hypothesis-critical; skip and mark ❌ all others.
- **Beta**: Full coverage; explicitly document existing controls and their implementation
status per bucket to support pre-GA gap analysis.

### 5. `.github/instructions/security/standards-mapping.instructions.md`

Append a new `## Project Phase Scoping` section with:
- **MVE**: Map only hard-blocker controls (A01:2025, A02:2025, A03:2025 minimum); skip
lower-priority OWASP items, NIST 800-53, and CIS Benchmarks unless directly relevant;
note that full coverage is deferred to MVP.
- **Beta**: Full OWASP/NIST baseline plus compliance-specific escalation (PCI-DSS, HIPAA,
SOC 2) when Phase 1 discovered compliance requirements; produce a "Pre-GA Standards Gaps"
section.

### 6. `.github/instructions/security/security-model.instructions.md`

Append a new `## Project Phase Scoping` section with:
- **MVE**: Restrict STRIDE to critical paths only; accept ❓ uncertainty without blocking;
skip threat ID generation for buckets marked out of MVE scope; add plan note that full
coverage is deferred.
- **Beta**: Full STRIDE analysis plus incident response surface review; flag `[IR-GAP]`
threats for each Critical/High item missing a detection/containment/recovery path.

### 7. `.github/instructions/security/backlog-handoff.instructions.md`

Append a new `## Project Phase Scoping` section with:
- **MVE**: Include Critical and High risk items only; override `autonomyTier` to `"manual"`;
prepend an advisory to the backlog output; add `phase:mve` tag to all generated items so
downstream consumers know these items are scoped to the MVE and do not carry forward
unchanged into MVP or Beta backlogs.
- **Beta**: Full item set; add a "Pre-GA Security Controls" category for GA-gate blockers
and gaps; tag with `phase:pre-ga`.

### 8. Plugin Regeneration

Run `npm run plugin:generate` after all instruction and agent file changes to regenerate
outputs under `plugins/`. No changes to `security.collection.yml` are required because all
modified files are already referenced.

---

## Acceptance Criteria

- [ ] `projectPhase` field (`mve | mvp | beta`, default `"mvp"`) is present in the `state.json` schema in both `security-planner.agent.md` and `identity.instructions.md` with identical definitions.
- [ ] `identity.instructions.md` State Creation block initializes `projectPhase` to `"mvp"` for new sessions.
- [ ] Exactly one Phase 1 stage-discovery question is present in `identity.instructions.md` with mapping guidance covering all three enum values and one ambiguity follow-up.
- [ ] When `projectPhase` resolves to `"mve"`, the agent displays a scoping advisory before proceeding to Phase 2.
- [ ] `operational-buckets.instructions.md` contains MVE hypothesis-critical bucket guidance and Beta existing-controls documentation guidance.
- [ ] `standards-mapping.instructions.md` contains MVE hard-blocker-only guidance (A01/A02/A03 named explicitly) and Beta compliance escalation guidance.
- [ ] `security-model.instructions.md` contains MVE critical-path-only STRIDE guidance (with ❓ acceptance) and Beta incident response surface guidance.
- [ ] `backlog-handoff.instructions.md` contains: MVE Critical/High filter, `manual` autonomy override, advisory text, and `phase:mve` tag; Beta "Pre-GA Security Controls" category with trigger conditions.
- [ ] Phase 6 handoff in `identity.instructions.md` includes an MVE phase-transition advisory (conditional on `projectPhase == "mve"`) that directs users to re-run Security Planner at MVP.
- [ ] Sessions without `projectPhase` in `state.json` (all existing sessions) fall back gracefully to `"mvp"` behavior without errors or warnings.
- [ ] `mve` and `mvp` (lowercase) are added to `.cspell.json` `words` array.
- [ ] All new instruction content uses RFC 2119 language (`MUST`/`SHOULD`/`MAY`) consistent with existing file conventions.
- [ ] `npm run spell-check` passes with no new failures.
- [ ] `npm run lint:all` passes with no new failures.
- [ ] `npm run plugin:generate` completes successfully with updated outputs under `plugins/security/`.
- [ ] `npm run plugin:validate` passes.

---

## Dependencies

- No collection YAML changes required because `security.collection.yml` already references all files targeted by this change.
- No changes to RAI Planner or SSSC Planner are in scope.
- `npm` and Node.js must be available for validation commands.

---

## References

- LINDDUN three-flavor model (GO / PRO / MAESTRO): https://linddun.org/whyuselinddun/
- OWASP Let's Threat Model (early-stage focus, `categorize_only` mode): https://github.com/OWASP/www-project-lets-threat-model
- Threat Modeling Manifesto (continuous refinement principle): https://www.threatmodelingmanifesto.org/
- Architectural precedent: `raiEnabled`/`raiScope`/`raiTier` conditional field population in `.github/instructions/security/identity.instructions.md`

### Additional Context

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.