tasks ready
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
---
|
||||
description: read semantic protocol
|
||||
---
|
||||
MANDATORY USE `skill({name="semantics-core"})`, `skill({name="semantics-contracts"})`, `skill({name="semantics-belief"})`
|
||||
MANDATORY USE `skill({name="semantics-core"})`, `skill({name="semantics-contracts"})`, `skill({name="semantics-belief"})`, `skill({name="semantics-frontend"})`
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
description: Perform a read-only consistency analysis across spec.md, plan.md, tasks.md, and ADR sources for the active Rust MCP feature.
|
||||
description: Perform a read-only consistency analysis across spec.md, plan.md, tasks.md, and ADR sources for the active Python/Svelte feature.
|
||||
---
|
||||
|
||||
## User Input
|
||||
@@ -66,7 +66,7 @@ Identify inconsistencies, ambiguities, coverage gaps, and decision-memory drift
|
||||
|
||||
## Analysis Rules
|
||||
|
||||
- Treat stale Python/Svelte assumptions in plan/tasks as real defects for this repository.
|
||||
- Treat stale Rust/MCP assumptions in plan/tasks as real defects for this Python/Svelte repository.
|
||||
- Treat missing ADR propagation as a real defect, not a documentation nit.
|
||||
- Prefer repository-real expectations (`src/**/*.rs`, `tests/*.rs`, task-shaped MCP tools/resources, belief runtime, static semantic verification).
|
||||
- Prefer repository-real expectations (`backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, `frontend/tests/`, `pytest`, `vitest`, `ruff check`, static semantic verification).
|
||||
- Do not treat `.kilo/plans/*` as feature artifacts for consistency analysis.
|
||||
|
||||
@@ -149,18 +149,19 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
- "Are error handling requirements defined for all API failure modes? [Gap]"
|
||||
- "Are accessibility requirements specified for all interactive elements? [Completeness]"
|
||||
- "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
|
||||
- "Are WebSocket reconnection requirements defined for real-time features? [Gap]"
|
||||
|
||||
Clarity:
|
||||
- "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
|
||||
- "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
|
||||
- "Are 'related dashboards' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
|
||||
- "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
|
||||
|
||||
Consistency:
|
||||
- "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
|
||||
- "Are card component requirements consistent between landing and detail pages? [Consistency]"
|
||||
- "Are component requirements consistent between list and detail views? [Consistency]"
|
||||
|
||||
Coverage:
|
||||
- "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
|
||||
- "Are requirements defined for zero-state scenarios (no dashboards)? [Coverage, Edge Case]"
|
||||
- "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
|
||||
- "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
|
||||
|
||||
@@ -171,7 +172,7 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
Decision Memory:
|
||||
- "Do all repo-shaping technical choices have explicit rationale before tasks are generated? [Decision Memory, Plan]"
|
||||
- "Are rejected alternatives documented for architectural branches that would materially change implementation scope? [Decision Memory, Gap]"
|
||||
- "Can a coder determine from the planning artifacts which tempting shortcut is forbidden? [Decision Memory, Clarity]"
|
||||
- "Can a developer determine from the planning artifacts which tempting shortcut is forbidden? [Decision Memory, Clarity]"
|
||||
|
||||
**Scenario Classification & Coverage** (Requirements Quality Focus):
|
||||
- Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
|
||||
@@ -188,8 +189,8 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
Ask questions about the requirements themselves:
|
||||
- Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
|
||||
- Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
|
||||
- Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
|
||||
- Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
|
||||
- Assumptions: "Is the assumption of 'always available API' validated? [Assumption]"
|
||||
- Dependencies: "Are external API requirements documented? [Dependency, Gap]"
|
||||
- Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
|
||||
- Decision-memory drift: "Do tasks inherit the same rejected-path guardrails defined in planning? [Decision Memory, Conflict]"
|
||||
|
||||
@@ -254,6 +255,7 @@ Sample items:
|
||||
- "Are authentication requirements consistent across all endpoints? [Consistency]"
|
||||
- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
|
||||
- "Is versioning strategy documented in requirements? [Gap]"
|
||||
- "Are WebSocket message schemas documented for all event types? [Completeness, Gap]"
|
||||
|
||||
**Performance Requirements Quality:** `performance.md`
|
||||
|
||||
@@ -289,20 +291,20 @@ Sample items:
|
||||
**❌ WRONG - These test implementation, not requirements:**
|
||||
|
||||
```markdown
|
||||
- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
|
||||
- [ ] CHK001 - Verify landing page displays 3 dashboard cards [Spec §FR-001]
|
||||
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
|
||||
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
|
||||
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
|
||||
- [ ] CHK004 - Check that related dashboards section shows 3-5 items [Spec §FR-005]
|
||||
```
|
||||
|
||||
**✅ CORRECT - These test requirements quality:**
|
||||
|
||||
```markdown
|
||||
- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
|
||||
- [ ] CHK001 - Are the number and layout of featured dashboards explicitly specified? [Completeness, Spec §FR-001]
|
||||
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
|
||||
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
|
||||
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
|
||||
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
|
||||
- [ ] CHK004 - Is the selection criteria for related dashboards documented? [Gap, Spec §FR-005]
|
||||
- [ ] CHK005 - Are loading state requirements defined for asynchronous dashboard data? [Gap]
|
||||
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
|
||||
- [ ] CHK007 - Do planning artifacts state why the accepted architecture was chosen and which alternative is rejected? [Decision Memory, ADR]
|
||||
```
|
||||
|
||||
@@ -46,6 +46,7 @@ Execution steps:
|
||||
- Critical user journeys / sequences
|
||||
- Error/empty/loading states
|
||||
- Accessibility or localization notes
|
||||
- Svelte 5 runes reactivity expectations ($state, $derived, $effect, $props)
|
||||
|
||||
Non-Functional Quality Attributes:
|
||||
- Performance (latency, throughput targets)
|
||||
@@ -66,7 +67,7 @@ Execution steps:
|
||||
- Conflict resolution (e.g., concurrent edits)
|
||||
|
||||
Constraints & Tradeoffs:
|
||||
- Technical constraints (language, storage, hosting)
|
||||
- Technical constraints (Python 3.13+, Svelte 5, PostgreSQL)
|
||||
- Explicit tradeoffs or rejected alternatives
|
||||
|
||||
Terminology & Consistency:
|
||||
|
||||
@@ -18,10 +18,11 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
You are updating the local constitution at `.specify/memory/constitution.md`. This file is the workflow-facing constitutional source for the repository and must align with:
|
||||
|
||||
- `.kilo/skills/semantics-core/SKILL.md`
|
||||
- `.kilo/skills/semantics-contracts/SKILL.md`
|
||||
- `.kilo/skills/semantics-belief/SKILL.md`
|
||||
- `.kilo/skills/semantics-testing/SKILL.md`
|
||||
- `.opencode/skills/semantics-core/SKILL.md`
|
||||
- `.opencode/skills/semantics-contracts/SKILL.md`
|
||||
- `.opencode/skills/semantics-belief/SKILL.md`
|
||||
- `.opencode/skills/semantics-testing/SKILL.md`
|
||||
- `.opencode/skills/semantics-frontend/SKILL.md`
|
||||
- `README.md`
|
||||
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
|
||||
- `docs/adr/*`
|
||||
@@ -29,7 +30,7 @@ You are updating the local constitution at `.specify/memory/constitution.md`. Th
|
||||
Execution flow:
|
||||
|
||||
1. Load the existing constitution at `.specify/memory/constitution.md`.
|
||||
2. Identify placeholders, stale assumptions, or principles that conflict with the current Rust MCP repository.
|
||||
2. Identify placeholders, stale assumptions, or principles that conflict with the current Python/Svelte repository.
|
||||
3. Derive concrete constitutional text from user input and repository reality.
|
||||
4. Version the constitution using semantic versioning:
|
||||
- MAJOR: incompatible governance/principle change
|
||||
@@ -42,11 +43,11 @@ Execution flow:
|
||||
- `.specify/templates/tasks-template.md`
|
||||
- `.specify/templates/test-docs-template.md`
|
||||
- `.specify/templates/ux-reference-template.md`
|
||||
- `.kilo/workflows/speckit.plan.md`
|
||||
- `.kilo/workflows/speckit.tasks.md`
|
||||
- `.kilo/workflows/speckit.implement.md`
|
||||
- `.kilo/workflows/speckit.test.md`
|
||||
- `.kilo/workflows/speckit.analyze.md`
|
||||
- `.opencode/command/speckit.plan.md`
|
||||
- `.opencode/command/speckit.tasks.md`
|
||||
- `.opencode/command/speckit.implement.md`
|
||||
- `.opencode/command/speckit.test.md`
|
||||
- `.opencode/command/speckit.analyze.md`
|
||||
7. Prepend a sync impact report as an HTML comment at the top of the constitution.
|
||||
8. Validate:
|
||||
- no unexplained placeholders remain
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
description: Execute the implementation plan by processing the active tasks.md for the Rust MCP repository.
|
||||
description: Execute the implementation plan by processing the active tasks.md for the Python/Svelte repository.
|
||||
handoffs:
|
||||
- label: Audit & Verify (Tester)
|
||||
agent: qa-tester
|
||||
@@ -39,21 +39,25 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Repository Reality Rules
|
||||
|
||||
- Default source paths are `src/**/*.rs` and `tests/*.rs`.
|
||||
- Default source paths are `backend/src/**/*.py`, `frontend/src/**/*.svelte`, `backend/tests/`, and `frontend/tests/`.
|
||||
- Active feature docs always live under `specs/<feature>/...` and are discovered via the `.specify/scripts/bash/*` helpers.
|
||||
- Default verification stack is Rust-native and repository-real:
|
||||
- `cargo test --all-targets --all-features -- --nocapture`
|
||||
- `cargo clippy --all-targets --all-features -- -D warnings` when applicable
|
||||
- `python3 scripts/static_verify.py`
|
||||
- Do not fall back to `backend/`, `frontend/`, `pytest`, `npm`, or `__tests__/` conventions unless the active feature genuinely introduces such a surface.
|
||||
- Default verification stack is Python/Svelte-native and repository-real:
|
||||
- `cd backend && pytest` (backend tests)
|
||||
- `cd frontend && npm run test` (frontend vitest)
|
||||
- `ruff check backend/` (Python linting)
|
||||
- `cd frontend && npm run build` (Svelte build check)
|
||||
- `python3 scripts/static_verify.py` (semantic static verification when available)
|
||||
- Do not fall back to `cargo`, `cargo test`, `cargo clippy`, `src/**/*.rs`, or Rust/MCP conventions unless the active feature genuinely introduces such a surface.
|
||||
|
||||
## Semantic Execution Rules
|
||||
|
||||
- Preserve and extend canonical `[DEF]` anchors and metadata.
|
||||
- Use correct comment-anchor syntax: `# [DEF:...]` for Python, `<!-- [DEF:...] -->` for Svelte markup, `// [DEF:...]` for Svelte script blocks.
|
||||
- Match contract density to effective complexity.
|
||||
- Keep accepted-path and rejected-path memory intact.
|
||||
- Do not silently restore an ADR- or contract-rejected branch.
|
||||
- For C4/C5 Rust orchestration flows, account for the belief runtime where required by repository norms and local contracts.
|
||||
- For C4/C5 Python orchestration flows, account for the belief runtime where required by repository norms and local contracts.
|
||||
- For C4/C5 Svelte components, ensure `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY` tags are satisfied.
|
||||
- Treat pseudo-semantic markup as invalid.
|
||||
|
||||
## Progress and Acceptance
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
description: Execute the Rust MCP implementation planning workflow and generate research, design, contracts, and quickstart artifacts.
|
||||
description: Execute the Python/Svelte implementation planning workflow and generate research, design, contracts, and quickstart artifacts.
|
||||
handoffs:
|
||||
- label: Create Tasks
|
||||
agent: speckit.tasks
|
||||
prompt: Break the Rust MCP plan into executable tasks
|
||||
prompt: Break the Python/Svelte plan into executable tasks
|
||||
send: true
|
||||
- label: Create Checklist
|
||||
agent: speckit.checklist
|
||||
prompt: Create a requirements-quality checklist for the active Rust MCP feature
|
||||
prompt: Create a requirements-quality checklist for the active Python/Svelte feature
|
||||
---
|
||||
|
||||
## User Input
|
||||
@@ -27,20 +27,19 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
2. **Load canonical planning context**:
|
||||
- `README.md`
|
||||
- `Cargo.toml`
|
||||
- `backend/pyproject.toml` and `backend/requirements.txt`
|
||||
- `frontend/package.json` and `frontend/svelte.config.js`
|
||||
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
|
||||
- `docs/adr/ADR-0001-semantic-rust-module-layout.md`
|
||||
- `docs/adr/ADR-0002-belief-state-runtime.md`
|
||||
- `docs/adr/ADR-0003-comment-anchored-semantic-protocol.md`
|
||||
- `docs/adr/ADR-0004-task-shaped-server-routing.md`
|
||||
- `docs/adr/*.md` (Architecture Decision Records)
|
||||
- `.specify/memory/constitution.md`
|
||||
- `.kilo/skills/semantics-core/SKILL.md`
|
||||
- `.kilo/skills/semantics-contracts/SKILL.md`
|
||||
- `.kilo/skills/semantics-testing/SKILL.md`
|
||||
- `.opencode/skills/semantics-core/SKILL.md`
|
||||
- `.opencode/skills/semantics-contracts/SKILL.md`
|
||||
- `.opencode/skills/semantics-testing/SKILL.md`
|
||||
- `.opencode/skills/semantics-frontend/SKILL.md`
|
||||
- `.specify/templates/plan-template.md`
|
||||
|
||||
3. **Execute the planning workflow** using the template structure:
|
||||
- Fill `Technical Context` for the current repository reality: Rust crate, task-shaped MCP server, semantic contracts, belief runtime, and repository-local verification.
|
||||
- Fill `Technical Context` for the current repository reality: Python 3.13+ backend (FastAPI, SQLAlchemy), Svelte 5 frontend (SvelteKit, Vite, Tailwind CSS), PostgreSQL storage, Docker deployment.
|
||||
- Fill `Constitution Check` using the local constitution, semantic protocol compliance doc, and ADR set.
|
||||
- ERROR if a blocking constitutional or semantic conflict is discovered and cannot be justified.
|
||||
- Phase 0: generate `research.md` in `FEATURE_DIR`, resolving all material unknowns.
|
||||
@@ -52,14 +51,16 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Phase 0: Research
|
||||
|
||||
Research must resolve only implementation-shaping unknowns that matter for this Rust MCP repository, such as:
|
||||
Research must resolve only implementation-shaping unknowns that matter for this Python/Svelte repository, such as:
|
||||
|
||||
- crate/module placement under `src/`
|
||||
- `tests/*.rs` strategy and required fixture coverage
|
||||
- MCP tool/resource schema design
|
||||
- runtime evidence and belief-state coverage
|
||||
- backend module placement under `backend/src/` (api/, core/, models/, services/, schemas/)
|
||||
- frontend component placement under `frontend/src/` (routes/, lib/components/, lib/stores/, lib/api/)
|
||||
- `backend/tests/` and `frontend/tests/` strategy and required fixture coverage
|
||||
- FastAPI endpoint / WebSocket schema design
|
||||
- Svelte 5 runes reactivity model ($state, $derived, $effect, $props)
|
||||
- PostgreSQL schema and migration strategy
|
||||
- belief-state runtime coverage for C4/C5 Python flows
|
||||
- semantic validation boundaries and static verification workflow
|
||||
- task-shaped routing, workspace safety, and error-envelope design
|
||||
|
||||
Write `research.md` with concise sections:
|
||||
|
||||
@@ -74,29 +75,34 @@ Use `[NEED_CONTEXT: target]` instead of inventing relation targets, DTO names, o
|
||||
|
||||
### UX / Interaction Validation
|
||||
|
||||
Validate the proposed design against `ux_reference.md` as an **interaction reference** for MCP callers, CLI/operator flows, result envelopes, warnings, and recovery guidance.
|
||||
Validate the proposed design against `ux_reference.md` as an **interaction reference** for:
|
||||
- API callers (REST endpoints, WebSocket messages)
|
||||
- CLI/operator flows
|
||||
- Svelte UI flows (when the feature introduces frontend components)
|
||||
- Result envelopes, warnings, and recovery guidance
|
||||
|
||||
If the planned architecture degrades the promised interaction model, deterministic recovery path, or context-budget behavior, stop and warn the user.
|
||||
|
||||
### Data Model Output
|
||||
|
||||
Generate `data-model.md` for Rust/MCP domain entities such as:
|
||||
Generate `data-model.md` for Python/Svelte domain entities such as:
|
||||
|
||||
- tool request/response structs
|
||||
- semantic query payloads
|
||||
- runtime evidence envelopes
|
||||
- workspace/checkpoint/index/security entities
|
||||
- contract and relation traceability data
|
||||
- FastAPI request/response schemas (Pydantic models)
|
||||
- SQLAlchemy ORM entities
|
||||
- Svelte store shapes and component props
|
||||
- WebSocket message envelopes
|
||||
- Task/report/artifact entities
|
||||
|
||||
### Global ADR Continuity
|
||||
|
||||
Before task decomposition, planning must identify any repo-shaping decisions this feature depends on or extends:
|
||||
|
||||
- Rust module layout and decomposition
|
||||
- task-shaped tool/resource routing
|
||||
- belief-state runtime behavior
|
||||
- semantic comment-anchor rules
|
||||
- payload/schema stability decisions
|
||||
- Python module layout and decomposition (`backend/src/api/`, `backend/src/core/`, etc.)
|
||||
- Frontend component architecture (Svelte 5 runes, SvelteKit routing)
|
||||
- Belief-state runtime behavior for C4/C5 flows
|
||||
- Semantic comment-anchor rules for Python and Svelte
|
||||
- RBAC/security constraints (local auth, ADFS SSO)
|
||||
- Plugin system lifecycle
|
||||
|
||||
For each durable choice, ensure the plan references the relevant ADR and explicitly records accepted and rejected paths.
|
||||
|
||||
@@ -108,37 +114,35 @@ Generate `contracts/modules.md` as the primary design contract for implementatio
|
||||
- classify each planned module/component with `@COMPLEXITY` 1-5
|
||||
- use canonical relation syntax `@RELATION PREDICATE -> TARGET_ID`
|
||||
- preserve accepted-path and rejected-path memory via `@RATIONALE` and `@REJECTED` where needed
|
||||
- describe MCP tools/resources, runtime evidence, validation envelopes, and semantic boundaries instead of inventing backend/frontend layers
|
||||
- describe Python backend modules (api routes, core services, models, plugins) and Svelte frontend components instead of inventing Rust/MCP layers
|
||||
- use appropriate comment-anchor syntax: `# [DEF:...]` for Python, `<!-- [DEF:...] -->` for Svelte markup, `// [DEF:...]` for Svelte script blocks
|
||||
|
||||
Complexity guidance for this repository:
|
||||
|
||||
- **Complexity 1**: anchors only
|
||||
- **Complexity 2**: `@PURPOSE`
|
||||
- **Complexity 3**: `@PURPOSE`, `@RELATION`
|
||||
- **Complexity 4**: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; Rust orchestration paths should account for belief runtime markers before mutation or return
|
||||
- **Complexity 1**: anchors only (DTOs, simple constants)
|
||||
- **Complexity 2**: `@PURPOSE` (utility functions, pure helpers)
|
||||
- **Complexity 3**: `@PURPOSE`, `@RELATION` (multi-step flows with dependencies); Svelte components also `@UX_STATE`
|
||||
- **Complexity 4**: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; Python orchestration paths should account for belief runtime markers (`belief_scope`, `reason`, `reflect`, `explore`); Svelte also `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`
|
||||
- **Complexity 5**: level 4 plus `@DATA_CONTRACT`, `@INVARIANT`, and explicit decision-memory continuity
|
||||
|
||||
If a planned contract depends on unknown schema, relation target, or ADR identity, emit `[NEED_CONTEXT: target]` instead of fabricating placeholders.
|
||||
|
||||
### Optional Machine-Readable Contracts
|
||||
|
||||
You MAY generate machine-readable artifacts in `contracts/` only when they mirror the actual MCP tool/resource payloads of this Rust server. Do **not** default to REST/OpenAPI or frontend-sync artifacts unless the feature truly introduces them.
|
||||
|
||||
### Quickstart Output
|
||||
|
||||
Generate `quickstart.md` using real repository verification paths, typically:
|
||||
Generate `quickstart.md` using real repository verification paths:
|
||||
|
||||
- start or exercise the MCP server entrypoint
|
||||
- invoke relevant MCP tools/resources
|
||||
- validate expected envelopes and recovery flows
|
||||
- run `cargo test --all-targets --all-features -- --nocapture`
|
||||
- run `cargo clippy --all-targets --all-features -- -D warnings` when applicable
|
||||
- run `python3 scripts/static_verify.py`
|
||||
- start or exercise the FastAPI backend entrypoint: `cd backend && python -m uvicorn src.app:app --reload`
|
||||
- start or exercise the SvelteKit frontend: `cd frontend && npm run dev`
|
||||
- invoke relevant API endpoints or CLI commands
|
||||
- validate expected response envelopes, WebSocket messages, and recovery flows
|
||||
- run `cd backend && pytest` for backend tests
|
||||
- run `cd frontend && npm run test` for frontend tests
|
||||
- run `ruff check backend/` for Python linting
|
||||
|
||||
## Key Rules
|
||||
|
||||
- Use absolute paths in workflow execution.
|
||||
- Planning must reflect the current repository structure (`src/**/*.rs`, `tests/*.rs`, `docs/adr/*`) rather than legacy Python/Svelte examples.
|
||||
- Do not reference `.ai/*` or `.kilocode/*` paths.
|
||||
- Planning must reflect the current repository structure (`backend/src/`, `frontend/src/`, `docs/adr/`) rather than legacy Rust/MCP examples.
|
||||
- Do not reference `.ai/*` or `.kilocode/*` paths as feature artifacts.
|
||||
- Do not write any feature planning artifact outside `specs/<feature>/...`.
|
||||
- Do not hand off to `speckit.tasks` until blocking ADR continuity and rejected-path guardrails are explicit.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
description: Maintain semantic integrity by reindexing, auditing, and reviewing the Rust MCP repository through AXIOM MCP tools.
|
||||
description: Maintain semantic integrity by reindexing, auditing, and reviewing the Python/Svelte repository through AXIOM MCP tools.
|
||||
---
|
||||
|
||||
## User Input
|
||||
@@ -19,9 +19,10 @@ Ensure the repository adheres to the active GRACE semantic protocol using AXIOM
|
||||
1. **ROLE: Orchestrator** — coordinate semantic maintenance at the workflow level.
|
||||
2. **MCP-FIRST** — use AXIOM task-shaped tools for discovery, context, audit, impact analysis, and safe mutation planning.
|
||||
3. **STRICT ADHERENCE** — follow the local semantic authorities:
|
||||
- `.kilo/skills/semantics-core/SKILL.md`
|
||||
- `.kilo/skills/semantics-contracts/SKILL.md`
|
||||
- `.kilo/skills/semantics-testing/SKILL.md`
|
||||
- `.opencode/skills/semantics-core/SKILL.md`
|
||||
- `.opencode/skills/semantics-contracts/SKILL.md`
|
||||
- `.opencode/skills/semantics-testing/SKILL.md`
|
||||
- `.opencode/skills/semantics-frontend/SKILL.md`
|
||||
- `docs/SEMANTIC_PROTOCOL_COMPLIANCE.md`
|
||||
- `docs/adr/*`
|
||||
4. **NON-DESTRUCTIVE** — do not remove business logic; only add or correct semantic markup unless the user requested implementation changes.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
description: Create or update the feature specification from a natural-language feature description for the Rust MCP repository.
|
||||
description: Create or update the feature specification from a natural-language feature description for the Python/Svelte repository.
|
||||
handoffs:
|
||||
- label: Build Technical Plan
|
||||
agent: speckit.plan
|
||||
prompt: Create a Rust MCP implementation plan for the active feature
|
||||
prompt: Create a Python/Svelte implementation plan for the active feature
|
||||
- label: Clarify Spec Requirements
|
||||
agent: speckit.clarify
|
||||
prompt: Clarify specification requirements
|
||||
@@ -39,38 +39,41 @@ The feature description is the text passed to `/speckit.specify`.
|
||||
- `spec.md`
|
||||
- `ux_reference.md`
|
||||
- `checklists/requirements.md`
|
||||
5. Generate `ux_reference.md` as an **interaction reference** for MCP callers, CLI/operator flows, result envelopes, warnings, and recovery behavior.
|
||||
6. Write `spec.md` focused on **what** the user/operator needs and **why**, not how the Rust crate will implement it.
|
||||
5. Generate `ux_reference.md` as an **interaction reference** for API callers, CLI/operator flows, Svelte UX states, result envelopes, warnings, and recovery behavior.
|
||||
6. Write `spec.md` focused on **what** the user/operator needs and **why**, not how the Python/FastAPI backend or Svelte frontend will implement it.
|
||||
7. Validate the spec against a requirements-quality checklist and iterate until major issues are resolved.
|
||||
|
||||
## Specification Rules
|
||||
|
||||
- Use domain language appropriate for this repository: MCP callers, tools, resources, runtime evidence, workspace flows, operator recovery, semantic contracts.
|
||||
- Avoid leaking implementation details such as module names, crates, file-level refactors, or exact Rust APIs.
|
||||
- Use domain language appropriate for this repository: API callers (REST/WebSocket), CLI operators, Svelte UI users, task runners, data migration operators, Git integration users.
|
||||
- Avoid leaking implementation details such as FastAPI route names, SQLAlchemy models, Svelte component names, or exact file-level refactors.
|
||||
- Use `[NEEDS CLARIFICATION: ...]` only for truly blocking product ambiguities. Maximum 3 markers.
|
||||
- Prefer informed defaults grounded in repository context over unnecessary clarification.
|
||||
- Do not assume web-app, backend/frontend, or Svelte UI flows unless the feature actually introduces them.
|
||||
- The default project structure is a web application with `backend/src/` (Python) and `frontend/src/` (Svelte). Assume this unless the feature explicitly changes it.
|
||||
- Do not assume Rust, MCP server, cargo, or `src/*.rs` conventions unless the feature actually introduces them.
|
||||
- Do not write feature outputs to `.kilo/plans/`, `.kilo/reports/`, or any path outside `specs/<feature>/...`.
|
||||
|
||||
## UX / Interaction Reference Rules
|
||||
|
||||
- `ux_reference.md` is mandatory, but for this repository it is usually an interaction-reference artifact rather than a screen-design artifact.
|
||||
- `ux_reference.md` is mandatory. For this repository it covers both:
|
||||
- **API/interaction reference** for backend callers (REST endpoints, WebSocket messages, CLI commands)
|
||||
- **Svelte UX reference** for frontend flows (when the feature has a UI component)
|
||||
- Capture:
|
||||
- caller/operator persona
|
||||
- happy-path invocation flow
|
||||
- result envelope expectations
|
||||
- caller/operator/end-user persona
|
||||
- happy-path invocation flow (API requests, CLI commands, or UI interactions)
|
||||
- result envelope expectations (JSON response shapes, CLI output, UI feedback)
|
||||
- warning/degraded states
|
||||
- failure recovery guidance
|
||||
- canonical terminology
|
||||
- Only include UI-specific `@UX_*` guidance when the feature truly has a user interface component.
|
||||
- Include `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY` guidance when the feature introduces Svelte components.
|
||||
|
||||
## Quality Validation
|
||||
|
||||
Generate `FEATURE_DIR/checklists/requirements.md` and ensure it validates:
|
||||
|
||||
- no implementation leakage into `spec.md`
|
||||
- no stale Python/Svelte assumptions unless the feature explicitly needs them
|
||||
- compatibility with the Rust MCP/task-shaped tool surface
|
||||
- no stale Rust/MCP assumptions unless the feature explicitly needs them
|
||||
- compatibility with the Python/FastAPI backend and Svelte frontend surface
|
||||
- measurable success criteria
|
||||
- explicit edge cases and recovery paths
|
||||
- decision-memory readiness for downstream planning
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
---
|
||||
description: Generate an actionable, dependency-ordered tasks.md for the active Rust MCP feature.
|
||||
description: Generate an actionable, dependency-ordered tasks.md for the active Python/Svelte feature.
|
||||
handoffs:
|
||||
- label: Analyze For Consistency
|
||||
agent: speckit.analyze
|
||||
prompt: Run a cross-artifact consistency analysis for the Rust MCP feature
|
||||
prompt: Run a cross-artifact consistency analysis for the Python/Svelte feature
|
||||
send: true
|
||||
- label: Implement Project
|
||||
agent: speckit.implement
|
||||
prompt: Start implementation in phases for the Rust MCP feature
|
||||
prompt: Start implementation in phases for the Python/Svelte feature
|
||||
send: true
|
||||
---
|
||||
|
||||
@@ -31,9 +31,9 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
3. **Build the task model**:
|
||||
- Extract user stories and priorities from `spec.md`
|
||||
- Extract repository structure, tool/resource scope, verification stack, and semantic constraints from `plan.md`
|
||||
- Extract repository structure, backend/frontend scope, verification stack, and semantic constraints from `plan.md`
|
||||
- Extract accepted-path and rejected-path memory from ADRs and `contracts/modules.md`
|
||||
- Map entities, tool payloads, runtime evidence, and verification scenarios to stories
|
||||
- Map entities, API payloads, UI components, and verification scenarios to stories
|
||||
- Generate tasks grouped by story and ordered by dependency
|
||||
- Validate that no task schedules an ADR-rejected path
|
||||
|
||||
@@ -41,9 +41,9 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
- Phase 1: Setup
|
||||
- Phase 2: Foundational work
|
||||
- Phase 3+: one phase per user story in priority order
|
||||
- Final phase: polish and cross-cutting verification
|
||||
- Every task must use the strict checklist format and include exact file paths
|
||||
- Write the final document to `FEATURE_DIR/tasks.md`, never to `.kilo/plans/` or other side folders
|
||||
- Final phase: polish and cross-cutting verification
|
||||
- Every task must use the strict checklist format and include exact file paths
|
||||
- Write the final document to `FEATURE_DIR/tasks.md`, never to `.kilo/plans/` or other side folders
|
||||
|
||||
5. **Report** the generated path and summarize:
|
||||
- total task count
|
||||
@@ -74,38 +74,52 @@ Rules:
|
||||
4. `[USx]` required only for user-story phases
|
||||
5. exact file paths required in the description
|
||||
|
||||
### Rust / MCP Pathing
|
||||
### Python / Svelte Pathing
|
||||
|
||||
Prefer real repository paths such as:
|
||||
|
||||
- `src/server/*.rs`
|
||||
- `src/services/**/*.rs`
|
||||
- `src/models/*.rs`
|
||||
- `src/semantics/*.rs`
|
||||
- `tests/*.rs`
|
||||
**Backend (Python):**
|
||||
- `backend/src/api/*.py` (FastAPI routes)
|
||||
- `backend/src/core/**/*.py` (core services, task manager, auth, migration, plugins)
|
||||
- `backend/src/models/*.py` (SQLAlchemy models)
|
||||
- `backend/src/services/*.py` (business logic)
|
||||
- `backend/src/schemas/*.py` (Pydantic schemas)
|
||||
- `backend/tests/*.py` (pytest tests)
|
||||
|
||||
**Frontend (Svelte):**
|
||||
- `frontend/src/routes/**/*.svelte` (SvelteKit pages)
|
||||
- `frontend/src/lib/components/**/*.svelte` (reusable Svelte 5 components)
|
||||
- `frontend/src/lib/stores/*.svelte.js` (Svelte rune stores)
|
||||
- `frontend/src/lib/api/*.js` (API client modules)
|
||||
- `frontend/tests/**/*.test.js` (vitest tests)
|
||||
|
||||
**Shared/Infrastructure:**
|
||||
- `docs/adr/*.md`
|
||||
- `docker/*`
|
||||
- `specs/<feature>/contracts/*.md`
|
||||
|
||||
Do **not** generate default tasks for:
|
||||
|
||||
- `backend/` or `frontend/`
|
||||
- `*.py`
|
||||
- `.svelte`
|
||||
- `__tests__/`
|
||||
- `src/**/*.rs` or `tests/*.rs`
|
||||
- `Cargo.toml`
|
||||
- `cargo` commands
|
||||
- MCP server/tool/resource syntax unless the feature actually introduces them
|
||||
|
||||
### Verification Discipline
|
||||
|
||||
Each story phase must end with:
|
||||
|
||||
- a verification task against `ux_reference.md` interpreted as the caller/operator interaction contract
|
||||
- a verification task against `ux_reference.md` interpreted as the API caller, CLI operator, or Svelte UX interaction contract
|
||||
- a semantic audit / verification task tied to repository validators and touched contracts
|
||||
|
||||
Typical verification tasks may include:
|
||||
|
||||
- focused `cargo test` commands
|
||||
- `cargo test --all-targets --all-features -- --nocapture`
|
||||
- `cargo clippy --all-targets --all-features -- -D warnings`
|
||||
- `python3 scripts/static_verify.py`
|
||||
- focused `pytest backend/tests/test_<module>.py` commands
|
||||
- `cd backend && pytest` (full backend suite)
|
||||
- `cd frontend && npm run test` (vitest suite)
|
||||
- `ruff check backend/` (Python lint)
|
||||
- `cd frontend && npm run build` (Svelte build validation)
|
||||
- `python3 scripts/static_verify.py` (semantic static verification)
|
||||
|
||||
Only include the commands that are truly required by the feature scope.
|
||||
|
||||
@@ -115,8 +129,9 @@ If a task implements or depends on a guarded contract, append a concise guardrai
|
||||
|
||||
Examples:
|
||||
|
||||
- `- [ ] T021 [US1] Implement deterministic tool envelope mapping in src/server/tools.rs (RATIONALE: preserve task-shaped MCP parity; REJECTED: ad-hoc per-tool response shapes)`
|
||||
- `- [ ] T033 [US2] Add runtime evidence verification in tests/server_protocol.rs (RATIONALE: C4/C5 flows must expose belief markers; REJECTED: relying on manual log inspection only)`
|
||||
- `- [ ] T021 [US1] Implement report generation endpoint in backend/src/api/reports.py (RATIONALE: unified report envelope preserves task-shaped parity; REJECTED: ad-hoc per-endpoint response shapes)`
|
||||
- `- [ ] T033 [US2] Add WebSocket logging handler in backend/src/core/task_manager/ws_handler.py (RATIONALE: C4/C5 flows must expose real-time log streaming; REJECTED: polling-based log retrieval)`
|
||||
- `- [ ] T040 [US3] Create DashboardCard component in frontend/src/lib/components/DashboardCard.svelte (RATIONALE: @UX_STATE must cover Idle/Loading/Error/Empty; REJECTED: single-state inline rendering without recovery)`
|
||||
|
||||
If no safe executable task wording exists because the accepted path is still unclear, stop and emit `[NEED_CONTEXT: target]`.
|
||||
|
||||
@@ -124,8 +139,9 @@ If no safe executable task wording exists because the accepted path is still unc
|
||||
|
||||
Tests are optional only when the feature truly has no new verification surface. In this repository, test tasks are usually expected for:
|
||||
|
||||
- new MCP tools/resources
|
||||
- new query/mutation flows
|
||||
- new FastAPI endpoints / WebSocket handlers
|
||||
- new plugin or service modules
|
||||
- new Svelte components with `@UX_STATE` contracts
|
||||
- C4/C5 semantic contracts
|
||||
- runtime evidence / belief-state behavior
|
||||
- rejected-path regression coverage
|
||||
@@ -136,5 +152,5 @@ Before finalizing `tasks.md`, verify that:
|
||||
|
||||
- blocking ADRs are inherited into setup/foundational or downstream story tasks
|
||||
- no task text schedules a rejected path
|
||||
- story tasks remain executable within the actual Rust crate structure
|
||||
- story tasks remain executable within the actual Python/Svelte repository structure
|
||||
- at least one explicit verification task protects against rejected-path regression
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
description: Execute semantic audit and Rust-native testing for the active feature batch.
|
||||
description: Execute semantic audit and Python/Svelte-native testing for the active feature batch.
|
||||
---
|
||||
|
||||
## User Input
|
||||
@@ -12,14 +12,16 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Goal
|
||||
|
||||
Run the verification loop for the touched Rust MCP scope: semantic audit, decision-memory audit, executable tests, logic review, and documentation of coverage/results.
|
||||
Run the verification loop for the touched Python/Svelte scope: semantic audit, decision-memory audit, executable tests (pytest + vitest), logic review, and documentation of coverage/results.
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
1. **NEVER delete existing tests** unless the user explicitly requests removal.
|
||||
2. **NEVER duplicate tests** when existing `tests/*.rs` coverage already validates the same contract.
|
||||
2. **NEVER duplicate tests** when existing `backend/tests/` or `frontend/tests/` coverage already validates the same contract.
|
||||
3. **Decision-memory regression guard**: tests and audits must not silently normalize any path documented as rejected.
|
||||
4. **Rust-native structure**: prefer existing integration/protocol test organization under `tests/`.
|
||||
4. **Python/Svelte-native structure**: prefer existing test organization:
|
||||
- Backend: `backend/tests/` with pytest
|
||||
- Frontend: `frontend/tests/` or co-located `__tests__/` with vitest + @testing-library/svelte
|
||||
|
||||
## Execution Steps
|
||||
|
||||
@@ -29,7 +31,7 @@ Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --inclu
|
||||
|
||||
- `FEATURE_DIR`
|
||||
- touched implementation tasks from `tasks.md`
|
||||
- affected `.rs` files
|
||||
- affected `.py` and `.svelte` files
|
||||
- relevant ADRs, `@RATIONALE`, and `@REJECTED` guardrails
|
||||
|
||||
All test documentation emitted by this workflow belongs under `FEATURE_DIR/tests/` or other files inside `specs/<feature>/...`, never under `.kilo/plans/`.
|
||||
@@ -61,9 +63,10 @@ Before writing or executing tests, perform a semantic audit of the touched scope
|
||||
1. Use the AXIOM semantic validation path where available.
|
||||
2. Reject malformed or pseudo-semantic markup.
|
||||
3. Verify contract density matches effective complexity.
|
||||
4. Verify C4/C5 Rust flows account for belief runtime markers (`belief_scope`, `reason`, `reflect`, `explore`) when required by the contract and repository norms.
|
||||
5. Verify no touched code silently restores an ADR- or contract-rejected path.
|
||||
6. Emulate the algorithm mentally to ensure `@PRE`, `@POST`, `@INVARIANT`, and declared side effects remain coherent.
|
||||
4. For C4/C5 Python flows: verify belief runtime markers (`belief_scope`, `reason`, `reflect`, `explore`).
|
||||
5. For C4/C5 Svelte components: verify `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY` coverage.
|
||||
6. Verify no touched code silently restores an ADR- or contract-rejected path.
|
||||
7. Emulate the algorithm mentally to ensure `@PRE`, `@POST`, `@INVARIANT`, and declared side effects remain coherent.
|
||||
|
||||
If audit fails, emit `[AUDIT_FAIL: semantic_noncompliance | contract_mismatch | logic_mismatch | rejected_path_regression]` with concrete file-based reasons.
|
||||
|
||||
@@ -71,24 +74,35 @@ If audit fails, emit `[AUDIT_FAIL: semantic_noncompliance | contract_mismatch |
|
||||
|
||||
When test additions are needed:
|
||||
|
||||
- prefer `tests/*.rs` integration/protocol coverage
|
||||
- use deterministic fixtures rather than logic mirrors
|
||||
- trace tests back to semantic contracts and ADR guardrails
|
||||
- add explicit rejected-path regression coverage when the touched scope has a forbidden alternative
|
||||
|
||||
For non-UI Rust MCP flows, UX verification means validating interaction envelopes, warnings, recovery messaging, and tool/resource discoverability promised by `ux_reference.md`.
|
||||
- Backend: prefer `backend/tests/` with pytest fixtures, use `unittest.mock` / `pytest-mock` for external dependencies
|
||||
- Frontend: prefer vitest with `@testing-library/svelte` for component testing, `jsdom` environment
|
||||
- Use deterministic fixtures rather than logic mirrors
|
||||
- Trace tests back to semantic contracts and ADR guardrails
|
||||
- Add explicit rejected-path regression coverage when the touched scope has a forbidden alternative
|
||||
- For Svelte UX contracts, validate `@UX_STATE` transitions, `@UX_FEEDBACK` messages, and `@UX_RECOVERY` paths
|
||||
|
||||
### 6. Execute Verifiers
|
||||
|
||||
Run the smallest truthful verifier set for the touched scope, typically chosen from:
|
||||
|
||||
```bash
|
||||
cargo test --all-targets --all-features -- --nocapture
|
||||
cargo clippy --all-targets --all-features -- -D warnings
|
||||
# Backend tests
|
||||
cd backend && pytest
|
||||
|
||||
# Backend lint
|
||||
ruff check backend/
|
||||
|
||||
# Frontend tests
|
||||
cd frontend && npm run test
|
||||
|
||||
# Frontend build check (catches Svelte compilation errors)
|
||||
cd frontend && npm run build
|
||||
|
||||
# Semantic static verification (when available)
|
||||
python3 scripts/static_verify.py
|
||||
```
|
||||
|
||||
Use narrower `cargo test <target>` runs when they are sufficient and then widen verification when finalizing the feature batch.
|
||||
Use narrower test runs when they are sufficient (e.g., `pytest backend/tests/test_auth.py`) and then widen verification when finalizing the feature batch.
|
||||
|
||||
### 7. Test Documentation
|
||||
|
||||
|
||||
@@ -33,8 +33,9 @@ Decision memory prevents architectural drift. It records the *Decision Space* (W
|
||||
2. **Task Guardrails:** Preventative `@REJECTED` tags injected by the Orchestrator to keep you away from known LLM pitfalls.
|
||||
3. **Reactive Micro-ADR (Your Responsibility):** If you encounter a runtime failure, use `explore()`, and invent a valid workaround, you MUST ascend to the `[DEF]` header and document it via `@RATIONALE [Why]` and `@REJECTED [The failing path]` BEFORE closing the task.
|
||||
|
||||
**⚠️ `@RATIONALE`/`@REJECTED` ARE C5-ONLY.**
|
||||
Decision Memory tags belong exclusively to C5 contracts per Std:Semantics:Core complexity scale. C4 adds `@PRE`/`@POST`/`@SIDE_EFFECT` — not decision memory. Adding them below C5 violates INV_7 (verbosity/erosion). If a C1-C4 contract genuinely needs decision memory, it should be C5.
|
||||
**`@RATIONALE` / `@REJECTED` are ORTHOGONAL tags.** Per `axiom_config.yaml`, these are `protected: true` and `orthogonal: true` — they may appear at ANY complexity level (C1-C5) when a node records a deliberate architectural choice. They are REQUIRED for `ADR` type contracts. Removal of an existing `@RATIONALE`/`@REJECTED` requires `<ESCALATION>` to the Architect.
|
||||
|
||||
If a C1-C4 contract records a workaround after a runtime failure, add `@RATIONALE`/`@REJECTED` at that node's header BEFORE closing the task. This is a Reactive Micro-ADR — it does NOT require bumping the complexity to C5.
|
||||
|
||||
**Resurrection Ban:** Silently reintroducing a coding pattern, library, or logic flow previously marked as `@REJECTED` is classified as a fatal regression. If the rejected path is now required, emit `<ESCALATION>` to the Architect.
|
||||
|
||||
|
||||
@@ -42,9 +42,15 @@ Format depends on the execution environment:
|
||||
- JS/TS: `// [DEF:Id:Type] ... // [/DEF:Id:Type]`
|
||||
*Allowed Types: Root, Standard, Module, Class, Function, Component, Store, Block, ADR, Tombstone.*
|
||||
|
||||
**Module Header Tags (required for `Module` type at ALL complexity levels):**
|
||||
- `@LAYER` — architectural layer: `Domain` (business logic), `UI` (interface), `Infra` (infrastructure), `Test` (tests).
|
||||
- `@SEMANTICS` — orthogonal semantic markers (comma-separated keywords, e.g. `indexing, validation, metadata`).
|
||||
|
||||
**ADR Type Override:** `ADR` type has its own contract rules — `@COMPLEXITY` is FORBIDDEN. ADR requires only: `@PURPOSE`, `@RELATION`, `@RATIONALE`, `@REJECTED`. Optional orthogonal tags: `@STATUS` (ACTIVE, DEPRECATED, EXPERIMENTAL).
|
||||
|
||||
**Graph Dependencies (GraphRAG):**
|
||||
`@RELATION PREDICATE -> TARGET_ID`
|
||||
*Allowed Predicates:* DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO.
|
||||
*Allowed Predicates:* DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO, VERIFIES.
|
||||
|
||||
## III. COMPLEXITY SCALE (1-5)
|
||||
The level of control is defined in the Header via `@COMPLEXITY`. Default is 1 if omitted.
|
||||
@@ -54,6 +60,10 @@ The level of control is defined in the Header via `@COMPLEXITY`. Default is 1 if
|
||||
- **C4 (Orchestration):** Adds `@PRE`, `@POST`, `@SIDE_EFFECT`. Requires Belief State runtime logging.
|
||||
- **C5 (Critical):** Adds `@DATA_CONTRACT`, `@INVARIANT`, and mandatory Decision Memory tracking.
|
||||
|
||||
**Module type** additionally requires `@LAYER` and `@SEMANTICS` at EVERY complexity level (C1-C5). These are Module‑only — not required for Function, Class, Block, or Component types.
|
||||
|
||||
**`@RATIONALE` / `@REJECTED` are orthogonal tags** — they may appear at ANY complexity level (C1-C5) when decision memory is needed. They are `protected: true` (cannot be removed without escalation) and are REQUIRED for `ADR` type. Adding them to lower‑complexity nodes does NOT violate INV_7 — the tag belongs to the decision space, not the complexity hierarchy.
|
||||
|
||||
## IV. DOMAIN SUB-PROTOCOLS (ROUTING)
|
||||
Depending on your active task, you MUST request and apply the following domain-specific rules:
|
||||
- For Backend Logic & Architecture: Use `skill({name="semantics-contracts"})` and `skill({name="semantics-belief"})`.
|
||||
@@ -81,7 +91,7 @@ The complexity scale is NOT a checklist — each level has a STRICT MAXIMUM of a
|
||||
Do NOT add tags from higher levels. The examples below show the boundary of what is acceptable at each tier.
|
||||
|
||||
### C1 (Atomic) — DTOs, simple constants, trivial wrappers
|
||||
Requires ONLY `[DEF]...[/DEF]`. No `@PURPOSE`, no `@RELATION`, no `@RATIONALE`, no `@PRE`/`@POST`.
|
||||
Requires ONLY `[DEF]...[/DEF]`. No `@PURPOSE`, no `@RELATION`, no `@PRE`/`@POST`.
|
||||
```python
|
||||
# [DEF:UserDTO:Class]
|
||||
@dataclass
|
||||
@@ -91,10 +101,11 @@ class UserDTO:
|
||||
email: str
|
||||
# [/DEF:UserDTO:Class]
|
||||
```
|
||||
Do NOT add: `@PURPOSE`, `@RATIONALE`, `@REJECTED`, `@PRE`, `@POST`, `@SIDE_EFFECT`, `@RELATION`, `@DATA_CONTRACT`, `@INVARIANT`.
|
||||
Do NOT add: `@PURPOSE`, `@PRE`, `@POST`, `@SIDE_EFFECT`, `@RELATION`, `@DATA_CONTRACT`, `@INVARIANT`.
|
||||
Note: `@RATIONALE`/`@REJECTED` are orthogonal — they MAY appear at C1 if the node records a deliberate architectural choice (e.g., "why this DTO has field X instead of Y").
|
||||
|
||||
### C2 (Simple) — Utility functions, pure computations
|
||||
Adds `@PURPOSE`. Still NO `@RELATION`, NO `@RATIONALE`, NO `@PRE`/`@POST`.
|
||||
Adds `@PURPOSE`. Still NO `@RELATION`, NO `@PRE`/`@POST`.
|
||||
```python
|
||||
# [DEF:format_timestamp:Function]
|
||||
# @COMPLEXITY 2
|
||||
@@ -105,7 +116,7 @@ def format_timestamp(ts: datetime) -> str:
|
||||
```
|
||||
|
||||
### C3 (Flow) — Multi-step logic with dependencies
|
||||
Adds `@RELATION` for dependencies. Still NO `@RATIONALE`, NO `@PRE`/`@POST`.
|
||||
Adds `@RELATION` for dependencies. Still NO `@PRE`/`@POST`.
|
||||
```python
|
||||
# [DEF:load_and_validate:Function]
|
||||
# @COMPLEXITY 3
|
||||
@@ -121,7 +132,7 @@ def load_and_validate(path: str) -> dict:
|
||||
|
||||
### C4 (Orchestration) — Stateful operations with side effects
|
||||
Adds `@PRE`, `@POST`, `@SIDE_EFFECT`. Add `belief_scope()` + `reason()`/`reflect()` in body.
|
||||
Still NO `@RATIONALE`, NO `@REJECTED`, NO `@DATA_CONTRACT`, NO `@INVARIANT`.
|
||||
Still NO `@DATA_CONTRACT`, NO `@INVARIANT`.
|
||||
```python
|
||||
# [DEF:migrate_database:Function]
|
||||
# @COMPLEXITY 4
|
||||
@@ -149,8 +160,8 @@ def migrate_database(conn: Connection) -> None:
|
||||
# [/DEF:migrate_database:Function]
|
||||
```
|
||||
|
||||
### C5 (Critical) — Core infrastructure with invariants and decision memory
|
||||
Adds `@RATIONALE`, `@REJECTED`, `@DATA_CONTRACT`, `@INVARIANT`. Use all belief markers.
|
||||
### C5 (Critical) — Core infrastructure with invariants and data contracts
|
||||
Adds `@DATA_CONTRACT`, `@INVARIANT`. Use all belief markers. `@RATIONALE`/`@REJECTED` are expected here for architectural decisions.
|
||||
```python
|
||||
# [DEF:rebuild_index:Function]
|
||||
# @COMPLEXITY 5
|
||||
@@ -190,12 +201,14 @@ def rebuild_index(root: Path) -> IndexSnapshot:
|
||||
### Quick reference
|
||||
| Level | Allowed tags | Forbidden tags |
|
||||
|-------|-------------|----------------|
|
||||
| C1 | only `[DEF]` | PURPOSE, RELATION, PRE, POST, SIDE_EFFECT, DATA_CONTRACT, INVARIANT, RATIONALE, REJECTED |
|
||||
| C2 | +PURPOSE | RELATION, PRE, POST, SIDE_EFFECT, DATA_CONTRACT, INVARIANT, RATIONALE, REJECTED |
|
||||
| C3 | +RELATION | PRE, POST, SIDE_EFFECT, DATA_CONTRACT, INVARIANT, RATIONALE, REJECTED |
|
||||
| C4 | +PRE, POST, SIDE_EFFECT | DATA_CONTRACT, INVARIANT, RATIONALE, REJECTED |
|
||||
| C5 | +DATA_CONTRACT, INVARIANT, RATIONALE, REJECTED | — |
|
||||
| C1 | only `[DEF]` | PURPOSE, RELATION, PRE, POST, SIDE_EFFECT, DATA_CONTRACT, INVARIANT |
|
||||
| C2 | +PURPOSE | RELATION, PRE, POST, SIDE_EFFECT, DATA_CONTRACT, INVARIANT |
|
||||
| C3 | +RELATION | PRE, POST, SIDE_EFFECT, DATA_CONTRACT, INVARIANT |
|
||||
| C4 | +PRE, POST, SIDE_EFFECT | DATA_CONTRACT, INVARIANT |
|
||||
| C5 | +DATA_CONTRACT, INVARIANT | — |
|
||||
|
||||
**Key rule:** `@RATIONALE`/`@REJECTED` are C5-only. Adding them to C1-C4 violates INV_7 (fractal limit) and dilutes real decision memory.
|
||||
**Key rule:** `@RATIONALE` / `@REJECTED` are ORTHOGONAL tags. They are NOT gated by complexity — they may appear at ANY level (C1-C5) when a node records a deliberate architectural choice. They are `protected: true` (removal requires `<ESCALATION>`). They are REQUIRED for `ADR` type contracts.
|
||||
|
||||
**Module type:** `@LAYER` and `@SEMANTICS` are REQUIRED at EVERY complexity level (C1-C5) in addition to the tags above.
|
||||
|
||||
# [/DEF:Std:Semantics:Core]
|
||||
|
||||
Reference in New Issue
Block a user