fix
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -32,6 +32,7 @@ The feature description is the text passed to `/speckit.specify`.
|
||||
- `.specify/templates/spec-template.md`
|
||||
- `.specify/templates/ux-reference-template.md`
|
||||
- `.specify/memory/constitution.md`
|
||||
- `.opencode/skills/semantics-core/SKILL.md` — §VIII Attention Architecture for spec density rules
|
||||
- `README.md`
|
||||
- relevant `docs/adr/*` when the feature clearly touches an existing architectural lane
|
||||
4. Create or update the following artifacts inside `FEATURE_DIR` only:
|
||||
|
||||
@@ -109,13 +109,41 @@ Only include the commands that are truly required by the feature scope.
|
||||
|
||||
### Contract and ADR Propagation
|
||||
|
||||
If a task implements or depends on a guarded contract, append a concise guardrail summary derived from `@RATIONALE` and `@REJECTED`.
|
||||
If a task implements a function with a pre-generated contract in `contracts/modules.md`, inline the contract's key execution constraints directly into the task description. This eliminates cross-file navigation — the implementing agent sees the contract in the task.
|
||||
|
||||
Examples:
|
||||
- `- [ ] T021 [US1] Implement dashboard migration service in backend/src/core/migration/service.py (RATIONALE: full scan ensures consistency; REJECTED: incremental-only update leaves stale entries)`
|
||||
- `- [ ] T033 [US2] Add WebSocket event handler in frontend/src/lib/stores/taskDrawer.js (RATIONALE: real-time feedback prevents polling; REJECTED: interval polling for task status)`
|
||||
**Function contract inlining format (C3+):**
|
||||
|
||||
If no safe executable task wording exists because the accepted path is still unclear, stop and emit `[NEED_CONTEXT: target]`.
|
||||
```text
|
||||
- [ ] T017 [US1] Implement Core.Auth.Login in backend/src/services/auth_service.py
|
||||
@PRE: credentials valid, DB connected
|
||||
@POST: AuthResponse(access_token, refresh_token, user_id)
|
||||
@DATA_CONTRACT: LoginRequest → AuthResponse
|
||||
@TEST_EDGE: invalid_credentials→401, locked_account→423, missing_fields→422
|
||||
|
||||
- [ ] T018 [US1] Implement UserListModel.search in frontend/src/lib/models/UserListModel.svelte.ts
|
||||
@ACTION search(query): full-text, resets pagination
|
||||
@POST: page=1, screenState="loading"
|
||||
@SIDE_EFFECT: GET /api/users?q={query}
|
||||
@TEST_EDGE: empty_query→screenState="idle", network_fail→screenState="error"
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Only inline for C3+ functions with pre-generated contracts in `contracts/modules.md`.
|
||||
- C1/C2 functions do NOT get inlined constraints — their task is just the file path.
|
||||
- Inline ALL `@PRE`, `@POST`, `@SIDE_EFFECT`, `@DATA_CONTRACT`, `@TEST_EDGE` from the contract.
|
||||
- Keep each constraint on one comma-separated line for CSA 4× density.
|
||||
- `@TEST_EDGE` format: `scenario→outcome` (compact, survives pooling).
|
||||
- Task still uses the standard checkbox format on the first line.
|
||||
|
||||
**ADR guardrail format (decision memory only):**
|
||||
|
||||
If a task depends on a guarded decision but has no function contract, append only `@RATIONALE`/`@REJECTED`:
|
||||
|
||||
```text
|
||||
- [ ] T021 [US1] Implement dashboard migration in backend/src/core/migration/service.py
|
||||
RATIONALE: full scan ensures consistency
|
||||
REJECTED: incremental-only update leaves stale entries
|
||||
```
|
||||
|
||||
### Component Reuse Mandate
|
||||
|
||||
|
||||
Reference in New Issue
Block a user