@geraldmaron/construct 1.0.4 → 1.0.6

package/platforms/claude/settings.template.json

@@ -460,6 +460,19 @@
         ],
         "id": "stop:optimize-agents",
         "description": "Check performance reviews and auto-optimize low-scoring agents at session end"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/session-reflect.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ],
+        "id": "stop:auto-reflect",
+        "description": "Deterministic session-end reflect: extracts a transcript summary into .cx/observations (500ms hard budget; CONSTRUCT_REFLECT_AUTO=off to disable)"
       }
     ],
     "UserPromptSubmit": [

package/rules/common/agents.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/agents.md — platform-agnostic agent orchestration guidance.
+rules/common/agents.md: platform-agnostic agent orchestration guidance.
 
 Defines when to route to specialist agents, parallel execution rules,
 and multi-perspective analysis patterns. Does not reference specific
@@ -9,7 +9,7 @@ platform agent types or config paths.
 
 ## Immediate Agent Usage
 
-No user prompt needed — match the task to the right specialist:
+No user prompt needed: match the task to the right specialist:
 1. Complex feature requests - planning specialist
 2. Code just written/modified - code review specialist
 3. Bug fix or new feature - TDD specialist

package/rules/common/beads-hygiene.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/beads-hygiene.md — Beads issue tracker hygiene contract.
+rules/common/beads-hygiene.md: Beads issue tracker hygiene contract.
 
 Beads is the system of record for durable work in this project. Status drifts
 when issues are not updated alongside the code, so every agent and persona
@@ -7,16 +7,16 @@ operating in Construct treats hygiene as part of the work, not as cleanup.
 Loaded by AGENTS.md, CLAUDE.md, the construct persona, and the engineer /
 operator / planner role overlays.
 -->
-# Beads Hygiene — Project Contract
+# Beads Hygiene: Project Contract
 
-Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn their keep when their state matches the world. Stale "open" issues pollute `bd ready`, hide real work, and let agents propose work that already shipped. Every agent — human or AI, on any platform — is responsible for keeping the tracker honest.
+Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn their keep when their state matches the world. Stale "open" issues pollute `bd ready`, hide real work, and let agents propose work that already shipped. Every agent (human or AI, on any platform) is responsible for keeping the tracker honest.
 
 ## When to update beads
 
 | Event | Required action |
 |---|---|
 | About to start non-trivial work | A Beads issue exists. `bd ready` to find or `bd create` if missing. `bd update <id> --claim` before edits. |
-| Work lands on `main` | `bd close <id> --reason="Landed in PR #N — verified: <file:line evidence>"`. Do not wait for someone else to notice. |
+| Work lands on `main` | `bd close <id> --reason="Landed in PR #N. Verified: <file:line evidence>"`. Do not wait for someone else to notice. |
 | Direction reverses mid-work | `bd supersede <old-id> --with=<new-id>`. Do not edit the old description in place. |
 | Issue scope expands | Update the description and acceptance criteria in the same change that broadens scope. |
 | A blocker is discovered | Add the dependency with `bd dep add <id> <depends-on>` so the readiness queue reflects reality. |
@@ -27,10 +27,10 @@ Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn the
 
 Run before planning, before claiming work, before proposing changes:
 
-1. `bd ready` — surface unblocked work.
-2. `bd list --status=in_progress` — verify nothing has been left mid-flight by an earlier session.
-3. `bd stale` — surface anything untouched past the staleness window.
-4. Cross-check the open list against `git log --oneline -20 origin/main` — close anything whose work actually landed.
+1. `bd ready`: surface unblocked work.
+2. `bd list --status=in_progress`: verify nothing has been left mid-flight by an earlier session.
+3. `bd stale`: surface anything untouched past the staleness window.
+4. Cross-check the open list against `git log --oneline -20 origin/main`: close anything whose work actually landed.
 
 If any of these surface drift, fix it before starting new work. Drift you observe and ignore becomes drift the next agent inherits.
 
@@ -40,14 +40,14 @@ After the code changes land in main:
 
 1. The bead the work was claimed against is closed with evidence in the reason.
 2. Any beads superseded by the change are marked superseded, not left open.
-3. New beads exist for follow-up work that was discovered but not done — file them in the same session, not "later".
+3. New beads exist for follow-up work that was discovered but not done: file them in the same session, not "later".
 4. `bd doctor` and `bd preflight` should run before push and report clean.
 
 ## What goes in a bead
 
 | Field | Standard |
 |---|---|
-| Title | Imperative, scoped, parseable. "PR 3 — `construct intake` CLI" beats "intake CLI". |
+| Title | Imperative, scoped, parseable. "PR 3: `construct intake` CLI" beats "intake CLI". |
 | Description | Why the bead exists + what success looks like. State the new shape directly. Do not preserve a "current behavior must keep working" goal unless the user explicitly asked for migration. |
 | Acceptance criteria | Numbered, binary checks. A reviewer can answer pass/fail without re-reading the description. |
 | Dependencies | Wire `bd dep add` whenever order matters. Implicit ordering rots into parallel work that breaks each other. |
@@ -72,4 +72,4 @@ There is no authorized bypass. Beads hygiene is a release gate. If the tooling i
 
 ## Automation
 
-Project-level automation is tracked in the beads queue — auto-close on merge, pre-push `bd preflight` gate, weekly drift report, memory-contradiction detection. Until that ships, hygiene is a per-session discipline.
+Project-level automation is tracked in the beads queue: auto-close on merge, pre-push `bd preflight` gate, weekly drift report, memory-contradiction detection. Until that ships, hygiene is a per-session discipline.

package/rules/common/code-review.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/code-review.md — when and how to conduct code reviews.
+rules/common/code-review.md: when and how to conduct code reviews.
 
 Defines mandatory review triggers, severity levels, approval criteria,
 and references coding-style.md and security.md for checklists.

package/rules/common/coding-style.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/coding-style.md — language-agnostic coding standards.
+rules/common/coding-style.md: language-agnostic coding standards.
 
 Covers immutability, core principles (KISS/DRY/YAGNI), file organization,
 error handling, input validation, naming conventions, and quality checklist.

package/rules/common/comments.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/comments.md — Construct comment convention for JS/TS/MJS source files.
+rules/common/comments.md: Construct comment convention for JS/TS/MJS source files.
 
 Defines the two allowed comment forms (file header, section context block) and
 what is never allowed (inline narration, trailing comments, mid-function notes).
@@ -37,12 +37,12 @@ The blank line between the comment and the code is required. It signals "this co
 
 ## What is never allowed
 
-- **Inline trailing comments** — `const x = 1; // increment` — delete them
-- **Mid-function narration** — a comment in the middle of a function body that describes what the next line does — delete it; rename the variable or extract a function instead
-- **Between-group labels** — `// Language patterns`, `// Dashboard`, `// Step 1:` — delete them
-- **Narrative voice** — `// We weight BM25`, `// Now test the keys`, `// This correctly scores` — delete them
-- **Point-in-time notes** — `// X removed`, `// previously`, `// no longer` — belongs in git log
-- **Noise sentinels** — `// ok`, `// best effort`, `// skip` — delete them; use `/* non-critical */` inline only when the catch clause would otherwise look like a bug
+- **Inline trailing comments** (`const x = 1; // increment`) delete them
+- **Mid-function narration** (a comment in the middle of a function body that describes what the next line does) delete it; rename the variable or extract a function instead
+- **Between-group labels** (`// Language patterns`, `// Dashboard`, `// Step 1:`) delete them
+- **Narrative voice** (`// We weight BM25`, `// Now test the keys`, `// This correctly scores`) delete them
+- **Point-in-time notes** (`// X removed`, `// previously`, `// no longer`) belongs in git log
+- **Noise sentinels** (`// ok`, `// best effort`, `// skip`) delete them; use `/* non-critical */` inline only when the catch clause would otherwise look like a bug
 
 ## SLA annotations (hooks only)
 
@@ -54,5 +54,5 @@ The blank line between the comment and the code is required. It signals "this co
 
 ## Rule of thumb
 
-Delete the comment. If the section becomes harder to understand, the comment earns its place — as a block before it, with a blank line after. If it reads just as clearly without, it stays deleted.
+Delete the comment. If the section becomes harder to understand, the comment earns its place: as a block before it, with a blank line after. If it reads just as clearly without, it stays deleted.
 

package/rules/common/commit-approval.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/commit-approval.md — conversational approval rule for mutating git operations.
+rules/common/commit-approval.md: conversational approval rule for mutating git operations.
 
 Behavioral rule, not a hook. The agent asks and waits for a yes; the user
 replies in chat. Infrastructure stays out of the way.
@@ -19,7 +19,7 @@ Before running any of these Bash tool calls:
 The agent must:
 
 1. **State the working branch** so the user sees the scope.
-2. **Show the proposed action verbatim** — for a commit, the full proposed message (subject and body) formatted exactly as it will appear in `git log`. For a push, the target refspec. For a merge, the PR number and merge mode (`--squash`, `--rebase`, etc.).
+2. **Show the proposed action verbatim**: for a commit, the full proposed message (subject and body) formatted exactly as it will appear in `git log`. For a push, the target refspec. For a merge, the PR number and merge mode (`--squash`, `--rebase`, etc.).
 3. **Ask for confirmation** and wait for a yes before executing.
 
 A yes from the user in chat is the approval. No marker file, no CLI command, no special syntax.
@@ -41,13 +41,13 @@ Then stop and wait.
 
 ## Exceptions
 
-- **The user explicitly tells the agent to run a defined sequence** ("commit, push, and merge when ready"). That single yes covers the named batch — but only the actions named, in the order named. A new commit triggered later (e.g. by a CI fix or follow-up edit) is its own approval gate.
+- **The user explicitly tells the agent to run a defined sequence** ("commit, push, and merge when ready"). That single yes covers the named batch: but only the actions named, in the order named. A new commit triggered later (e.g. by a CI fix or follow-up edit) is its own approval gate.
 - **Read-only git operations** (`git status`, `git log`, `git diff`, `git fetch`, `git branch`, `git show`) don't need approval.
 
 A "yes" from earlier in the session does NOT carry forward to subsequent commits. Each new commit message must be shown and approved.
 
 ## Why this is a rule, not a hook
 
-A hook that blocked every commit turned out to be over-restrictive — it required a separate command invocation to write a marker file each time, which added friction without much safety beyond the agent just following the rule. The agent is the one producing commit messages; asking in chat is the right interface.
+A hook that blocked every commit turned out to be over-restrictive: it required a separate command invocation to write a marker file each time, which added friction without much safety beyond the agent just following the rule. The agent is the one producing commit messages; asking in chat is the right interface.
 
 If the agent ever commits without asking, that's a correctness bug. Surface it in the session and raise a follow-up to catch the regression.

package/rules/common/cx-agent-routing.md

@@ -1,11 +1,11 @@
 <!--
-rules/common/cx-agent-routing.md — auto-trigger routing rules for cx-* specialist agents.
+rules/common/cx-agent-routing.md: auto-trigger routing rules for cx-* specialist agents.
 
 Defines when to route directly to a cx-* specialist vs through Construct orchestration.
 Covers intent-based routing table, complexity gate, and routing rules.
 Loaded by rule-loading systems that look for cx-agent-routing in the rules hierarchy.
 -->
-# cx-* Agent Routing — Auto-trigger Rules
+# cx-* Agent Routing: Auto-trigger Rules
 
 When a request matches the trigger patterns below, automatically route to the corresponding cx-* specialist or persona before responding.
 

package/rules/common/cx-skill-routing.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/cx-skill-routing.md — Redirect to canonical skill routing table.
+rules/common/cx-skill-routing.md: Redirect to canonical skill routing table.
 -->
 # cx-* Skill Routing
 
@@ -7,5 +7,5 @@ rules/common/cx-skill-routing.md — Redirect to canonical skill routing table.
 >
 > All skill routing keywords, domain tables, and routing rules live there.
 > This file exists only as a named entry point for rule-loading systems that
-> look for `cx-skill-routing.md`. Do not add routing entries here — update
+> look for `cx-skill-routing.md`. Do not add routing entries here: update
 > `skills/routing.md` instead.

package/rules/common/development-workflow.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/development-workflow.md — feature implementation pipeline.
+rules/common/development-workflow.md: feature implementation pipeline.
 
 Defines the research-plan-TDD-review-commit workflow that runs before
 git operations. References testing.md, code-review.md, git-workflow.md.

package/rules/common/doc-ownership.md

@@ -1,9 +1,9 @@
 <!--
-rules/common/doc-ownership.md — which specialist owns which document type.
+rules/common/doc-ownership.md: which specialist owns which document type.
 
 Prevents the orchestrator (or any general persona) from authoring specialist
 documents directly. Routing authorship to the owning role is how research,
-framing, and domain scrutiny actually fire — writing a PRD without the
+framing, and domain scrutiny actually fire: writing a PRD without the
 product manager bypasses those checks entirely.
 -->
 # Document Ownership

package/rules/common/efficiency.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/efficiency.md — session context and tool-use efficiency standards.
+rules/common/efficiency.md: session context and tool-use efficiency standards.
 
 Applies to all agents operating in a Construct session. Violations compound context
 cost and reduce throughput. These rules are enforced by read-tracker.mjs and surfaced
@@ -19,7 +19,7 @@ Signals that a re-read is warranted:
 - An external process (Bash, a subagent) may have modified it.
 - The last read was in a prior session (context was compacted).
 
-Do not re-read to verify — trust the in-context state. If staleness is a concern,
+Do not re-read to verify: trust the in-context state. If staleness is a concern,
 check the file hash via `read-tracker.mjs` state rather than re-reading the full file.
 
 **Threshold:** more than 3 reads of the same file within a session without an intervening
@@ -54,4 +54,4 @@ re-running the command.
 Each Task dispatch creates a subagent context. Dispatch a specialist when the task
 benefits from a structurally different view (architecture suspicion, security scan,
 coverage gap analysis). Do not dispatch for tasks that fit within a single focused
-pass — the round-trip cost exceeds the benefit.
+pass: the round-trip cost exceeds the benefit.

package/rules/common/framing.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/framing.md — how to frame a problem before acting on it.
+rules/common/framing.md: how to frame a problem before acting on it.
 
 Establishes the hard separation between execution artifacts (tickets, chat
 transcripts, existing docs) and sources of truth (the underlying problem).

package/rules/common/git-workflow.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/git-workflow.md — commit message format and PR workflow.
+rules/common/git-workflow.md: commit message format and PR workflow.
 
 Defines conventional commit types and pull request creation steps.
 -->

package/rules/common/patterns.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/patterns.md — reusable design patterns and skeleton project strategy.
+rules/common/patterns.md: reusable design patterns and skeleton project strategy.
 
 Covers skeleton project evaluation, repository pattern, and API response format.
 -->

package/rules/common/performance.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/performance.md — model-agnostic performance and context management rules.
+rules/common/performance.md: model-agnostic performance and context management rules.
 
 Defines model selection tiers, context window management heuristics,
 and build troubleshooting steps. No platform-specific tool names or config paths.

package/rules/common/release-gates.md

@@ -1,12 +1,12 @@
 <!--
-rules/common/release-gates.md — Hard release gates for Construct work.
+rules/common/release-gates.md: Hard release gates for Construct work.
 
 Defines the blocking contracts every agent and persona must satisfy locally
 before any commit, push, or "done" claim. Loaded by the construct persona,
 AGENTS.md, and the engineer/reviewer/operator role overlays. Enforcement is at
-the prompt level — CI is a backstop, not the primary gate.
+the prompt level: CI is a backstop, not the primary gate.
 -->
-# Release Gates — Hard Contracts
+# Release Gates: Hard Contracts
 
 These are blocking gates. Every agent, persona, and harness session working in or shipping Construct must satisfy them locally **before** any commit, push, or "done" claim. CI is a backstop, not the primary check.
 
@@ -20,7 +20,7 @@ Run these before declaring work done. Pasting the output into the PR body or `bd
 |---|---|---|
 | Tests | `npm test` | 0 failed, 0 unexpected skips |
 | Comment policy | `node bin/construct lint:comments` | 0 errors AND 0 warnings |
-| Doc verification | `node bin/construct docs:verify` | "All documentation checks passed" — no warnings either |
+| Doc verification | `node bin/construct docs:verify` | "All documentation checks passed": no warnings either |
 | AUTO doc drift | `node bin/construct docs:update --check` | "Docs are up to date" |
 | Template policy | `npm run lint:templates` | "Template policy: clean." |
 
@@ -34,9 +34,9 @@ npm run release:check
 
 The repo enforces `.gitmessage` and `.github/pull_request_template.md`. Both are validated by `scripts/lint-commits-pr.mjs` (the `lint-templates` CI job) and fail the build on any deviation.
 
-Commit subjects must match `type(scope): subject` — type from {feat, fix, refactor, perf, docs, test, chore, ci, build, style}, imperative mood, ≤72 chars, no trailing period, lowercase after the colon. Run `git config commit.template .gitmessage` once per clone to load the template into your editor.
+Commit subjects must match `type(scope): subject`: type from {feat, fix, refactor, perf, docs, test, chore, ci, build, style}, imperative mood, ≤72 chars, no trailing period, lowercase after the colon. Run `git config commit.template .gitmessage` once per clone to load the template into your editor.
 
-PR descriptions must keep all six headings — Summary, Beads issue, Doc updates included, Local gates, Test plan, Risks / rollback — with at least one checked box in both the "Doc updates" and "Local gates" sections. Empty templates fail.
+PR descriptions must keep all six headings (Summary, Beads issue, Doc updates included, Local gates, Test plan, Risks / rollback) with at least one checked box in both the "Doc updates" and "Local gates" sections. Empty templates fail.
 
 Forbidden in commit messages: `Co-Authored-By: Claude*` trailers (unless the user explicitly asks), `--no-verify`, `--no-gpg-sign`. Forbidden in PR bodies: deleting the required headings, leaving every gate box unchecked.
 
@@ -47,7 +47,7 @@ For every non-trivial change:
 1. **A Beads issue exists.** `bd ready` to find or create one. `bd show <id>` to read context. `bd update <id> --claim` to claim before editing files.
 2. **`plan.md` reflects the work.** Even though `plan.md` is local-only and gitignored, it stays the human-readable working plan. Mark items `done` when they ship; add new rows for work that wasn't previously tracked.
 3. **Doc updates land in the same change as code.** If runtime shape, contracts, boundaries, or major dependencies changed, update `docs/concepts/architecture.md` in the same commit. If the docs surface or maintenance contract changed, update `docs/README.md`. If active work, decisions, or assumptions changed, update `.cx/context.md` and `.cx/context.json`. Always add a `CHANGELOG.md` entry.
-4. **Beads close on green.** `bd close <id>` happens after CI is green and the work is verified — not before.
+4. **Beads close on green.** `bd close <id>` happens after CI is green and the work is verified: not before.
 
 ## Hard rules
 

package/rules/common/research.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/research.md — canonical research and evidence policy for Construct.
+rules/common/research.md: canonical research and evidence policy for Construct.
 
 Defines how research starts, which sources to prefer, how claims are verified,
 and what must be recorded so findings are reproducible. Applies to research,
@@ -14,9 +14,9 @@ Construct treats research as a reproducible evidence-gathering process, not free
 
 Research always starts from the most recent available evidence.
 
-- Default to sources from the current year before earlier years — always search most-recent-first.
+- Default to sources from the current year before earlier years: always search most-recent-first.
 - For fast-moving topics (AI tools, LLM behavior, cloud APIs, security advisories, market data), treat anything older than 12 months as presumptively stale unless a newer source confirms it is still accurate.
-- When using a search engine or index, always filter or sort by date — do not rely on relevance ranking alone.
+- When using a search engine or index, always filter or sort by date: do not rely on relevance ranking alone.
 - State the publication or access date for every external source. If a source has no date, treat its confidence as `low` until recency is established another way.
 
 ## 2. Domain-specific starting points
@@ -67,7 +67,7 @@ Record:
 Every URL cited in a committed document must be verified before the document is published.
 
 - Fetch the URL. Confirm it resolves and the content matches the cited claim.
-- Do not cite aggregate or index pages (e.g., arxiv.org search results, Google Scholar listings) for quantitative claims — cite the specific paper or article URL.
+- Do not cite aggregate or index pages (e.g., arxiv.org search results, Google Scholar listings) for quantitative claims: cite the specific paper or article URL.
 - If a URL returns a 404, paywall, or redirect loop, find the canonical source or replace the citation.
 - Unverified URLs must be marked `[unverified]` until confirmed.
 

package/rules/common/security.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/security.md — mandatory security checks and secret management.
+rules/common/security.md: mandatory security checks and secret management.
 
 Defines pre-commit security checklist, secret management rules,
 and response protocol for discovered vulnerabilities.

package/rules/common/skill-composition.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/skill-composition.md — how specialist prompts compose with skill files.
+rules/common/skill-composition.md: how specialist prompts compose with skill files.
 
 Defines the default boundary between what lives in the agent's base prompt and
 what is fetched via `get_skill` at runtime. Aims to keep prompts lean while
@@ -17,13 +17,13 @@ Every specialist prompt carries a marker:
 **Role guidance**: call `get_skill("roles/NAME")` before drafting.
 ```
 
-When the agent begins substantive work in its domain, it calls `get_skill("roles/NAME")` via the construct-mcp server. The skill body is returned for that turn only — no permanent prompt budget is consumed.
+When the agent begins substantive work in its domain, it calls `get_skill("roles/NAME")` via the construct-mcp server. The skill body is returned for that turn only: no permanent prompt budget is consumed.
 
 All hosts Construct supports (Claude Code, OpenCode, Codex, Copilot) have `get_skill` available through the construct-mcp server, so the runtime call is reliable.
 
 ## Why on-demand is the default
 
-Inlining every role skill at sync time used to consume ~1000–2000 words of prompt budget per specialist, regardless of whether the skill content was relevant to the current task. That budget is fixed — it reduces the window available for actual context.
+Inlining every role skill at sync time used to consume ~1000–2000 words of prompt budget per specialist, regardless of whether the skill content was relevant to the current task. That budget is fixed: it reduces the window available for actual context.
 
 On-demand loading means:
 
@@ -40,20 +40,20 @@ Set `preloadRoleGuidance: true` on a registry entry only when:
 - The role content is so load-bearing that every single turn needs it
 - The agent's model is weak at tool-calling discipline and skips the `get_skill` call in practice
 
-This should be rare. If you find yourself preloading most agents, revisit the reasoning — the default exists because the cost is real.
+This should be rare. If you find yourself preloading most agents, revisit the reasoning: the default exists because the cost is real.
 
 ## Skill array vs. role guidance
 
 Two different mechanisms for two different purposes:
 
-- **Registry `skills: [...]` array** — declarative metadata listing which skills the agent is *entitled* to call. Not inlined into the prompt. Used by `list_skills`, routing heuristics, and audit tooling. Add skills here liberally.
-- **Role guidance directive** — the single `**Role guidance**: call get_skill("roles/NAME")` line in the prompt. Points the agent at its role file and (by default) tells it to load on demand. Exactly one per agent.
+- **Registry `skills: [...]` array**: declarative metadata listing which skills the agent is *entitled* to call. Not inlined into the prompt. Used by `list_skills`, routing heuristics, and audit tooling. Add skills here liberally.
+- **Role guidance directive**: the single `**Role guidance**: call get_skill("roles/NAME")` line in the prompt. Points the agent at its role file and (by default) tells it to load on demand. Exactly one per agent.
 
 ## Contributor guidance
 
 When adding or editing a specialist:
 
-1. Keep the base prompt short — role, perspective, productive tension, handoff contract. Under 400 words is normal.
+1. Keep the base prompt short: role, perspective, productive tension, handoff contract. Under 400 words is normal.
 2. Put domain depth into `skills/roles/NAME.md` and optional flavor overlays like `skills/roles/NAME.FLAVOR.md`.
 3. Leave the role-guidance directive in place. Do not manually inline role content into the prompt body.
 4. Only add `preloadRoleGuidance: true` with a written reason in the registry description.
@@ -64,4 +64,4 @@ Do not:
 
 - Paste role-skill content directly into the prompt body "to be safe"
 - Add `preloadRoleGuidance: true` to push a prompt under the cap without fixing the underlying bloat
-- Split a role skill into many tiny files to dodge the cap — keep the cohesive unit, load it on demand instead
+- Split a role skill into many tiny files to dodge the cap: keep the cohesive unit, load it on demand instead

package/rules/common/testing.md

@@ -1,5 +1,5 @@
 <!--
-rules/common/testing.md — test coverage requirements and TDD workflow.
+rules/common/testing.md: test coverage requirements and TDD workflow.
 
 Defines minimum 80% coverage, TDD red-green-refactor cycle,
 AAA test structure, and descriptive naming conventions.

package/rules/golang/coding-style.md

@@ -1,5 +1,5 @@
 <!--
-rules/golang/coding-style.md — <one-line purpose>
+rules/golang/coding-style.md: <one-line purpose>
 
 <2–6 line summary.>
 -->
@@ -15,7 +15,7 @@ paths:
 
 ## Formatting
 
-- **gofmt** and **goimports** are mandatory — no style debates
+- **gofmt** and **goimports** are mandatory: no style debates
 
 ## Design Principles
 

package/rules/golang/hooks.md

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

package/rules/golang/patterns.md

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

package/rules/golang/security.md

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

package/rules/golang/testing.md

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

package/rules/python/coding-style.md

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

package/rules/python/hooks.md

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

package/rules/python/patterns.md

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

package/rules/python/security.md

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

package/rules/python/testing.md

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

package/rules/swift/coding-style.md

@@ -1,5 +1,5 @@
 <!--
-rules/swift/coding-style.md — <one-line purpose>
+rules/swift/coding-style.md: <one-line purpose>
 
 <2–6 line summary.>
 -->
@@ -19,14 +19,14 @@ paths:
 
 ## Immutability
 
-- Prefer `let` over `var` — define everything as `let` and only change to `var` if the compiler requires it
+- Prefer `let` over `var`: define everything as `let` and only change to `var` if the compiler requires it
 - Use `struct` with value semantics by default; use `class` only when identity or reference semantics are needed
 
 ## Naming
 
 Follow [Apple API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/):
 
-- Clarity at the point of use — omit needless words
+- Clarity at the point of use: omit needless words
 - Name methods and properties for their roles, not their types
 - Use `static let` for constants over global constants
 

package/rules/swift/hooks.md

@@ -1,5 +1,5 @@
 <!--
-rules/swift/hooks.md — <one-line purpose>
+rules/swift/hooks.md: <one-line purpose>
 
 <2–6 line summary.>
 -->
@@ -18,4 +18,4 @@ paths:
 
 ## Warning
 
-Flag `print()` statements — use `os.Logger` or structured logging instead for production code.
+Flag `print()` statements: use `os.Logger` or structured logging instead for production code.

package/rules/swift/patterns.md

@@ -1,5 +1,5 @@
 <!--
-rules/swift/patterns.md — <one-line purpose>
+rules/swift/patterns.md: <one-line purpose>
 
 <2–6 line summary.>
 -->
@@ -53,7 +53,7 @@ actor Cache<Key: Hashable & Sendable, Value: Sendable> {
 
 ## Dependency Injection
 
-Inject protocols with default parameters — production uses defaults, tests inject mocks:
+Inject protocols with default parameters: production uses defaults, tests inject mocks:
 
 ```swift
 struct UserService {

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