From e916cb1f1707fa19812ee49b3787524330d7d40c Mon Sep 17 00:00:00 2001 From: busya Date: Mon, 16 Mar 2026 23:55:42 +0300 Subject: [PATCH] speckit update --- .kilocode/workflows/speckit.implement.md | 39 ++++++++++++++++++++---- .kilocode/workflows/speckit.test.md | 31 ++++++++++++++++--- 2 files changed, 59 insertions(+), 11 deletions(-) diff --git a/.kilocode/workflows/speckit.implement.md b/.kilocode/workflows/speckit.implement.md index a23645b8..dffe062d 100644 --- a/.kilocode/workflows/speckit.implement.md +++ b/.kilocode/workflows/speckit.implement.md @@ -122,11 +122,20 @@ You **MUST** consider the user input before proceeding (if not empty). 7. Implementation execution rules: - **Strict Adherence**: Apply `.ai/standards/semantics.md` rules: - - Every file MUST start with a `[DEF:id:Type]` header and end with a closing `[/DEF:id:Type]` anchor. - - Include `@TIER` and define contracts (`@PRE`, `@POST`). - - For Svelte components, use `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, and explicitly declare reactivity with `@UX_REATIVITY: State: $state, Derived: $derived`. - - **Molecular Topology Logging**: Use prefixes `[EXPLORE]`, `[REASON]`, `[REFLECT]` in logs to trace logic. + - Every file MUST start with a `[DEF:id:Type]` header and end with a matching closing `[/DEF:id:Type]` anchor. + - Use `@COMPLEXITY` / `@C:` as the primary control tag; treat `@TIER` only as legacy compatibility metadata. + - Contract density MUST match effective complexity from [`.ai/standards/semantics.md`](.ai/standards/semantics.md): + - Complexity 1: anchors only. + - Complexity 2: require `@PURPOSE`. + - Complexity 3: require `@PURPOSE` and `@RELATION`. + - Complexity 4: require `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`. + - Complexity 5: require full level-4 contract plus `@DATA_CONTRACT` and `@INVARIANT`. + - For Python Complexity 4+ modules, implementation MUST include a meaningful semantic logging path using `logger.reason()` and `logger.reflect()`. + - For Python Complexity 5 modules, `belief_scope(...)` is mandatory and the critical path must be irrigated with `logger.reason()` / `logger.reflect()` according to the contract. + - For Svelte components, require `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, and `@UX_REACTIVITY`; runes-only reactivity is allowed (`$state`, `$derived`, `$effect`, `$props`). + - Reject pseudo-semantic markup: docstrings containing loose `@PURPOSE` / `@PRE` text do **NOT** satisfy the protocol unless represented in canonical anchored metadata blocks. - **Self-Audit**: The Coder MUST use `axiom-core` tools (like `audit_contracts_tool`) to verify semantic compliance before completion. + - **Semantic Rejection Gate**: If self-audit reveals broken anchors, missing closing tags, missing required metadata for the effective complexity, orphaned critical classes/functions, or Complexity 4/5 Python code without required belief-state logging, the task is NOT complete and cannot be handed off as accepted work. - **CRITICAL Contracts**: If a task description contains a contract summary (e.g., `CRITICAL: PRE: ..., POST: ...`), these constraints are **MANDATORY** and must be strictly implemented in the code using guards/assertions (if applicable per protocol). - **Setup first**: Initialize project structure, dependencies, configuration - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios @@ -144,23 +153,41 @@ You **MUST** consider the user input before proceeding (if not empty). 9. **Handoff to Tester (Audit Loop)**: - Once a task or phase is complete, the Coder hands off to the Tester. - - Handoff includes: File paths, expected contracts (@PRE/@POST), and logic overview. + - Handoff includes: file paths, declared complexity, expected contracts (`@PRE`, `@POST`, `@SIDE_EFFECT`, `@DATA_CONTRACT`, `@INVARIANT` when applicable), and a short logic overview. + - Handoff MUST explicitly disclose any contract exceptions or known semantic debt. Hidden semantic debt is forbidden. + - The handoff payload MUST instruct the Tester to execute the dedicated testing workflow [`.kilocode/workflows/speckit.test.md`](.kilocode/workflows/speckit.test.md), not just perform an informal review. 10. **Tester Verification & Orchestrator Gate**: - Tester MUST: + - Explicitly run the [`.kilocode/workflows/speckit.test.md`](.kilocode/workflows/speckit.test.md) workflow as the verification procedure for the delivered implementation batch. - Perform mandatory semantic audit (using `audit_contracts_tool`). + - Reject code that only imitates the protocol superficially, such as free-form docstrings with `@PURPOSE` text but without canonical `[DEF]...[/DEF]` anchors and header metadata. + - Verify that effective complexity and required metadata match [`.ai/standards/semantics.md`](.ai/standards/semantics.md). + - Verify that Python Complexity 4/5 implementations include required belief-state instrumentation (`belief_scope`, `logger.reason()`, `logger.reflect()`). - Emulate algorithms "in mind" step-by-step to ensure logic consistency. - Verify unit tests match the declared contracts. - If Tester finds issues: - - Emit `[AUDIT_FAIL: reason]` and notify the Orchestrator. + - Emit `[AUDIT_FAIL: semantic_noncompliance | contract_mismatch | logic_mismatch | test_mismatch | speckit_test_not_run]`. + - Provide concrete file-path-based reasons, for example: missing anchors, module/class contract mismatch, missing `@DATA_CONTRACT`, missing `logger.reason()`, illegal docstring-only annotations, or missing execution of [`.kilocode/workflows/speckit.test.md`](.kilocode/workflows/speckit.test.md). + - Notify the Orchestrator. - Orchestrator redirects the feedback to the Coder for remediation. + - Orchestrator green-status rule: + - The Orchestrator MUST NOT assign green/accepted status unless the Tester confirms that [`.kilocode/workflows/speckit.test.md`](.kilocode/workflows/speckit.test.md) was executed. + - Missing execution evidence for [`.kilocode/workflows/speckit.test.md`](.kilocode/workflows/speckit.test.md) is an automatic gate failure even if the Tester verbally reports that the code "looks fine". - Acceptance (Final mark [X]): - Only after the Tester is satisfied with semantics, emulation, and tests. + - Any semantic audit warning relevant to touched files blocks acceptance until remediated or explicitly waived by the user. + - No final green status is allowed without explicit confirmation that [`.kilocode/workflows/speckit.test.md`](.kilocode/workflows/speckit.test.md) was run. 11. Completion validation: - Verify all required tasks are completed and accepted by the Tester. - Check that implemented features match the original specification. - Confirm the implementation follows the technical plan and GRACE standards. + - Confirm touched files do not contain protocol-invalid patterns such as: + - class/function-level docstring contracts standing in for canonical anchors, + - missing closing anchors, + - missing required metadata for declared complexity, + - Complexity 5 repository/service code using only `belief_scope(...)` without explicit `logger.reason()` / `logger.reflect()` checkpoints. - Report final status with summary of completed and audited work. Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list. diff --git a/.kilocode/workflows/speckit.test.md b/.kilocode/workflows/speckit.test.md index 7518ca56..0af9ecfb 100644 --- a/.kilocode/workflows/speckit.test.md +++ b/.kilocode/workflows/speckit.test.md @@ -60,11 +60,18 @@ Create coverage matrix: Before writing tests, the Tester MUST: 1. **Run `axiom-core.audit_contracts_tool`**: Identify semantic violations. -2. **Emulate Algorithm**: Step through the code implementation in mind. +2. **Run a protocol-shape review on touched files**: + - Reject non-canonical semantic markup, including docstring-only annotations such as `@PURPOSE`, `@PRE`, or `@INVARIANT` written inside class/function docstrings without canonical `[DEF]...[/DEF]` anchors and header metadata. + - Reject files whose effective complexity contract is under-specified relative to [`.ai/standards/semantics.md`](.ai/standards/semantics.md). + - Reject Python Complexity 4+ modules that omit meaningful `logger.reason()` / `logger.reflect()` checkpoints. + - Reject Python Complexity 5 modules that omit `belief_scope(...)`, `@DATA_CONTRACT`, or `@INVARIANT`. + - Treat broken or missing closing anchors as blocking violations. +3. **Emulate Algorithm**: Step through the code implementation in mind. - Verify it adheres to the `@PURPOSE` and `@INVARIANT`. - Verify `@PRE` and `@POST` conditions are correctly handled. -3. **Validation Verdict**: - - If audit fails: Emit `[AUDIT_FAIL: reason]` and notify Orchestrator. +4. **Validation Verdict**: + - If audit fails: Emit `[AUDIT_FAIL: semantic_noncompliance]` with concrete file-path reasons and notify Orchestrator. + - Example blocking case: [`backend/src/services/dataset_review/repositories/session_repository.py`](backend/src/services/dataset_review/repositories/session_repository.py) contains a module anchor, but its nested repository class/method semantics are expressed as loose docstrings instead of canonical anchored contracts; this MUST be rejected until remediated or explicitly waived. - If audit passes: Proceed to writing/verifying tests. ### 5. Write Tests (TDD Approach) @@ -73,10 +80,13 @@ For each module requiring tests: 1. **Check existing tests**: Scan `__tests__/` for duplicates. 2. **Read TEST_FIXTURE**: If CRITICAL tier, read @TEST_FIXTURE from semantics header. -3. **Write test**: Follow co-location strategy. +3. **Do not normalize broken semantics through tests**: + - The Tester must not write tests that silently accept malformed semantic protocol usage. + - If implementation is semantically invalid, stop and reject instead of adapting tests around the invalid structure. +4. **Write test**: Follow co-location strategy. - Python: `src/module/__tests__/test_module.py` - Svelte: `src/lib/components/__tests__/test_component.test.js` -4. **Use mocks**: Use `unittest.mock.MagicMock` for external dependencies +5. **Use mocks**: Use `unittest.mock.MagicMock` for external dependencies ### 4a. UX Contract Testing (Frontend Components) @@ -173,6 +183,16 @@ Generate test execution report: - Failed: [X] - Skipped: [X] +## Semantic Audit Verdict + +- Verdict: PASS | FAIL +- Blocking Violations: + - [file path] -> [reason] +- Notes: + - Reject docstring-only semantic pseudo-markup + - Reject complexity/contract mismatches + - Reject missing belief-state instrumentation for Python Complexity 4/5 + ## Issues Found | Test | Error | Resolution | @@ -182,6 +202,7 @@ Generate test execution report: ## Next Steps - [ ] Fix failed tests +- [ ] Fix blocking semantic violations before acceptance - [ ] Add more coverage for [module] - [ ] Review TEST_FIXTURE fixtures ```