@geraldmaron/construct 1.0.5 → 1.0.7

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.
@@ -8,8 +8,9 @@ git operations. References testing.md, code-review.md, git-workflow.md.
 
 ## Feature Implementation Workflow
 
-0. **Research & Reuse** _(mandatory before any new implementation)_
+0. **Research & Reuse** _(mandatory before any new implementation or artifact)_
    - **Search existing code first:** Look for existing implementations, templates, and patterns before writing anything new.
+   - **Search existing artifacts:** Before authoring a doc, rule, template, strategy, PRD, ADR, or RFC, audit what already exists. See [review-before-change.md](review-before-change.md) for the audit checklist. Extend or supersede; do not duplicate.
    - **Check docs:** Confirm API behavior, package usage, and version-specific details before implementing.
    - **Check package registries:** npm, PyPI, crates.io before writing utility code.
    - Prefer adopting a proven approach over writing net-new code.

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/no-fabrication.md

@@ -0,0 +1,69 @@
+<!--
+rules/common/no-fabrication.md: canonical anti-fabrication policy for Construct.
+
+Defines the trust contract between operators and the system: outputs stick to
+source, gaps stay visible, and confidence reflects evidence. Applies to every
+specialist, every artifact, and every summary — intake processing, document
+evaluation, knowledge writing, plan drafting, review verdicts, handoffs.
+
+Sibling rules: research.md (evidence hierarchy), framing.md (execution
+artifacts are not sources), comments.md (banned voice patterns).
+-->
+# No-Fabrication Policy
+
+Fabrication is the single largest threat to trust in an agent system. A persona that invents a customer quote, sharpens a vague signal into a confident assertion, or papers over a gap with plausible-sounding prose corrupts every artifact downstream. This rule applies to **every output** Construct produces: intake summaries, classification rationales, PRDs, ADRs, RFCs, knowledge notes, handoffs, review verdicts, plan entries, beads issues, MCP tool responses, dashboard text.
+
+## 1. Stick to source
+
+- Every load-bearing claim must trace to a source the reader can re-verify. Cite with `[source: path#anchor]`, `[source: intake-<id>]`, `[source: bd-<id>]`, `[source: <commit-sha>]`, or a fetched URL with the date the fetch happened.
+- If a fact is not in the source you have access to, write `unknown` or `[unverified]`. Do not paper over the gap with prose that sounds confident.
+- Never invent: customer names, quotes, ticket IDs, commit hashes, percentages, dates, file paths, function names, API surfaces, dependency names, version numbers.
+
+## 2. Preserve ambiguity
+
+- A vague signal stays vague in the artifact. If the intake says "users are frustrated with the dashboard," the PRD says "users are frustrated with the dashboard [source: intake-xxx]" — not "users want sub-200ms p95 dashboard latency."
+- When a source is ambiguous, list the possible interpretations and tag the chosen reading as inference, not observation.
+- Do not promote inference to observation. `X happened` requires evidence the event happened. `X likely means Y` requires the inference to be marked as such.
+
+## 3. Distinguish observation from inference
+
+- Observation: directly verifiable from the source. Format: bare statement with citation.
+- Inference: a conclusion drawn from one or more observations. Format: prefixed with `inference:` or `[inferred]`, and the supporting observations must be cited.
+- Speculation (no supporting observation): not allowed in artifacts. If you must raise a hypothesis, write it as a question, not an assertion.
+
+## 4. Calibrate confidence honestly
+
+- Confidence in artifacts and observation records reflects evidence strength, not authorial conviction. Single-source claims, secondary sources, and inferred conclusions get lower confidence than primary-source observations.
+- Words that smuggle confidence without evidence — `clearly`, `obviously`, `undoubtedly`, `definitely`, `certainly`, `surely` — are banned from artifact bodies. Replace with an explicit citation or remove.
+- Quantitative claims (`30% faster`, `5x improvement`, `90th percentile latency`) require an inline source. Hand-wave percentages are fabrication.
+
+## 5. Don't mind-read users or customers
+
+- `Users want X`, `customers expect Y`, `everyone agrees Z` require a citation to the source where the user or customer said so (interview transcript, support ticket, survey, observed behavior). Without the citation, the claim is fabrication.
+- Speculative product-vision language is allowed only in clearly-marked hypothesis or alternative sections, never in observation or requirements sections.
+
+## 6. Surface uncertainty as a question, not an assertion
+
+- When you don't know, ask. A persona that doesn't know whether a regression touched the auth flow asks for the diff before claiming it did. A reviewer who can't tell if a test covers a branch asks for the coverage report.
+- "I don't have access to X" is a valid output. Pretending to have access is fabrication.
+
+## 7. Embellishment is fabrication
+
+- Adding plausible-but-unverified detail to a summary, classification rationale, or handoff is fabrication, even when the additions feel innocuous.
+- The intake classifier's `rationale` field lists the exact keywords matched. Downstream personas must not embellish the rationale into a richer narrative the classifier did not produce.
+- Session summaries derive from observable session artifacts (context, observations, commits). Do not include events the transcript does not record.
+
+## 8. When in doubt, say less
+
+- A shorter, accurate artifact beats a longer artifact padded with unverified plausibility.
+- Sections that lack source material should be omitted, not filled with speculation. An ADR without a "Rejected alternatives" section because no alternatives were considered is better than an ADR with invented alternatives.
+
+## Enforcement
+
+- `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/prd/**`, `docs/adr/**`, `docs/rfc/**`, `docs/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
+- `agents/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation when `CONSTRUCT_CONTRACT_ENFORCEMENT=block`.
+- `construct intake done <id> --output=<path>` stamps `intake_id`, `intake_confidence`, and `intake_rationale` into the artifact's frontmatter so every intake-derived artifact carries verifiable provenance.
+
+## Bypass
+
+There is no bypass. If a check is wrong, fix the check (`rules/common/no-fabrication.md`, the pattern bank in `lib/comment-lint.mjs`, or the contract postcondition). Do not work around the gate.

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/review-before-change.md

@@ -0,0 +1,58 @@
+<!--
+rules/common/review-before-change.md: audit the current state before authoring anything new.
+
+Applies to every specialist on every platform. Pairs with framing.md (frame the
+problem) and development-workflow.md step 0 (research and reuse before code).
+This rule extends the same discipline to artifacts: docs, strategy, PRDs, ADRs,
+RFCs, rules, templates, and any other durable file. Read before scaffolding.
+-->
+# Review Before Change
+
+Before creating or rewriting a durable artifact, check what already exists.
+
+This rule exists because the most common waste in Construct is duplicated effort: a new strategy doc landing next to a PRD that already covers it, a new rule re-stating a section of `framing.md`, a new diagram drawn while an equivalent one sits two folders away. The fix is not more process. It is a fifteen-second audit before the first write.
+
+## When this applies
+
+Any time the work would produce or significantly rewrite one of:
+
+- A doc under `docs/`, including concepts, cookbook, providers, runbooks, ADRs, RFCs, PRDs, memos, runbooks, decisions.
+- A rule under `rules/` or a skill under `skills/`.
+- A template under `templates/`.
+- A top-level repo doc (README, CHANGELOG, STRATEGY, AGENTS, CONTRIBUTING).
+- A profile under `profiles/` or a registered agent.
+
+It does not apply to local-only working files (`plan.md`, `.cx/` state, draft scratch).
+
+## The audit
+
+Before writing, answer all three:
+
+1. **Does an artifact for this already exist?** Search by topic, not filename. `grep -rli "<topic>" docs/ rules/ skills/` is the floor. If something close exists, the default is to extend or supersede, not to create a sibling.
+2. **Is there a template or canonical shape for this artifact type?** Check `templates/docs/` and the matching `skills/docs/*-workflow.md`. If a shape exists, use it; do not invent a new structure.
+3. **What is the canonical home for this kind of content?** A strategy doc belongs in one place. A new ADR does not live in `docs/notes/`. If you have to think about where to put it, the location is wrong.
+
+If any answer surfaces an existing artifact, you have two valid moves:
+
+- **Extend it.** Add the missing section to the existing file.
+- **Supersede it.** Replace the old artifact and mark it superseded. Do not leave two competing sources of truth.
+
+Creating a new sibling artifact "because the old one didn't quite fit" is the failure mode this rule prevents. If the old one doesn't fit, fix it.
+
+## Documenting the audit
+
+For artifacts that go through a review cycle (strategy, PRD, ADR, RFC), the framing or problem-statement section should briefly note what existing artifacts were reviewed and why a new one is warranted. One sentence is enough. The point is to leave evidence that the audit happened.
+
+## Anti-patterns
+
+- Creating `docs/notes/strategy.md` because you didn't notice `STRATEGY.md` at the root.
+- Writing a new rule that paraphrases an existing one.
+- Adding a new template alongside `templates/docs/strategy.md` because the existing one "needed a couple of tweaks."
+- Drafting an ADR for a decision already captured in an existing ADR.
+- Producing a recipe in `docs/cookbook/` for a workflow already documented in `docs/concepts/`.
+
+## Related
+
+- `rules/common/framing.md`: frame the underlying problem before reaching for inputs.
+- `rules/common/development-workflow.md`: step 0 covers the same discipline for code.
+- `rules/common/doc-ownership.md`: which specialist owns which artifact type.

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 {