Refine sm-flow trigger and scale rules
This commit is contained in:
aruo
@@ -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.
|
||||
+53
@@ -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-standard-change.
|
||||
@@ -0,0 +1 @@
|
||||
Committed OpenSpec for validate-sm-flow-standard-change.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Design
|
||||
|
||||
## Scale
|
||||
|
||||
Scale: `standard`.
|
||||
|
||||
Rationale: this validation has a clear target and no business-code risk, but it intentionally exercises the full normal artifact set rather than the reduced micro path.
|
||||
|
||||
## Interface Impact
|
||||
|
||||
Interface impact: L1 internal documentation/protocol validation.
|
||||
|
||||
No API, DTO, database, event, service, or cross-module runtime contract changes are expected.
|
||||
|
||||
## Artifact Model
|
||||
|
||||
Standard validation requires:
|
||||
|
||||
- OpenSpec: `proposal.md`, independent `design.md`, `specs/`, `tasks.md`.
|
||||
- Devflow archive: `brief.md`, `evidence.md`, `decisions.md`, `acceptance.md`.
|
||||
|
||||
The validation checks that current skill rules point to `references/scales.md` for the exact standard artifact requirements instead of redefining them elsewhere.
|
||||
|
||||
## Execution Design
|
||||
|
||||
1. Build the standard OpenSpec fixture.
|
||||
2. Run static scans for standard artifact wording and duplicated scale definitions.
|
||||
3. Run skill validation and reference integrity checks.
|
||||
4. Record evidence separately in `devflow/.../evidence.md`.
|
||||
5. Mark the fixture as committed only if artifact completeness and alignment pass.
|
||||
|
||||
## Risks
|
||||
|
||||
- The external OpenSpec archive/apply commands are not exposed in the current tool surface; this validation uses file-based checks.
|
||||
- File presence does not prove independent-agent usability; forward-testing remains a separate optional validation surface.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Validate SM Flow Standard Change
|
||||
|
||||
## Why
|
||||
|
||||
The previous validation covered a micro change. A standard change has stricter expectations: an independent `design.md`, complete OpenSpec artifacts, and a separate `evidence.md` in devflow.
|
||||
|
||||
This validation checks whether the current `sm-flow` skill can still describe and validate a normal standard change after the recent simplification work.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Create a standard-scale validation fixture for `sm-flow`.
|
||||
- Verify standard OpenSpec artifacts exist and are aligned: `proposal.md`, `design.md`, `specs/`, and `tasks.md`.
|
||||
- Verify standard devflow archive artifacts exist: `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md`.
|
||||
- Verify standard still uses the same four visible checkpoints and nine internal phases without exposing phase names as user commands.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- Standard-scale validation records.
|
||||
- Static checks over `.agents/skills/sm-flow`.
|
||||
- Narrow fixes to the skill if standard validation reveals inconsistency.
|
||||
|
||||
Out of scope:
|
||||
|
||||
- Business code changes.
|
||||
- Reworking archived historical changes.
|
||||
- Changing the current trigger policy.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This change does not test a complex migration, rollback, or cross-team interface change.
|
||||
- This change does not require independent browser/manual validation.
|
||||
- This change does not replace the micro validation already archived.
|
||||
|
||||
## Risks
|
||||
|
||||
- A standard validation fixture can become noise if left unarchived; status must be explicit.
|
||||
- If standard rules are only validated by file presence, semantic drift may still require future forward-testing.
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
# sm-flow Standard Change Spec
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Standard Change Has Full OpenSpec Artifacts
|
||||
|
||||
A standard `sm-flow` change SHALL have `proposal.md`, independent `design.md`, `specs/`, and `tasks.md`.
|
||||
|
||||
#### Scenario: Standard fixture is committed
|
||||
|
||||
- **Given** a change is classified as `standard`
|
||||
- **When** commit validation runs
|
||||
- **Then** `proposal.md`, `design.md`, at least one spec file, and `tasks.md` exist
|
||||
- **And** the artifacts are aligned from proposal to design to specs to tasks
|
||||
|
||||
### Requirement: Standard Archive Has Evidence
|
||||
|
||||
A standard `sm-flow` archive SHALL include `brief.md`, `evidence.md`, `decisions.md`, and `acceptance.md` in devflow.
|
||||
|
||||
#### Scenario: Standard fixture is archived or accepted
|
||||
|
||||
- **Given** a standard validation change has completed apply checks
|
||||
- **When** devflow records are written
|
||||
- **Then** `evidence.md` exists as a separate file
|
||||
- **And** it records the static and script validation evidence used for acceptance
|
||||
|
||||
### Requirement: Scale Definitions Remain Centralized
|
||||
|
||||
Standard-specific artifact requirements SHALL be defined by `references/scales.md`; other files may reference those requirements but not carry a competing full definition.
|
||||
|
||||
#### Scenario: Standard wording is scanned
|
||||
|
||||
- **Given** sm-flow references mention standard behavior
|
||||
- **When** scale definition phrases are scanned
|
||||
- **Then** complete standard definitions appear only in `references/scales.md`
|
||||
- **And** operational files defer to the current scale rather than hard-coding alternative standard rules
|
||||
@@ -0,0 +1,29 @@
|
||||
# Tasks
|
||||
|
||||
## 1. Standard OpenSpec Fixture
|
||||
|
||||
- [x] 1.1 Create `proposal.md`.
|
||||
- [x] 1.2 Create independent `design.md`.
|
||||
- [x] 1.3 Create at least one spec under `specs/`.
|
||||
- [x] 1.4 Create `tasks.md`.
|
||||
|
||||
## 2. Standard Validation
|
||||
|
||||
- [x] 2.1 Run scale duplication scan.
|
||||
- [x] 2.2 Run obsolete wording scan.
|
||||
- [x] 2.3 Run skill quick validation.
|
||||
- [x] 2.4 Run reference integrity scan.
|
||||
|
||||
## 3. Commit Gate
|
||||
|
||||
- [x] 3.1 Confirm OpenSpec artifact completeness.
|
||||
- [x] 3.2 Confirm proposal -> design -> specs -> tasks alignment.
|
||||
- [x] 3.3 Create `.committed`.
|
||||
|
||||
## 4. Devflow Records
|
||||
|
||||
- [x] 4.1 Create `brief.md`.
|
||||
- [x] 4.2 Create separate `evidence.md`.
|
||||
- [x] 4.3 Create `decisions.md`.
|
||||
- [x] 4.4 Create `acceptance.md`.
|
||||
- [x] 4.5 Update `devflow/index.md`.
|
||||
Reference in New Issue
Block a user