busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix

Browse Source
This commit is contained in:
busya
2026-06-05 15:01:34 +03:00
parent 50180aaa14
commit 4cef6af041
27 changed files with 13547 additions and 892 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
.opencode/command/speckit.plan.md
View File

@@ -116,6 +116,21 @@ Validate the proposed design against `ux_reference.md` as an **interaction refer
If the planned architecture degrades the promised interaction model, deterministic recovery path, or context-budget behavior, stop and warn the user.
### Attention Compliance Gate (MANDATORY — before generating contracts)
Every contract in `contracts/modules.md` MUST pass these checks. Contracts that fail are invisible to the model after context compression (per `semantics-core` §VIII):
| Rule | Check | Failure Consequence |
|------|-------|---------------------|
| **ATTN_1** | First anchor line: `#region Domain.Sub.Name [C:N] [TYPE Type] [SEMANTICS tag1,tag2]` — all on ONE line | CSA 4× pooling loses detail from multi-line anchors |
| **ATTN_2** | IDs are hierarchical: `Core.Auth.Login`, not `login_handler` | HCA 128× makes flat IDs indistinguishable from noise |
| **ATTN_3** | All contracts in a domain share primary `@SEMANTICS` keyword (e.g., all auth contracts use `[SEMANTICS auth, ...]`) | DSA Lightning Indexer fails to group domain contracts |
| **ATTN_4** | Contract ≤150 lines, module ≤400 lines | Contracts exceeding the sliding window are partially invisible |
**Cross-stack compliance (fullstack features only):**
- Backend Pydantic schema contract and frontend TypeScript DTO contract MUST have matching `@RELATION` edges crossing the stack boundary.
- Both MUST share at least one `@SEMANTICS` keyword so the DSA Indexer can link them.
### Data Model Output
Generate `data-model.md` for ss-tools domain entities such as:
@@ -143,7 +158,7 @@ Before task decomposition, planning must identify any repo-shaping decisions thi
### Contract Design Output
Generate `contracts/modules.md` as the primary design contract for implementation. Contracts must:
- use short semantic IDs (e.g., `MigrationModel`, `GitManager`, `DashboardApi`)
- use short hierarchical semantic IDs with 2-3 levels: `Domain.Name` (e.g., `Core.Auth.Login`, `Api.Dashboards`, `Users.ListModel`, `Test.Migration.RunTask`). NOT flat IDs like `login_handler` or `UserListModel`.
- classify each planned module/component/model with `[C:N]` complexity in the `#region` anchor (NOT `@COMPLEXITY N`)
- use canonical anchor syntax: `#region Id [C:N] [TYPE TypeName] [SEMANTICS tags]` / `#endregion Id`
- use canonical relation syntax `@RELATION PREDICATE -> TARGET_ID`
@@ -157,6 +172,63 @@ Complexity guidance for this repository:
- **C4**: typically adds `@PRE`, `@POST`, `@SIDE_EFFECT`; **Screen Models** also `@STATE`, `@ACTION`, `@INVARIANT`; orchestration paths should account for belief runtime markers
- **C5**: C4 + `@DATA_CONTRACT`, `@INVARIANT`, and explicit decision-memory continuity (`@RATIONALE`/`@REJECTED`)
### Function-Level Contracts for C3+ (MANDATORY for cross-stack and orchestration)
For every C3+ function, method, or Screen Model action that is:
- An API endpoint (FastAPI route handler)
- A Screen Model action with `@SIDE_EFFECT`
- A C4/C5 orchestration function (migration runner, task executor, auth flow)
Generate its full `#region` header in `contracts/modules.md` under its parent module. This header becomes the implementation contract that the coding agent MUST satisfy.
**Minimal header for C3 API endpoints:**
```
#region Domain.Resource.Action [C:3] [TYPE Function] [SEMANTICS domain,action]
@BRIEF One-line purpose.
@RELATION DEPENDS_ON -> [DependencyService]
@RELATION DEPENDS_ON -> [DTO:RequestSchema]
```
**Full header for C4/C5 orchestration & cross-stack functions:**
```
#region Domain.Resource.Action [C:4] [TYPE Function] [SEMANTICS domain,action]
@BRIEF One-line purpose.
@PRE Precondition 1 (verifiable by guard clause).
@PRE Precondition 2.
@POST Output guarantee 1 (testable assertion).
@POST Output guarantee 2.
@SIDE_EFFECT State mutation, I/O, or external call.
@SIDE_EFFECT Logging (REASON/REFLECT/EXPLORE markers required).
@RELATION DEPENDS_ON -> [ServiceDependency]
@RELATION DEPENDS_ON -> [DTO:InputSchema]
@DATA_CONTRACT InputDTO -> OutputDTO
@RATIONALE Why this implementation approach.
@REJECTED What alternative was considered and forbidden.
@TEST_EDGE: scenario_name -> Expected failure behavior.
@TEST_EDGE: scenario_name -> Expected failure behavior.
```
**Screen Model actions (Svelte `.svelte.ts`):**
```
// #region ScreenModel.actionName [C:4] [TYPE Function] [SEMANTICS domain,action]
// @BRIEF What this action does.
// @ACTION Public action — callable from components.
// @PRE Guards before execution.
// @POST State guarantees after completion.
// @SIDE_EFFECT API call, store mutation, model state update.
// @RELATION CALLS -> [apiClient]
// @TEST_EDGE: network_failure -> ScreenState = "error"
```
**Rules:**
- Function contract headers are **NOT implementation** — they are design contracts. The coding agent implements the body.
- C1/C2 functions do NOT need pre-generated contracts — only C3+.
- `@TEST_EDGE` declarations enable qa-tester to write tests BEFORE implementation (true TDD).
- `@DATA_CONTRACT` on API endpoints enables fullstack-coder to align frontend TypeScript DTOs.
- `@SIDE_EFFECT` with belief runtime markers ensures molecular CoT logging is wired from day one.
- Cross-stack functions MUST have matching `@DATA_CONTRACT` on both backend and frontend sides.
- All contracts MUST pass the Attention Compliance Gate (ATTN_1-4) above.
If a planned contract depends on unknown schema, relation target, or ADR identity, emit `[NEED_CONTEXT: target]` instead of fabricating placeholders.
### Quickstart Output