skills

.opencode/agents/python-coder.md

@@ -34,7 +34,7 @@ Your attention mechanism compresses context in a hybrid pipeline (see `semantics
 
 4. **Copy‑paste regression.** You see similar code → copy it. If the original had `@REJECTED fallback to SQLite` but HCA 128× erased those tokens from your attention, you silently re‑implement the forbidden path. `@REJECTED` in the anchor header is a dense token that survives all compression layers.
 
-**This project now:** 3658 contracts, 1627 orphans (44%), 206 unresolved edges. Every orphan contract is invisible to the DSA Indexer — the attention pipeline literally cannot route queries to it.
+**Pre-training note:** `#region`, `@brief`, `@see` appear millions of times in training — you recognize them natively. `@RATIONALE`, `@REJECTED`, `@DATA_CONTRACT`, `@RELATION` are **custom tags learned only through in-context examples in this prompt and loaded skills.** Every `@RATIONALE` you read in a code contract is in-context fine-tuning. Consistency is paramount: planner-generated format must match implementation format.
 
 ## Protocol Reference
 Load and follow these skills (MANDATORY):

.opencode/command/speckit.plan.md

@@ -184,28 +184,27 @@ Generate its full `#region` header in `contracts/modules.md` under its parent mo
 **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]
+# @ingroup Domain
+# @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.
+# @ingroup Domain
+# @BRIEF One-line purpose.
+# @PRE Precondition 1 (verifiable by guard clause).
+# @POST Output guarantee 1 (testable assertion).
+# @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.
 ```
 
 **Screen Model actions (Svelte `.svelte.ts`):**

.opencode/skills/semantics-core/SKILL.md

@@ -18,6 +18,52 @@ description: Reference manual for GRACE-Poly v2.6 — syntax formats, complexity
 
 **Agent prompts are thin shims:** they describe the agent's role, cognitive frame (specific failure modes for their stack), verification commands, and escalation format. They do NOT redefine tiers, tags, or syntax. Agent-specific cognitive framing lives in each agent's prompt and is not duplicated here.
 
+### 0.1 Pre-Training Frequency & Tag Familiarity
+
+Not all GRACE tags are equal in the model's training data. Understanding which tags the model has seen millions of times vs. which it learns only through in-context examples is critical for protocol design.
+
+#### Pre-training native (Doxygen/JSDoc — millions of examples)
+
+| Tag | Doxygen/JSDoc equivalent | Training context |
+|-----|-------------------------|-----------------|
+| `@BRIEF` | `@brief` | All C/C++/Python/Rust Doxygen projects, all JS/TS JSDoc projects |
+| `@defgroup` | `@defgroup GroupName Description` | Module-level grouping in Doxygen (LLVM, OpenCV, ROS) |
+| `@ingroup` | `@ingroup GroupName` | Child membership in Doxygen groups |
+| `@see` | `@see`, `@sa` | Cross-references — the model's native link mechanism |
+| `@deprecated` | `@deprecated` | Deprecation markers in Doxygen and JSDoc |
+| `@note`, `@warning` | `@note`, `@warning` | Advisory annotations |
+
+**Rule:** These tags trigger pre-trained recognition. Use them as structural anchors. `@defgroup` on modules + `@ingroup` on children is the strongest domain-grouping signal the model natively understands.
+
+#### Pre-training weak (formal verification — thousands of examples)
+
+| Tag | Context | Model recognition |
+|-----|---------|-------------------|
+| `@PRE` | Eiffel, Ada 2012, JML, ACSL | Understands "precondition" but not in documentation context |
+| `@POST` | Eiffel, Ada 2012, JML, ACSL | Understands "postcondition" — weaker signal than `@brief` |
+| `@INVARIANT` | Eiffel, Dafny, formal methods | Understands the word — but Doxygen `@invariant` is for formal verification, not general docs |
+
+**Rule:** These have semantic recognition from the word itself, but weak pre-training. Examples in agent prompts accelerate learning.
+
+#### Pure in-context learning (zero pre-training examples)
+
+| Tag | Closest pre-training analog | Why it's custom |
+|-----|---------------------------|-----------------|
+| `@RATIONALE` | `@note` | No documentation system has "architectural decision rationale" as a tag |
+| `@REJECTED` | `@deprecated` (for removed), `@warning` | No system records "considered and rejected alternative" |
+| `@SIDE_EFFECT` | None | No documentation system tags side effects explicitly |
+| `@DATA_CONTRACT` | `@param` / `@returns` | No system has "DTO mapping Input→Output" as a tag |
+| `@RELATION` | `@see` (link only) | No system has typed edges with predicates (DEPENDS_ON, CALLS...) |
+| `@UX_STATE` | None | UX state machines exist in no documentation system |
+| `@UX_FEEDBACK` | None | — |
+| `@UX_RECOVERY` | None | — |
+| `@UX_REACTIVITY` | None | — |
+| `@UX_TEST` | `@test` (Doxygen) | Doxygen's `@test` is for test cases, not UX interaction scenarios |
+| `@TEST_EDGE` | None | Edge case documentation exists nowhere |
+| `@TEST_INVARIANT` | None | — |
+
+**Rule:** Every appearance of these tags in agent prompts and skill examples is **critical training material.** The model has zero pre-trained knowledge of their format. Consistency across planner → coder → QA examples is paramount — deviation in one agent creates confusion in all others. In-context examples MUST be canonical and unchanging.
+
 ## I. GLOBAL INVARIANTS (specification)
 
 - **[INV_1]:** Every function, class, and module MUST have a `#region`/`#endregion` contract. Naked code is unreviewable.
@@ -33,13 +79,22 @@ description: Reference manual for GRACE-Poly v2.6 — syntax formats, complexity
 
 ### Primary — Region (recommended for Python, JS/TS, Rust)
 ```python
-# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tag1,tag2]
+# #region Domain.Name [C:N] [TYPE Module] [SEMANTICS tag1,tag2]
+# @defgroup Domain One-line description of this domain.   # ← groups children + serves as @BRIEF
+# @RELATION ...
+
+# #region Domain.Name.Action [C:N] [TYPE Function] [SEMANTICS domain,action]
+# @ingroup Domain
 # @BRIEF One-line description
 # @RELATION PREDICATE -> [TargetId]
-<code — this is what the contract wraps>
-# #endregion ContractId
+<code>
+# #endregion Domain.Name.Action
+
+# #endregion Domain.Name
 ```
 
+**Module contracts:** `@defgroup` replaces `@BRIEF` — it declares the group AND describes what the domain does. Child contracts: `@ingroup` on line 2 joins the group; `@BRIEF` on line 3 describes the specific contract.
+
 ### Legacy — DEF (permanently recognized)
 ```python
 // [DEF:ContractId:Type]
@@ -200,13 +255,26 @@ Contract IDs MUST use dot-separated domain prefixes with 2-3 levels of hierarchy
 
 ### ATTN_3 — SEMANTIC GROUPING (DSA Lightning Indexer)
 
-The DSA Indexer scores compressed records by keyword match against the query. `@SEMANTICS` keywords are your index keys:
+The DSA Indexer scores compressed records by keyword match against the query. Two complementary mechanisms:
 
+**`[SEMANTICS ...]` in anchor (CSA 4× density):**
 - All contracts in the `auth` domain MUST share `[SEMANTICS auth, ...]`.
 - `grep "@SEMANTICS.*auth"` → Indexer scores all auth records high.
-- If one auth contract uses `@SEMANTICS login` and another `@SEMANTICS authentication`, the Indexer may fail to group them.
+- If one auth contract uses `[SEMANTICS login]` and another `[SEMANTICS authentication]`, the Indexer may fail to group them.
 
-**Rule:** Identical domain = identical primary keyword in `@SEMANTICS`. Secondary keywords can vary.
+**`@ingroup Domain` on line 2 (HCA 128× pre-training):**
+- The model has seen `@ingroup` in Doxygen millions of times as a grouping mechanism.
+- Adding `@ingroup Auth` on line 2 (after the anchor) provides pre-training-recognized DSA grouping.
+- **Recommended for all new C3+ contracts.** Not required for C1/C2 inside a parent module with `@ingroup`.
+
+Example — both mechanisms reinforce each other:
+```
+#region Core.Auth.Login [C:4] [TYPE Function] [SEMANTICS auth,login,token]
+# @ingroup Auth
+# @BRIEF Authenticate user by credentials.
+```
+
+**Rule:** Identical domain = identical primary keyword in `[SEMANTICS ...]` AND identical `@ingroup Domain`. They target different compression layers (CSA vs HCA) and don't conflict — the keyword repetition amplifies the DSA score.
 
 ### ATTN_4 — FRACTAL BOUNDARIES (Sliding Window)
 
@@ -224,6 +292,9 @@ When Axiom MCP is down, these grep patterns exploit the DSA Indexer's keyword se
 # Find all contracts in a domain (Indexer matches @SEMANTICS keywords)
 grep -r "@SEMANTICS.*<domain>" src/
 
+# Find all contracts in a @defgroup (pre-training-recognized Doxygen pattern)
+grep -r "@ingroup.*<group>" src/
+
 # Find API type binding (cross-stack traceability)
 grep -r "@DATA_CONTRACT.*<ModelName>" src/
 
@@ -232,6 +303,9 @@ awk '/#region <ContractID>/,/#endregion <ContractID>/' file.py
 
 # Find all contracts BIND_TO a store
 grep -r "BINDS_TO.*\[<StoreId>\]" src/
+
+# Find cross-references by @see (pre-training-recognized — alternative to @RELATION for simple links)
+grep -r "@see.*<ContractID>" src/
 ```
 
 #endregion Std.Semantics.Core

.opencode/skills/semantics-python/SKILL.md

@@ -81,10 +81,11 @@ def format_timestamp(ts: datetime) -> str:
 ### C3 (Flow) — Module with nested functions, service layer
 ```python
 # #region Migration.Dashboard [C:3] [TYPE Module] [SEMANTICS migration,dashboard]
-# @BRIEF Dashboard migration service — export/import dashboards with validation.
+# @defgroup Migration Dashboard export/import with validation.
 # @LAYER Service
 
 # #region Migration.Dashboard.Migrate [C:3] [TYPE Function] [SEMANTICS migration,dashboard]
+# @ingroup Migration
 # @BRIEF Migrate a single dashboard from source to target Superset instance.
 # @RELATION DEPENDS_ON -> [SupersetClient]
 # @RELATION DEPENDS_ON -> [DashboardValidator]
@@ -102,6 +103,7 @@ def migrate_dashboard(source_client, target_client, dashboard_id: str, db_mappin
 ### C4 (Orchestration) — Stateful operations with belief runtime
 ```python
 # #region Migration.RunTask [C:4] [TYPE Function] [SEMANTICS migration,task,state]
+# @ingroup Migration
 # @BRIEF Execute a full migration task with rollback capability and progress reporting.
 # @PRE Database connection is established. Task record exists with valid migration plan.
 # @POST Task status updated to COMPLETED or FAILED. Migration audit log written.
@@ -139,6 +141,7 @@ async def run_migration_task(task_id: str, db_session) -> dict:
 ### C5 (Critical) — With decision memory
 ```python
 # #region Index.Rebuild [C:5] [TYPE Function] [SEMANTICS indexing,recovery,semantic]
+# @ingroup Index
 # @BRIEF Rebuild the full semantic index from source with atomic swap and rollback.
 # @PRE Workspace root is accessible. Source files exist.
 # @POST New index atomically swapped; old preserved for rollback.

.opencode/skills/semantics-svelte/SKILL.md

@@ -91,6 +91,7 @@ Models use the **`.svelte.ts`** extension (not plain `.ts`) because they rely on
 ```typescript
 // frontend/src/lib/models/UsersListModel.svelte.ts
 // #region Users.ListModel [C:4] [TYPE Model] [SEMANTICS users,list,screen-model]
+// @ingroup Users
 // @BRIEF State model for the user list screen — declares atoms, invariants, and actions.
 // @INVARIANT Changing filter (search, role, status) resets pagination to page 1.
 // @INVARIANT Deleting a user removes it from the list and decrements total count atomically.