Refine sm-flow trigger and scale rules

2026-07-05 14:30:15 +08:00
parent 433f7a93a4
commit e4f6e013a5
28 changed files with 937 additions and 105 deletions
@@ -0,0 +1 @@
+Devflow archive files are ready for validate-sm-flow-explicit-trigger.
@@ -0,0 +1 @@
+Committed OpenSpec for validate-sm-flow-explicit-trigger.
@@ -0,0 +1,44 @@
+# Validate SM Flow Explicit Trigger
+
+## Why
+
+Recent edits simplified `sm-flow` so it should only run when the user explicitly invokes it. The same cleanup also centralized scale rules in `references/scales.md`, removed time-based metrics, and split fallback/glossary concepts out of the top-level skill.
+
+This change validates those protocol decisions through a real micro `sm-flow` run instead of another informal review.
+
+## What Changes
+
+- Verify `sm-flow` only triggers on `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or an explicit natural-language request to use sm-flow.
+- Verify task type alone does not trigger `sm-flow`, even when the task mentions OpenSpec, devflow, cross-module work, or clarification.
+- Verify `micro / standard / complex` definitions live only in `references/scales.md`.
+- Verify the skill has no time/minute-based metrics.
+- Verify fallback usage is recorded when external OpenSpec capabilities are unavailable.
+
+## Design Notes
+
+- Scale: `micro`.
+- Interface impact: L1 internal documentation/protocol validation only.
+- No business code changes.
+- Independent `design.md` is intentionally omitted; this section is the micro design artifact.
+- OpenSpec CLI and external OpenSpec child skills are not directly callable in the current tool surface, so this run uses `references/fallbacks.md` and records that capability source in devflow.
+
+## Scope
+
+In scope:
+
+- `.agents/skills/sm-flow/SKILL.md`
+- `.agents/skills/sm-flow/references/*.md`
+- Validation OpenSpec and devflow records for this change
+
+Out of scope:
+
+- Business code
+- Rewriting historical OpenSpec archives
+- Changing the four visible checkpoints or nine internal phases
+- Adding automatic trigger heuristics
+
+## Risks
+
+- A future edit may duplicate scale rules outside `references/scales.md`.
+- The frontmatter description may drift from the top-level trigger rule.
+- Validation can prove current text consistency, but cannot force future agents to obey it without continued review.
@@ -0,0 +1,53 @@
+# sm-flow Explicit Trigger Spec
+
+## ADDED Requirements
+
+### Requirement: Explicit Trigger Only
+
+`sm-flow` SHALL be used only when the user explicitly invokes `/sm-flow`, `/sm-flow explore`, `/sm-flow apply`, `/sm-flow archive`, or clearly asks to use the sm-flow process in natural language.
+
+#### Scenario: Plain engineering request
+
+- **Given** a user asks for an engineering task that mentions OpenSpec, devflow, cross-module work, or clarification
+- **When** the user does not explicitly request sm-flow
+- **Then** the agent handles the task as ordinary engineering work
+- **And** the agent does not auto-trigger sm-flow based on task type
+
+#### Scenario: Explicit sm-flow request
+
+- **Given** a user invokes `/sm-flow` or clearly asks to use sm-flow
+- **When** the agent starts the process
+- **Then** the agent follows the visible checkpoints Discover, Commit, Apply, and Archive
+- **And** the internal phase order remains clarify, context, propose, grill, specify, audit, commit, apply, archive
+
+### Requirement: Scale Rules Have One Source
+
+The `micro / standard / complex` scale definitions SHALL be defined in `references/scales.md`; other files may only reference that file instead of redefining scale details.
+
+#### Scenario: Scale guidance is needed
+
+- **Given** a phase needs to choose or enforce a scale
+- **When** the rule is read
+- **Then** it points to `references/scales.md`
+- **And** no other reference file carries a competing full definition of the three scales
+
+### Requirement: No Time-Based Skill Metrics
+
+The skill SHALL NOT use minute, hour, second, or timebox metrics to define scale, effort, or validation thresholds.
+
+#### Scenario: Protocol text is scanned
+
+- **Given** the sm-flow skill files are scanned
+- **When** obsolete time metrics are searched
+- **Then** no matching scale or effort rule remains
+
+### Requirement: Fallback Capability Is Explicit
+
+When OpenSpec CLI or child skill capabilities are unavailable, `sm-flow` SHALL use `references/fallbacks.md` only as an explicit fallback and record the capability source in the current devflow process log.
+
+#### Scenario: External capability unavailable
+
+- **Given** OpenSpec child skills are not directly callable
+- **When** a change is still executed
+- **Then** the decisions log records fallback source, impact, and remaining risk
+- **And** the fallback does not skip context, grill, commit, apply, or archive gates
@@ -0,0 +1,26 @@
+# Tasks
+
+## 1. Discover
+
+- [x] 1.1 Read current `sm-flow` top-level trigger rule and relevant references.
+- [x] 1.2 Read `devflow/index.md` and glossary context for related history.
+- [x] 1.3 Classify this validation as `micro` and record capability fallback.
+
+## 2. Commit
+
+- [x] 2.1 Create micro OpenSpec proposal with inline design notes.
+- [x] 2.2 Create specs that express the observable validation expectations.
+- [x] 2.3 Create executable validation tasks.
+- [x] 2.4 Run cross-artifact alignment and create `.committed`.
+
+## 3. Apply
+
+- [x] 3.1 Scan `sm-flow` files for obsolete trigger, scale, time metric, and fallback wording.
+- [x] 3.2 Patch any discovered inconsistency in the skill files.
+- [x] 3.3 Run skill validation and reference integrity checks.
+
+## 4. Archive
+
+- [x] 4.1 Create micro devflow archive files.
+- [x] 4.2 Update `devflow/index.md`.
+- [x] 4.3 Create `.archive-ready` and ask whether to archive OpenSpec.
				`@@ -0,0 +1 @@`
				`Devflow archive files are ready for validate-sm-flow-explicit-trigger.`
				`@@ -0,0 +1 @@`
				`Committed OpenSpec for validate-sm-flow-explicit-trigger.`