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

fix

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

54
.specify/templates/plan-template.md
View File

@@ -81,25 +81,47 @@ docker/ # Docker configurations
## Semantic Contract Guidance
> Use this section to drive Phase 1 artifacts, especially `contracts/modules.md`.
> See `semantics-core` §VIII for the attention architecture that these rules optimize for.
- Classify each planned module/component/model with `[C:N]` complexity in the `#region` anchor.
- Use canonical anchor syntax appropriate for each context:
- Python: `# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tags]` / `# #endregion ContractId`
- Svelte markup: `<!-- #region ContractId [C:N] [TYPE Component] [SEMANTICS tags] -->` / `<!-- #endregion ContractId -->`
- Svelte/TypeScript model: `// #region ModelName [C:N] [TYPE Model] [SEMANTICS tags]` / `// #endregion ModelName`
- Markdown/ADR: `## @{ ContractId [C:N] [TYPE TypeName]` / `## @} ContractId`
### Attention Compliance Gate (MANDATORY — validate before generating contracts)
Every contract generated in Phase 1 MUST pass these checks (from `semantics-core` §VIII):
| Rule | Check | Why |
|------|-------|-----|
| **ATTN_1** | First anchor line packs `[C:N] [TYPE] [SEMANTICS]` on ONE line | CSA 4× pooling — spread-out anchors lose detail |
| **ATTN_2** | IDs are hierarchical: `Domain.Sub.Name` | HCA 128× — flat IDs become noise |
| **ATTN_3** | Same-domain contracts share primary `@SEMANTICS` keyword | DSA Lightning Indexer scores by keyword match |
| **ATTN_4** | Contract ≤150 lines, module ≤400 lines | Sliding window must see entire contract |
### Anchor Syntax (canonical)
- Python: `# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tags]` / `# #endregion ContractId`
- Svelte markup: `<!-- #region ContractId [C:N] [TYPE Component] [SEMANTICS tags] -->` / `<!-- #endregion ContractId -->`
- Svelte/TypeScript model: `// #region ModelName [C:N] [TYPE Model] [SEMANTICS tags]` / `// #endregion ModelName`
- Markdown/ADR: `## @{ ContractId [C:N] [TYPE TypeName]` / `## @} ContractId`
- **Legacy `[DEF:id:Type]` syntax is deprecated** — use `#region` format exclusively.
- **Model files use `.svelte.ts` extension** — canonical format for contracts with Svelte reactive primitives (`$state`, `$derived`, `$effect`).
- Match contract density to complexity:
- C1: anchors only (DTOs, simple constants)
- C2: typically adds `@BRIEF` (utility functions, pure helpers)
- C3: typically adds `@RELATION`; Svelte also `@UX_STATE`; TypeScript also `@STATE`/`@ACTION`
- C4: typically adds `@PRE`, `@POST`, `@SIDE_EFFECT`; Python also `belief_scope`/`reason`/`reflect` markers; Svelte also `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`
- C5: C4 + `@DATA_CONTRACT`, `@INVARIANT` + `@RATIONALE`/`@REJECTED` decision memory
- **Screen Models** (`[TYPE Model]`) are C4/C5 contracts that declare screen-level state, invariants, and actions. A component that reads/writes model state declares `@RELATION BINDS_TO -> [ModelId]`. See `semantics-svelte` §IIIa.
- Write relations only in canonical form: `@RELATION PREDICATE -> TARGET_ID`
- **Model files use `.svelte.ts` extension** — canonical format for contracts with Svelte reactive primitives.
### Complexity & Metadata (typical — all tags allowed at all tiers)
- C1: anchors only (DTOs, simple constants)
- C2: typically adds `@BRIEF`
- C3: typically adds `@RELATION`; Svelte also `@UX_STATE`; TypeScript also `@STATE`/`@ACTION`
- C4: typically adds `@PRE`, `@POST`, `@SIDE_EFFECT`; Svelte also `@UX_FEEDBACK`, `@UX_RECOVERY`
- C5: C4 + `@DATA_CONTRACT`, `@INVARIANT` + `@RATIONALE`/`@REJECTED` decision memory
- **Screen Models** (`[TYPE Model]`) are C4/C5 contracts. Component binds via `@RELATION BINDS_TO -> [ModelId]`. See `semantics-svelte` §IIIa.
### Relations
- Canonical form: `@RELATION PREDICATE -> TARGET_ID`
- Allowed predicates: `DEPENDS_ON`, `CALLS`, `INHERITS`, `IMPLEMENTS`, `DISPATCHES`, `BINDS_TO`, `CALLED_BY`, `VERIFIES`.
- If any relation target, DTO, or contract dependency is unknown, emit `[NEED_CONTEXT: target]` instead of inventing placeholders.
- Unknown targets → `[NEED_CONTEXT: target]` — never invent placeholders.
- **Cross-stack edges are critical**: backend Pydantic schema MUST have `@RELATION` to frontend TypeScript DTO and vice versa (survives HCA 128× cross-stack amnesia).
### Function-Level Contracts (C3+ only)
For C3+ functions that are API endpoints, Screen Model actions, or orchestration functions, generate full `#region` headers with `@PRE`/`@POST`/`@SIDE_EFFECT`/`@DATA_CONTRACT`/`@TEST_EDGE` in `contracts/modules.md` under their parent module. See `speckit.plan.md` → "Function-Level Contracts for C3+" for the canonical template. C1/C2 functions do NOT need pre-generated contracts — only C3+.
## Complexity Tracking