harden and streamline sm-flow protocol

2026-05-25 11:44:20 +08:00
parent 54741dd6c0
commit 1f01e30c4e
20 changed files with 1102 additions and 88 deletions
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Phase 1.5 checks cross-artifact alignment explicitly
+
+SM Flow SHALL explicitly check alignment across requirement, design, specification, and execution artifacts during Phase 1.5.
+
+#### Scenario: Alignment check runs
+
+- **WHEN** Phase 1.5 reviews the current Draft OpenSpec
+- **THEN** it checks that `brief/prd` aligns with `proposal`, `proposal` aligns with `design`, `design` aligns with `specs`, and `specs` align with `tasks`
+
+#### Scenario: Alignment gap is found
+
+- **WHEN** an expected behavior, term, field, constraint, or implementation slice appears in one artifact but not its downstream artifact
+- **THEN** the flow marks the gap explicitly and repairs OpenSpec before entering the next phase
+
+### Requirement: Phase 2.9 validates cross-artifact closure
+
+SM Flow SHALL re-check cross-artifact closure during Phase 2.9 before implementation.
+
+#### Scenario: Commit gate runs
+
+- **WHEN** Phase 2.9 evaluates whether Draft OpenSpec can become Committed OpenSpec
+- **THEN** it verifies that `evidence.md` and `decisions.md` findings that affect implementation are reflected in proposal, design, specs, or tasks
+
+#### Scenario: User review would otherwise catch the gap
+
+- **WHEN** a field, scope item, acceptance behavior, or design constraint is missing from the downstream OpenSpec artifacts
+- **THEN** the flow SHALL fail the commit gate and return to the earlier phase that owns the missing update
@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Micro mode compresses artifacts but preserves critical gates
+
+SM Flow SHALL allow `micro` mode to reduce artifact weight without skipping critical gates.
+
+#### Scenario: Micro mode starts
+
+- **WHEN** a change is classified as `micro`
+- **THEN** the flow may merge or simplify devflow artifacts
+- **AND** it SHALL still perform Phase 0.5 minimum context harvest, Phase 2 minimum clarification, Phase 2.9 commit gate, and Phase 4 lightweight backfill
+
+#### Scenario: Micro mode is treated as skip permission
+
+- **WHEN** the agent attempts to skip a critical gate because the change is small or low-risk
+- **THEN** the flow SHALL treat that as a protocol deviation rather than a valid micro-mode optimization
+
+### Requirement: Devflow updates happen during the flow
+
+SM Flow SHALL update devflow artifacts during the relevant phases rather than deferring all updates to Phase 4.
+
+#### Scenario: Phase-local information is produced
+
+- **WHEN** a phase produces entry summary, evidence, decisions, architecture findings, or commit-gate conclusions
+- **THEN** the corresponding devflow artifact is updated in or near that phase
+
+#### Scenario: Phase 4 begins
+
+- **WHEN** the flow enters Phase 4
+- **THEN** devflow backfill is primarily a consolidation step rather than the first time those records are written
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Each critical phase has an explicit checkpoint
+
+SM Flow SHALL require an explicit checkpoint before a critical phase can be considered complete.
+
+#### Scenario: Phase completes normally
+
+- **WHEN** the agent finishes a critical phase such as Phase 0, Phase 0.5, Phase 1, Phase 2, Phase 2.5, or Phase 2.9
+- **THEN** it reports the current phase, the capability source used, the produced artifacts, the satisfied exit conditions, and any unresolved blockers
+
+#### Scenario: Checkpoint is missing
+
+- **WHEN** a critical phase has produced artifacts or conclusions but no explicit checkpoint summary
+- **THEN** the phase SHALL NOT be treated as complete for purposes of entering the next phase
+
+### Requirement: Capability declaration is part of phase completion
+
+SM Flow SHALL treat skill or fallback declaration as part of the phase completion condition.
+
+#### Scenario: Native skill or local protocol is used
+
+- **WHEN** a phase depends on a named capability such as `openspec-propose`, `grill-with-docs`, `zoom-out`, or `openspec-apply-change`
+- **THEN** the agent states whether it used a native skill, a local `SKILL.md`, or a fallback protocol
+
+#### Scenario: Fallback is used
+
+- **WHEN** a phase falls back from a named capability
+- **THEN** the agent records the target capability, the reason it was unavailable, the fallback protocol name, and the downgrade risk
+
+#### Scenario: Declaration is omitted
+
+- **WHEN** no capability source is declared for a phase that requires one
+- **THEN** that phase SHALL NOT be considered complete
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Phase 2 builds a question pool before interviewing
+
+SM Flow SHALL build a Phase 2 question pool before consuming `user-interview` questions one at a time.
+
+#### Scenario: Phase 2 starts
+
+- **WHEN** the flow enters Phase 2
+- **THEN** it defines a question pool that covers at least terminology, scope boundaries, and acceptance
+
+#### Scenario: Complex change needs deeper coverage
+
+- **WHEN** the change affects multiple modules, interfaces, permissions, downstream consumers, response structures, or lifecycle rules
+- **THEN** the Phase 2 question pool also includes those dimensions before user-interview consumption begins
+
+### Requirement: User-interview questions remain one-at-a-time
+
+SM Flow SHALL preserve the one-question-at-a-time rule while using a question pool.
+
+#### Scenario: User-interview question is asked
+
+- **WHEN** the next unresolved `user-interview` item is selected from the question pool
+- **THEN** the flow asks exactly one question, waits for the explicit user answer, records the result, and only then advances to the next `user-interview` item
+
+#### Scenario: Question pool exists but answer is missing
+
+- **WHEN** there are remaining question-pool items and the current `user-interview` question is unanswered
+- **THEN** the flow SHALL NOT ask another `user-interview` question until the current one is resolved