@geraldmaron/construct 1.0.5 → 1.0.7

package/rules/swift/security.md

@@ -1,5 +1,5 @@
 <!--
-rules/swift/security.md — <one-line purpose>
+rules/swift/security.md: <one-line purpose>
 
 <2–6 line summary.>
 -->
@@ -14,9 +14,9 @@ paths:
 
 ## Secret Management
 
-- Use **Keychain Services** for sensitive data (tokens, passwords, keys) — never `UserDefaults`
+- Use **Keychain Services** for sensitive data (tokens, passwords, keys): never `UserDefaults`
 - Use environment variables or `.xcconfig` files for build-time secrets
-- Never hardcode secrets in source — decompilation tools extract them trivially
+- Never hardcode secrets in source: decompilation tools extract them trivially
 
 ```swift
 let apiKey = ProcessInfo.processInfo.environment["API_KEY"]
@@ -27,7 +27,7 @@ guard let apiKey, !apiKey.isEmpty else {
 
 ## Transport Security
 
-- App Transport Security (ATS) is enforced by default — do not disable it
+- App Transport Security (ATS) is enforced by default: do not disable it
 - Use certificate pinning for critical endpoints
 - Validate all server certificates
 

package/rules/swift/testing.md

@@ -1,5 +1,5 @@
 <!--
-rules/swift/testing.md — <one-line purpose>
+rules/swift/testing.md: <one-line purpose>
 
 <2–6 line summary.>
 -->
@@ -27,7 +27,7 @@ func userCreationValidatesEmail() throws {
 
 ## Test Isolation
 
-Each test gets a fresh instance — set up in `init`, tear down in `deinit`. No shared mutable state between tests.
+Each test gets a fresh instance: set up in `init`, tear down in `deinit`. No shared mutable state between tests.
 
 ## Parameterized Tests
 

package/rules/typescript/coding-style.md

@@ -1,5 +1,5 @@
 <!--
-rules/typescript/coding-style.md — <one-line purpose>
+rules/typescript/coding-style.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/typescript/hooks.md

@@ -1,5 +1,5 @@
 <!--
-rules/typescript/hooks.md — <one-line purpose>
+rules/typescript/hooks.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/typescript/patterns.md

@@ -1,5 +1,5 @@
 <!--
-rules/typescript/patterns.md — <one-line purpose>
+rules/typescript/patterns.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/typescript/security.md

@@ -1,5 +1,5 @@
 <!--
-rules/typescript/security.md — <one-line purpose>
+rules/typescript/security.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/typescript/testing.md

@@ -1,5 +1,5 @@
 <!--
-rules/typescript/testing.md — <one-line purpose>
+rules/typescript/testing.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/web/coding-style.md

@@ -1,5 +1,5 @@
 <!--
-rules/web/coding-style.md — <one-line purpose>
+rules/web/coding-style.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/web/design-quality.md

@@ -1,5 +1,5 @@
 <!--
-rules/web/design-quality.md — <one-line purpose>
+rules/web/design-quality.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/web/hooks.md

@@ -1,5 +1,5 @@
 <!--
-rules/web/hooks.md — <one-line purpose>
+rules/web/hooks.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/web/patterns.md

@@ -1,5 +1,5 @@
 <!--
-rules/web/patterns.md — <one-line purpose>
+rules/web/patterns.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/web/performance.md

@@ -1,5 +1,5 @@
 <!--
-rules/web/performance.md — <one-line purpose>
+rules/web/performance.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/web/security.md

@@ -1,5 +1,5 @@
 <!--
-rules/web/security.md — <one-line purpose>
+rules/web/security.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/rules/web/testing.md

@@ -1,5 +1,5 @@
 <!--
-rules/web/testing.md — <one-line purpose>
+rules/web/testing.md: <one-line purpose>
 
 <2–6 line summary.>
 -->

package/scripts/sync-agents.mjs

@@ -121,6 +121,18 @@ if (validationErrors.length > 0) {
   process.exit(1);
 }
 
+// Sync-time contract validation: contracts.json shape, schema refs, and
+// producer/consumer name resolution against the registry above.
+{
+  const { validateContractsFile } = await import("../lib/contracts/validate.mjs");
+  const contractsResult = validateContractsFile();
+  if (!contractsResult.ok) {
+    console.error("Contract validation failed:");
+    for (const err of contractsResult.errors) console.error(`  - ${err}`);
+    process.exit(1);
+  }
+}
+
 // --- Dry-run + lockfile + two-phase write infrastructure ---
 
 const DRY_RUN = process.argv.includes("--dry-run");
@@ -671,9 +683,13 @@ ${agentList || "(all specialists are internal — routed through Construct)"}`;
       if (!settings.mcpServers) settings.mcpServers = {};
       const registryMcp = registry.mcpServers ?? {};
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existing = JSON.stringify(settings.mcpServers[id] ?? "");
+        const existingEntry = settings.mcpServers[id];
+        const existing = JSON.stringify(existingEntry ?? "");
         const hasPlaceholder = existing.includes("__");
-        if (settings.mcpServers[id] && !hasPlaceholder) continue;
+        const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+        const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+        const transportMismatch = registryWantsCommand && existingIsRemote;
+        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
         settings.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
       if (!DRY_RUN) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
@@ -711,8 +727,8 @@ function hasCodexMcpTable(text, id) {
   return new RegExp(`^\\[mcp_servers\\.(?:${escapeRegExp(id)}|${escapeRegExp(tomlString(id))})\\]`, "m").test(text);
 }
 
-function isCodexMcpSupported(id) {
-  return id !== "memory";
+function isCodexMcpSupported() {
+  return true;
 }
 
 function syncCodex(entries) {
@@ -834,9 +850,13 @@ function syncVSCode() {
       if (!settings["github.copilot.mcpServers"]) settings["github.copilot.mcpServers"] = {};
       const mcpServers = settings["github.copilot.mcpServers"];
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existing = JSON.stringify(mcpServers[id] ?? "");
+        const existingEntry = mcpServers[id];
+        const existing = JSON.stringify(existingEntry ?? "");
         const hasPlaceholder = existing.includes("__");
-        if (mcpServers[id] && !hasPlaceholder) continue;
+        const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+        const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+        const transportMismatch = registryWantsCommand && existingIsRemote;
+        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
         mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
       settings["github.copilot.mcpServers"] = mcpServers;
@@ -862,9 +882,13 @@ function syncCursor() {
     const config = JSON.parse(fs.readFileSync(cursorMcpPath, "utf8"));
     if (!config.mcpServers) config.mcpServers = {};
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
-      const existing = JSON.stringify(config.mcpServers[id] ?? "");
+      const existingEntry = config.mcpServers[id];
+      const existing = JSON.stringify(existingEntry ?? "");
       const hasPlaceholder = existing.includes("__");
-      if (config.mcpServers[id] && !hasPlaceholder) continue;
+      const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+      const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+      const transportMismatch = registryWantsCommand && existingIsRemote;
+      if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
       config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
     }
     if (!DRY_RUN) fs.writeFileSync(cursorMcpPath, JSON.stringify(config, null, 2) + "\n");
@@ -963,14 +987,21 @@ function syncOpencode(entries) {
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
       const openCodeId = getOpenCodeMcpId(id);
       if (openCodeId !== id) delete config.mcp[id];
-      if (id === 'memory' && config.mcp.cass && !config.mcp[openCodeId]) {
-        config.mcp[openCodeId] = config.mcp.cass;
-      }
       if (id === 'memory') delete config.mcp.cass;
-      const existing = JSON.stringify(config.mcp[openCodeId] ?? "");
-      const hasPlaceholder = existing.includes("__") && existing.includes("__");
+
+      // Migrate the legacy cass-memory HTTP entry to the stdio bridge. cm v0.2.x
+      // rejects the MCP handshake (OpenCode surfaces 405 on the SSE GET), so
+      // any remote/http memory entry must be rewritten when the registry
+      // defines a command-based bridge.
+      const existingEntry = config.mcp[openCodeId];
+      const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+      const existingIsRemote = existingEntry && (existingEntry.type === 'remote' || existingEntry.type === 'http');
+      const transportMismatch = registryWantsCommand && existingIsRemote;
+
+      const existing = JSON.stringify(existingEntry ?? "");
+      const hasPlaceholder = existing.includes("__");
       const argsHaveTemplates = (mcpDef.args ?? []).some((a) => typeof a === 'string' && a.includes('__'));
-      if (!config.mcp[openCodeId] || hasPlaceholder || argsHaveTemplates) {
+      if (!existingEntry || hasPlaceholder || argsHaveTemplates || transportMismatch) {
         config.mcp[openCodeId] = buildOpenCodeMcpEntry(id, mcpDef, process.env).entry;
       }
     }

package/skills/ai/agent-dev.md

@@ -1,5 +1,5 @@
 <!--
-skills/ai/agent-dev.md — AI Agent Development — Use this skill when building AI agents, tool-use systems, or multi-agent workflo
+skills/ai/agent-dev.md (AI Agent Development) Use this skill when building AI agents, tool-use systems, or multi-agent workflo
 
 Use this skill when building AI agents, tool-use systems, or multi-agent workflows. ## Agent Architecture
 -->

package/skills/ai/llm-security.md

@@ -1,5 +1,5 @@
 <!--
-skills/ai/llm-security.md — LLM Security — Use this skill when securing LLM-powered applications against prompt injection,
+skills/ai/llm-security.md (LLM Security) Use this skill when securing LLM-powered applications against prompt injection,
 
 Use this skill when securing LLM-powered applications against prompt injection, data leakage, and misuse. ## Prompt Injection
 -->

package/skills/ai/ml-ops.md

@@ -1,5 +1,5 @@
 <!--
-skills/ai/ml-ops.md — ML Operations (MLOps) — ```
+skills/ai/ml-ops.md (ML Operations (MLOps)) ```
 
 ## The MLOps Lifecycle ```
 -->
@@ -86,7 +86,7 @@ Central store for model versions and deployment state:
 
 | Stage | Meaning |
 |---|---|
-| Staging | Candidate — passes evaluation, not yet in production |
+| Staging | Candidate: passes evaluation, not yet in production |
 | Production | Currently serving |
 | Archived | Superseded |
 
@@ -117,7 +117,7 @@ async def predict(req: PredictRequest) -> PredictResponse:
 
 ### A/B testing / Shadow mode
 
-- **Shadow mode**: new model receives traffic and logs predictions but does not serve users — validate before switching
+- **Shadow mode**: new model receives traffic and logs predictions but does not serve users: validate before switching
 - **A/B test**: split traffic (e.g., 10% new model) and measure business metrics, not just accuracy
 - Use a feature flag system to control routing
 
@@ -162,8 +162,8 @@ Trigger retraining when:
 
 ## Common Pitfalls
 
-- **Training-serving skew**: feature engineering in training differs from serving — solve with a shared feature pipeline
-- **Data leakage**: future information in training features inflates metrics — use strict temporal splits
+- **Training-serving skew**: feature engineering in training differs from serving: solve with a shared feature pipeline
+- **Data leakage**: future information in training features inflates metrics: use strict temporal splits
 - **Model staleness without detection**: set up drift monitoring day 1, not after the model degrades
 - **No rollback plan**: always keep N-1 model version in registry and test rollback procedure
-- **GPU waste**: jobs that could run on CPU scheduled on GPU — profile resource usage
+- **GPU waste**: jobs that could run on CPU scheduled on GPU: profile resource usage

package/skills/ai/orchestration-workflow.md

@@ -1,5 +1,5 @@
 <!--
-skills/ai/orchestration-workflow.md — Construct Orchestration Workflow — Use this skill when the request involves agent orchestration, phase transitions,
+skills/ai/orchestration-workflow.md (Construct Orchestration Workflow) Use this skill when the request involves agent orchestration, phase transitions,
 
 Use this skill when the request involves agent orchestration, phase transitions, task keys, handoff quality, workflow state, or project alignment. ## Core Model
 -->

package/skills/ai/prompt-and-eval.md

@@ -1,5 +1,5 @@
 <!--
-skills/ai/prompt-and-eval.md — Prompt Engineering and Evaluation — Use this skill when designing prompts, evaluating model performance, or optimizi
+skills/ai/prompt-and-eval.md (Prompt Engineering and Evaluation) Use this skill when designing prompts, evaluating model performance, or optimizi
 
 Use this skill when designing prompts, evaluating model performance, or optimizing LLM behavior. ## Prompt Structure
 -->

package/skills/ai/prompt-optimizer.md

@@ -1,5 +1,5 @@
 <!--
-skills/ai/prompt-optimizer.md — Closed-loop prompt auto-optimization guide.
+skills/ai/prompt-optimizer.md: Closed-loop prompt auto-optimization guide.
 
 Uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer,
 and the agent registry + construct sync as the deployment layer.
@@ -24,15 +24,15 @@ construct optimize --list
 construct optimize cx-debugger --threshold=0.65 --days=14 --min-traces=15
 ```
 
-The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-install `dspy-ai` and `requests` on first run. Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in `.env`. DSPy uses the same LLM key Construct uses — no separate setup.
+The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-install `dspy-ai` and `requests` on first run. Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in `.env`. DSPy uses the same LLM key Construct uses: no separate setup.
 
 ## When to run
 
 - Triggered by `/work:optimize-prompts` (manual) or the scheduled task `prompt-optimization-weekly`
 - Automatically suggested when `cx-trace-reviewer` finds an agent with median quality score below 0.65 over the past 7 days
-- Never run optimization on prompts with fewer than 20 scored traces — insufficient signal
+- Never run optimization on prompts with fewer than 20 scored traces: insufficient signal
 
-## Step 1 — Gather signal
+## Step 1: Gather signal
 
 Retrieve the current production prompt for the target agent from `agents/registry.json` (or the corresponding `promptFile` if using extracted prompts).
 
@@ -50,7 +50,7 @@ GET {CONSTRUCT_TELEMETRY_URL}/api/public/scores?traceId={id}&name=quality
 
 Filter to scores where `value < 0.7`. For each low-scoring trace, extract: the prompt used, the user input, the model output, the quality score, and any human comments.
 
-## Step 2 — Diagnose failure patterns
+## Step 2: Diagnose failure patterns
 
 Analyze the low-scoring traces as a batch. Identify recurring failure modes. Common patterns:
 
@@ -65,16 +65,16 @@ Analyze the low-scoring traces as a batch. Identify recurring failure modes. Com
 
 Write a failure summary: top 3 patterns with supporting trace count and representative examples.
 
-## Step 3 — Generate improved prompt
+## Step 3: Generate improved prompt
 
 Write an improved prompt that directly addresses the diagnosed failures. Rules:
 
-1. **Keep what works** — compare high-scoring traces (>0.8) to low-scoring ones. Only change what's associated with failures.
-2. **Surgical edits, not rewrites** — changing everything risks breaking current strengths. Identify the specific clauses that correlate with failures.
-3. **Be explicit, not vague** — if the failure is "too verbose", add a concrete rule ("respond in under 150 words for questions that fit on one line") not a general note ("be concise").
-4. **Add a self-check instruction** — append a brief checklist the agent runs before responding, derived from the top failure patterns.
+1. **Keep what works**: compare high-scoring traces (>0.8) to low-scoring ones. Only change what's associated with failures.
+2. **Surgical edits, not rewrites**: changing everything risks breaking current strengths. Identify the specific clauses that correlate with failures.
+3. **Be explicit, not vague**: if the failure is "too verbose", add a concrete rule ("respond in under 150 words for questions that fit on one line") not a general note ("be concise").
+4. **Add a self-check instruction**: append a brief checklist the agent runs before responding, derived from the top failure patterns.
 
-## Step 4 — Push to staging
+## Step 4: Push to staging
 
 Update the agent's prompt in `agents/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
 
@@ -82,7 +82,7 @@ Log the candidate prompt as a span attribute on a test run batch using `cx_trace
 
 Do not overwrite the production prompt in the registry until promotion is confirmed.
 
-## Step 5 — Monitor staging
+## Step 5: Monitor staging
 
 After at least 20 scored traces on the staging version:
 - Compare median quality score: staging vs production
@@ -91,7 +91,7 @@ After at least 20 scored traces on the staging version:
 
 To promote: update the agent registry with the accepted prompt and run `construct sync`.
 
-## Step 6 — Document the optimization
+## Step 6: Document the optimization
 
 Write to `.cx/decisions/` with:
 - Which agent was optimized

package/skills/ai/rag-system.md

@@ -1,5 +1,5 @@
 <!--
-skills/ai/rag-system.md — RAG System Design — Use this skill when building retrieval-augmented generation pipelines, vector se
+skills/ai/rag-system.md (RAG System Design) Use this skill when building retrieval-augmented generation pipelines, vector se
 
 Use this skill when building retrieval-augmented generation pipelines, vector search, or knowledge-grounded AI systems. ## Document Processing
 -->

package/skills/architecture/api-design.md

@@ -1,5 +1,5 @@
 <!--
-skills/architecture/api-design.md — API Design — Use this skill when designing REST, GraphQL, or gRPC APIs.
+skills/architecture/api-design.md (API Design) Use this skill when designing REST, GraphQL, or gRPC APIs.
 
 Use this skill when designing REST, GraphQL, or gRPC APIs. ## REST Design Principles
 -->

package/skills/architecture/caching.md

@@ -1,5 +1,5 @@
 <!--
-skills/architecture/caching.md — Caching — Use this skill when designing caching strategies for applications, APIs, or infr
+skills/architecture/caching.md (Caching) Use this skill when designing caching strategies for applications, APIs, or infr
 
 Use this skill when designing caching strategies for applications, APIs, or infrastructure. ## Cache Layers
 -->

package/skills/architecture/cloud-native.md

@@ -1,5 +1,5 @@
 <!--
-skills/architecture/cloud-native.md — Cloud-Native Architecture — Use this skill when designing containerized, orchestrated, or microservice-based
+skills/architecture/cloud-native.md (Cloud-Native Architecture) Use this skill when designing containerized, orchestrated, or microservice-based
 
 Use this skill when designing containerized, orchestrated, or microservice-based systems. ## Container Best Practices
 -->

package/skills/architecture/message-queue.md

@@ -1,5 +1,5 @@
 <!--
-skills/architecture/message-queue.md — Message Queues and Event-Driven Architecture — Use this skill when designing asynchronous communication, event-driven systems,
+skills/architecture/message-queue.md (Message Queues and Event-Driven Architecture) Use this skill when designing asynchronous communication, event-driven systems,
 
 Use this skill when designing asynchronous communication, event-driven systems, or message-based integrations. ## When to Use Message Queues
 -->

package/skills/architecture/security-arch.md

@@ -1,5 +1,5 @@
 <!--
-skills/architecture/security-arch.md — Security Architecture — Use this skill when designing authentication, authorization, network security, o
+skills/architecture/security-arch.md (Security Architecture) Use this skill when designing authentication, authorization, network security, o
 
 Use this skill when designing authentication, authorization, network security, or zero-trust architectures. ## Zero Trust Principles
 -->

package/skills/compliance/ai-disclosure.md

@@ -1,5 +1,5 @@
 <!--
-skills/compliance/ai-disclosure.md — AI Disclosure — AI transparency, disclosure, and regulatory compliance.
+skills/compliance/ai-disclosure.md (AI Disclosure) AI transparency, disclosure, and regulatory compliance.
 
 Use this skill when reviewing AI features for disclosure requirements, transparency obligations, or emerging AI regulation compliance.
 -->

package/skills/compliance/data-privacy.md

@@ -1,5 +1,5 @@
 <!--
-skills/compliance/data-privacy.md — Data Privacy — GDPR, CCPA, and data protection compliance patterns.
+skills/compliance/data-privacy.md (Data Privacy) GDPR, CCPA, and data protection compliance patterns.
 
 Use this skill when reviewing data collection, storage, processing, or retention for privacy regulation compliance.
 -->

package/skills/compliance/license-audit.md

@@ -1,5 +1,5 @@
 <!--
-skills/compliance/license-audit.md — License Audit — Dependency license review and open-source compliance.
+skills/compliance/license-audit.md (License Audit) Dependency license review and open-source compliance.
 
 Use this skill when auditing dependency licenses, evaluating OSS compliance risk, or preparing license inventories for legal review.
 -->
@@ -24,7 +24,7 @@ Use this skill when auditing dependency licenses, evaluating OSS compliance risk
 3. Map each dependency to its SPDX license identifier
 4. Flag any dependency without a clear license file as unknown-risk
 5. Check for license changes between pinned versions and latest
-6. Look past layer one — transitive copyleft taints the whole tree
+6. Look past layer one: transitive copyleft taints the whole tree
 
 ## Red Flags
 

package/skills/compliance/regulatory-review.md

@@ -1,5 +1,5 @@
 <!--
-skills/compliance/regulatory-review.md — Regulatory Review — Pre-ship compliance review checklist and process.
+skills/compliance/regulatory-review.md (Regulatory Review) Pre-ship compliance review checklist and process.
 
 Use this skill when conducting a compliance review before shipping features that handle user data, financial transactions, AI decisions, or regulated content.
 -->

package/skills/development/cpp.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/cpp.md — C/C++ Best Practices — Use this skill when writing, reviewing, or debugging C or C++ code.
+skills/development/cpp.md (C/C++ Best Practices) Use this skill when writing, reviewing, or debugging C or C++ code.
 
 Use this skill when writing, reviewing, or debugging C or C++ code. ## Project Structure
 -->

package/skills/development/go.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/go.md — Go Best Practices — Use this skill when writing, reviewing, or debugging Go code.
+skills/development/go.md (Go Best Practices) Use this skill when writing, reviewing, or debugging Go code.
 
 Use this skill when writing, reviewing, or debugging Go code. ## Project Structure
 -->

package/skills/development/java.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/java.md — Java Best Practices — Use this skill when writing, reviewing, or debugging Java or Kotlin code on the
+skills/development/java.md (Java Best Practices) Use this skill when writing, reviewing, or debugging Java or Kotlin code on the
 
 Use this skill when writing, reviewing, or debugging Java or Kotlin code on the JVM. ## Project Structure
 -->

package/skills/development/kotlin.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/kotlin.md — Kotlin / Android Development — | Scope | Use when |
+skills/development/kotlin.md (Kotlin / Android Development) | Scope | Use when |
 
 ## Coroutines & Flows ### Coroutine scope discipline
 -->
@@ -14,7 +14,7 @@ skills/development/kotlin.md — Kotlin / Android Development — | Scope | Use
 | `viewModelScope` | ViewModel-bound work; auto-cancelled on clear |
 | `lifecycleScope` | Fragment/Activity-bound; cancelled on destroy |
 | `rememberCoroutineScope()` | Compose-scoped; cancelled on composition exit |
-| `GlobalScope` | Never — uncontrolled lifetime |
+| `GlobalScope` | Never: uncontrolled lifetime |
 
 ```kotlin
 class ItemViewModel(private val repo: ItemRepository) : ViewModel() {
@@ -31,7 +31,7 @@ class ItemViewModel(private val repo: ItemRepository) : ViewModel() {
 
 ### Flow operators
 
-- `stateIn(scope, SharingStarted.WhileSubscribed(5_000), initial)` — converts cold flow to hot StateFlow for UI consumption
+- `stateIn(scope, SharingStarted.WhileSubscribed(5_000), initial)`: converts cold flow to hot StateFlow for UI consumption
 - `map`, `filter`, `distinctUntilChanged`, `debounce` for transform chains
 - `combine` for merging multiple flows
 - Use `flowOn(Dispatchers.IO)` for upstream CPU/IO work; do not switch dispatchers in the collector
@@ -43,7 +43,7 @@ class ItemViewModel(private val repo: ItemRepository) : ViewModel() {
 | `Dispatchers.Main` | UI updates |
 | `Dispatchers.IO` | Network, disk, database |
 | `Dispatchers.Default` | CPU-intensive work |
-| `Dispatchers.Unconfined` | Rarely — only in tests |
+| `Dispatchers.Unconfined` | Rarely: only in tests |
 
 ## Jetpack Compose
 
@@ -69,7 +69,7 @@ fun ItemList(items: List<Item>, onDelete: (Item) -> Unit) { ... }
 
 - `remember` expensive computations with stable keys
 - `key(id) { ... }` in lazy lists to preserve item identity
-- Avoid unstable lambdas — use `remember { { ... } }` or stable function references
+- Avoid unstable lambdas: use `remember { { ... } }` or stable function references
 - Enable Compose compiler metrics to detect recomposition hot spots
 - Prefer `LazyColumn` over `Column` for variable-length lists
 
@@ -134,7 +134,7 @@ Scoping: `@Singleton` for app-scoped, `@ActivityRetainedScoped` for ViewModel-li
 
 ## Common Pitfalls
 
-- `collect` in `Fragment.onViewCreated` without `repeatOnLifecycle(STARTED)` — causes collection after view destruction
-- `StateFlow.value` reads in tests without collecting — use `turbine` or `runTest { first() }`
-- Leaking `Activity` context into long-lived objects — use `applicationContext`
-- `LazyColumn` with `items(list)` where `list` is `State<List<...>>` causing full recomposition — use `key` param
+- `collect` in `Fragment.onViewCreated` without `repeatOnLifecycle(STARTED)`: causes collection after view destruction
+- `StateFlow.value` reads in tests without collecting: use `turbine` or `runTest { first() }`
+- Leaking `Activity` context into long-lived objects: use `applicationContext`
+- `LazyColumn` with `items(list)` where `list` is `State<List<...>>` causing full recomposition: use `key` param

package/skills/development/mobile-crossplatform.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/mobile-crossplatform.md — Mobile Cross-Platform Development — Before choosing a framework, answer:
+skills/development/mobile-crossplatform.md (Mobile Cross-Platform Development) Before choosing a framework, answer:
 
 ## Decision Framework: Native vs Cross-Platform Before choosing a framework, answer:
 -->
@@ -13,11 +13,11 @@ Before choosing a framework, answer:
 |---|---|---|
 | Platform-specific APIs needed (ARKit, Health, NFC)? | Yes | No |
 | Animation fidelity is a differentiator? | Yes | Partial |
-| Single team, both platforms? | — | Yes |
+| Single team, both platforms? |: | Yes |
 | Heavy use of platform OS widgets? | Yes | No |
-| App is primarily data-display / CRUD? | — | Yes |
-| Existing web team? | — | React Native |
-| Existing Kotlin/Swift team? | Native | — |
+| App is primarily data-display / CRUD? |: | Yes |
+| Existing web team? |: | React Native |
+| Existing Kotlin/Swift team? | Native |: |
 
 ---
 
@@ -42,7 +42,7 @@ Future<List<Item>> items(ItemsRef ref) async {
 
 ### Performance
 
-- `const` constructors everywhere possible — eliminates widget rebuilds
+- `const` constructors everywhere possible: eliminates widget rebuilds
 - `RepaintBoundary` around independently-animated subtrees
 - Profile with Flutter DevTools → CPU flame chart + widget rebuild tracker
 - `ListView.builder` for lazy lists; never `ListView(children: [...])` for long lists
@@ -78,8 +78,8 @@ testWidgets('shows items on load', (tester) async {
 ### New Architecture (React Native 0.74+)
 
 Enable the New Architecture by default on new projects. Key changes:
-- JSI replaces the async bridge — sync native calls
-- Fabric replaces the native renderer — concurrent React features work correctly
+- JSI replaces the async bridge: sync native calls
+- Fabric replaces the native renderer: concurrent React features work correctly
 - TurboModules replace native modules
 
 ### State & logic sharing with web
@@ -130,11 +130,11 @@ export default function ItemScreen() { ... }
 
 ## Common Pitfalls (both frameworks)
 
-- **Deep linking not tested until late** — set up universal links / app links in week 1
-- **Push notifications complexity** — Expo Notifications or Firebase Cloud Messaging; plan for permission states
-- **Over-the-air update strategy** — define what can be OTA vs what requires App Store review
-- **Platform capability divergence** — features available on iOS 17+ may be absent on Android 12; maintain a capability matrix
-- **Code signing automation** — `fastlane match` (iOS) and keystore management (Android) require upfront investment; do it early
+- **Deep linking not tested until late**: set up universal links / app links in week 1
+- **Push notifications complexity**: Expo Notifications or Firebase Cloud Messaging; plan for permission states
+- **Over-the-air update strategy**: define what can be OTA vs what requires App Store review
+- **Platform capability divergence**: features available on iOS 17+ may be absent on Android 12; maintain a capability matrix
+- **Code signing automation**: `fastlane match` (iOS) and keystore management (Android) require upfront investment; do it early
 
 ## When to go native anyway
 

package/skills/development/python.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/python.md — Python Best Practices — Use this skill when writing, reviewing, or debugging Python code.
+skills/development/python.md (Python Best Practices) Use this skill when writing, reviewing, or debugging Python code.
 
 Use this skill when writing, reviewing, or debugging Python code. ## Project Structure
 -->