@geraldmaron/construct 1.0.0 → 1.0.2

package/rules/common/doc-ownership.md

@@ -0,0 +1,54 @@
+<!--
+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
+product manager bypasses those checks entirely.
+-->
+# Document Ownership
+
+A document type names a body of work. That body of work has an owner. The orchestrator routes; it does not author.
+
+If Construct (or any general persona) drafts a PRD, ADR, research brief, or RFC directly, the specialists who would normally challenge the framing, demand external research, or enforce domain rigor never get invoked. The artifact looks complete and is structurally weak.
+
+## Ownership table
+
+| Document type | Owner | Why |
+|---|---|---|
+| PRD, meta-PRD, PRFAQ, one-pager, backlog proposal, customer profile | **cx-product-manager** | Requires evidence-traceable requirements, user grounding, scope discipline |
+| ADR, RFC, architecture overview, system design | **cx-architect** | Requires trade-off analysis, reversibility reasoning, interface contract scrutiny |
+| Research brief, evidence brief, signal brief, product intelligence report | **cx-researcher** | Requires external-source policy (`rules/common/research.md`), citation standards |
+| Runbook | **cx-operations** or **cx-sre** | Requires on-call reality, incident experience |
+| Incident report, postmortem | **cx-sre** | Requires blameless structure, reliability framing |
+| Test plan, QA strategy | **cx-qa** | Requires coverage threshold reasoning, risk-based prioritization |
+| Security review, threat model | **cx-security** | Requires attacker-perspective scrutiny |
+| Memo, internal explainer | **cx-docs-keeper** | Requires narrative discipline and cross-linking |
+| Changelog, CHANGELOG.md | **cx-docs-keeper** | Lightweight but still a documentation deliverable |
+
+## Routing rules
+
+1. **Detect the doc type from the request.** Keywords like "write a PRD", "draft an ADR", "produce a research brief" trigger ownership routing. Construct must not author these itself.
+
+2. **Route before framing.** The owning specialist runs the framing step (`rules/common/framing.md`) as part of their drafting process. Pre-framing by the orchestrator defeats the purpose.
+
+3. **Research precedes architecture.** If the request is for architecture/ADR/RFC work and references a named concept not in the project glossary, cx-researcher runs *before* cx-architect and returns the reference set cx-architect must cite.
+
+4. **The orchestrator reviews, does not redraft.** If the specialist's draft has issues, the orchestrator surfaces them back to the same specialist. Only the owner revises.
+
+5. **Cross-doc coherence is the docs-keeper's job.** When a set of documents must stay consistent (PRD ↔ ADR ↔ research), cx-docs-keeper runs after drafting to enforce cross-references, not to rewrite content.
+
+## Failure mode this rule prevents
+
+An orchestrator that writes a PRD directly:
+
+- Skips requirements traceability (cx-product-manager would demand evidence)
+- Skips external research (cx-researcher would demand primary sources)
+- Skips framing (framing is the owning specialist's first step, not the orchestrator's)
+- Produces a structurally complete artifact that reflects the orchestrator's reasoning, not the domain's rigor
+
+This is exactly how "it looks done but feels shallow" happens.
+
+## The one rule
+
+**If the document type has an owner in the table above, route to the owner. Do not author it yourself.**

package/rules/common/efficiency.md

@@ -0,0 +1,57 @@
+<!--
+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
+in the session-start efficiency digest.
+-->
+
+# Session Efficiency
+
+## Read discipline
+
+Read a file once per task boundary. When a file's content is needed again, use the
+in-context version unless there is a concrete reason to believe it changed (e.g., a
+tool wrote it since the last read).
+
+Signals that a re-read is warranted:
+- A Write/Edit tool call targeted the file after the last read.
+- 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,
+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
+write is a signal to stop and confirm the approach. The session-start digest surfaces
+files that crossed this threshold in the prior session.
+
+## Probe before bulk read
+
+Before calling `Read` with `limit` unset or above 200 lines:
+1. Check file size with `Glob` or `wc -l`.
+2. Use a `limit: 50` probe pass to confirm the region of interest.
+3. Then read the targeted range with `offset` + `limit`.
+
+Bulk reading a large file to find a small section is never the right approach.
+
+## Tool call parallelism
+
+Independent tool calls must run in parallel. Sequential execution of parallelizable
+calls wastes wall-clock time and burns context on round-trip overhead.
+
+A call is independent when its inputs do not depend on the output of any other call
+in the same batch.
+
+## Bash output
+
+Long Bash outputs are automatically persisted to `~/.cx/bash-logs/` by
+`bash-output-logger.mjs`. Reference the log path in subsequent turns rather than
+re-running the command.
+
+## Agent dispatch cost
+
+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.

package/rules/common/framing.md

@@ -0,0 +1,76 @@
+<!--
+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).
+Applies to every specialist working on architecture, documentation, research,
+product, or strategy work. Read before scaffolding anything.
+-->
+# Framing Policy
+
+Most agent failures on ambiguous work trace to a single mistake: anchoring on the most concrete input available (usually a ticket or a prior doc) and building the output around its structure instead of around the actual problem.
+
+Construct's default behavior must be the opposite.
+
+## 1. Execution artifacts are not sources of truth
+
+The following are **execution signals**, not the problem itself:
+
+- Jira tickets, Linear issues, GitHub issues
+- Chat transcripts, Slack threads, email threads
+- Existing PRDs, RFCs, design docs
+- User-provided summaries of "what we want"
+- Prior conversation history with the user
+
+They describe **how the problem was reported**, **what has been tried**, or **what someone thinks the solution is**. They do not define what the problem is.
+
+Treating them as source of truth produces output that reflects the reporting structure, not the underlying need. That is the failure mode this rule exists to prevent.
+
+## 2. Required framing step before scaffolding
+
+Before scaffolding any architecture, documentation set, research brief, PRD, ADR, RFC, or roadmap, **state the underlying problem in your own words, independent of how it was reported**.
+
+A valid problem statement:
+
+- Describes an outcome someone needs, not a ticket title
+- Does not reference ticket IDs, PRD filenames, or chat excerpts
+- Would be legible to a reader who has never seen the inputs
+- Names the constraint that makes the problem non-trivial
+
+If you cannot produce this statement without referencing the inputs, you have not framed the problem. You are paraphrasing the inputs.
+
+## 3. ADR / PRD / RFC content rules
+
+- **ADR "Problem" section** must describe a decision-forcing tension in the domain. It must not describe the documents, tickets, or process that surfaced it.
+- **PRD "Problem" section** must describe a user or business outcome that is currently blocked. It must not describe the roadmap item or ticket that initiated the work.
+- **RFC "Motivation" section** must describe the technical or product pressure that makes the change worth its cost. It must not describe the meeting or request that triggered the RFC.
+
+If a reader needs the ticket to understand the doc, the doc is failing its job.
+
+## 4. When the inputs disagree with the inferred problem
+
+If tickets, transcripts, or prior docs point at a different problem than the one you infer:
+
+- Surface the mismatch explicitly
+- Propose the reframed problem statement
+- Ask the user once, then proceed with the reframed version if no answer
+
+Do not silently adopt the input framing because it is easier.
+
+## 5. Anti-patterns
+
+Do not:
+
+- Title documents after tickets or PRD filenames
+- Structure information architecture around the artifacts that described the problem
+- Write an ADR whose "Decision" is "we will have these documents" or "we will use this ticket structure"
+- Produce a research brief whose sources are all internal tickets and transcripts
+- Frame the "Rejected alternatives" section as "we considered not doing this ticket"
+
+## 6. The one-sentence test
+
+Before any artifact is considered framed, it must pass:
+
+*"A principal engineer reading only this document, with no access to any tickets or prior context, would understand what problem is being solved and why it matters."*
+
+If the document fails that test, it is not framed. It is a changelog entry wearing a different costume.

package/rules/common/git-workflow.md

@@ -1,7 +1,7 @@
 <!--
-rules/common/git-workflow.md — <one-line purpose>
+rules/common/git-workflow.md — commit message format and PR workflow.
 
-<2–6 line summary.>
+Defines conventional commit types and pull request creation steps.
 -->
 # Git Workflow
 
@@ -14,8 +14,6 @@ rules/common/git-workflow.md — <one-line purpose>
 
 Types: feat, fix, refactor, docs, test, chore, perf, ci
 
-Note: Attribution disabled globally via ~/.claude/settings.json.
-
 ## Pull Request Workflow
 
 When creating PRs:

package/rules/common/patterns.md

@@ -1,7 +1,7 @@
 <!--
-rules/common/patterns.md — <one-line purpose>
+rules/common/patterns.md — reusable design patterns and skeleton project strategy.
 
-<2–6 line summary.>
+Covers skeleton project evaluation, repository pattern, and API response format.
 -->
 # Common Patterns
 
@@ -9,11 +9,7 @@ rules/common/patterns.md — <one-line purpose>
 
 When implementing new functionality:
 1. Search for battle-tested skeleton projects
-2. Use parallel agents to evaluate options:
-   - Security assessment
-   - Extensibility analysis
-   - Relevance scoring
-   - Implementation planning
+2. Evaluate options for security, extensibility, and relevance
 3. Clone best match as foundation
 4. Iterate within proven structure
 

package/rules/common/performance.md

@@ -1,23 +1,24 @@
 <!--
-rules/common/performance.md — <one-line purpose>
+rules/common/performance.md — model-agnostic performance and context management rules.
 
-<2–6 line summary.>
+Defines model selection tiers, context window management heuristics,
+and build troubleshooting steps. No platform-specific tool names or config paths.
 -->
 # Performance Optimization
 
 ## Model Selection Strategy
 
-**Haiku 4.5** (90% of Sonnet capability, 3x cost savings):
+**Fast tier** (small/cheap models):
 - Lightweight agents with frequent invocation
 - Pair programming and code generation
 - Worker agents in multi-agent systems
 
-**Sonnet 4.6** (Best coding model):
+**Standard tier** (mid-range models):
 - Main development work
 - Orchestrating multi-agent workflows
 - Complex coding tasks
 
-**Opus 4.5** (Deepest reasoning):
+**Reasoning tier** (large/frontier models):
 - Complex architectural decisions
 - Maximum reasoning requirements
 - Research and analysis tasks
@@ -30,15 +31,15 @@ Avoid last 20% of context window for:
 - Debugging complex interactions
 
 Prefer this retrieval ladder before loading more context:
-1. `Grep` / `Glob` to narrow candidate files
-2. targeted `Read` windows (aim for <400 lines)
-3. parallel reads for the minimum necessary file set
-4. summarize to `.cx/context.md` before broad re-exploration or compaction
+1. Targeted search to narrow candidate files
+2. Targeted reads (aim for <400 lines)
+3. Parallel reads for the minimum necessary file set
+4. Summarize to a context artifact before broad re-exploration
 
 Heuristics:
-- Re-reading the same file multiple times without a state change is usually a retrieval smell.
+- Re-reading the same file multiple times without a state change is a retrieval smell.
 - Large reads should be reserved for files where local structure matters more than symbol search.
-- Use workflow/context artifacts as cached state instead of rediscovering the same background repeatedly.
+- Use workflow/context artifacts as cached state instead of rediscovering background repeatedly.
 
 Lower context sensitivity tasks:
 - Single-file edits
@@ -46,26 +47,9 @@ Lower context sensitivity tasks:
 - Documentation updates
 - Simple bug fixes
 
-## Extended Thinking + Plan Mode
-
-Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning.
-
-Control extended thinking via:
-- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux)
-- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json`
-- **Budget cap**: `export MAX_THINKING_TOKENS=10000`
-- **Verbose mode**: Ctrl+O to see thinking output
-
-For complex tasks requiring deep reasoning:
-1. Ensure extended thinking is enabled (on by default)
-2. Enable **Plan Mode** for structured approach
-3. Use multiple critique rounds for thorough analysis
-4. Use split role sub-agents for diverse perspectives
-
 ## Build Troubleshooting
 
 If build fails:
-1. Use **build-error-resolver** agent
-2. Analyze error messages
-3. Fix incrementally
-4. Verify after each fix
+1. Analyze error messages
+2. Fix incrementally
+3. Verify after each fix

package/rules/common/release-gates.md

@@ -0,0 +1,69 @@
+<!--
+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.
+-->
+# 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.
+
+The goal is simple: if a gate would fail in CI, it fails locally first. We never push and pray.
+
+## The five local gates
+
+Run these before declaring work done. Pasting the output into the PR body or `bd note` is the standard evidence.
+
+| Gate | Command | Pass criterion |
+|---|---|---|
+| 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 |
+| AUTO doc drift | `node bin/construct docs:update --check` | "Docs are up to date" |
+| Template policy | `npm run lint:templates` | "Template policy: clean." |
+
+The shortcut for all five (plus dashboard sync) is:
+
+```bash
+npm run release:check
+```
+
+## Commit + PR templates
+
+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.
+
+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.
+
+## The tracker contract
+
+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.
+
+## Hard rules
+
+- **Do not commit if any gate fails.** Fix the underlying issue. Do not skip hooks (`--no-verify`), do not bypass with `[skip ci]` for code changes.
+- **Do not push expecting CI to catch it.** If you would not run a gate locally, do not run it in CI.
+- **Do not declare DONE before the gates run.** "Tests pass" without `npm test` evidence is not done.
+- **Comment policy violations are blocking, not advisory.** Warnings count as failures for this gate.
+- **Documentation drift is a code change.** A code commit that should have triggered a doc update but did not is incomplete work, not a follow-up.
+
+## When a gate must be bypassed
+
+If a gate is genuinely broken (tooling regression, infra issue) and the change is unrelated:
+
+1. State the gate name and the failure.
+2. Confirm with the user before bypassing.
+3. File a Beads issue for the broken gate.
+4. Note the bypass in the PR body and the Beads issue.
+
+This is the only authorized form of bypass. "I'll fix it later" is not.

package/rules/common/research.md

@@ -0,0 +1,107 @@
+<!--
+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,
+product evidence synthesis, document ingest follow-up, and any recommendation
+that depends on external facts or evolving internal evidence.
+-->
+# Research Policy
+
+Construct treats research as a reproducible evidence-gathering process, not free-form browsing. If a claim could change decisions, scope, architecture, or roadmap, it must be tied to verifiable evidence.
+
+## 1. Start order
+
+Start with the narrowest authoritative source that can answer the question:
+
+1. **Local project evidence first**
+   - `.cx/research/`
+   - `.cx/knowledge/`
+   - `docs/prd/`, `docs/meta-prd/`, `docs/adr/`, `docs/runbooks/`
+   - ingested markdown artifacts under `.cx/knowledge/`
+   - repo code, tests, configs, and existing decisions
+2. **Primary external sources second**
+   - official docs for the exact version in use
+   - source code, standards, specifications, API references, vendor security advisories
+3. **Secondary sources third**
+   - changelogs, migration guides, maintainer issue comments, release notes
+4. **Tertiary sources last**
+   - blogs, forums, Q&A, analyst summaries, AI-generated summaries
+
+Tertiary sources may help discover primary sources. They are not sufficient evidence for load-bearing claims.
+
+## 2. Required metadata for every source
+
+Record:
+
+- source title or path
+- source class: internal, primary, secondary, or tertiary
+- version or revision when applicable
+- publication date, release date, or access date
+- why this source is relevant
+
+If a source has no date and the topic is time-sensitive, treat confidence as reduced until recency is established another way.
+
+## 3. Verification rules
+
+For each load-bearing claim:
+
+- prefer **two independent sources**
+- one source is acceptable only when it is the authoritative primary source for that exact fact
+- separate **observation** from **inference**
+- label confidence as `high`, `medium`, or `low`
+- state the strongest counter-evidence or contradiction when one exists
+
+Claims about versions, APIs, security, pricing, compatibility, regulations, and timelines must cite the exact version/date basis.
+
+## 4. Reproducibility
+
+Research must be reproducible by another person in the repo.
+
+Record:
+
+- the exact question being answered
+- search terms, commands, paths, or systems queried
+- inclusion/exclusion decisions
+- unresolved gaps that would change the recommendation
+
+If you cannot explain how the answer was obtained, the research is incomplete.
+
+## 5. Evidence thresholds
+
+Recommendations must state what evidence threshold was used.
+
+Examples:
+
+- feature demand threshold
+- migration-risk threshold
+- security severity threshold
+- benchmark or performance threshold
+- confidence threshold for acting now vs gathering more evidence
+
+If the threshold is not met, the output should recommend more research, a weaker artifact, or a narrower decision.
+
+## 6. Output standard
+
+Research outputs should include:
+
+- question
+- method
+- sources
+- findings
+- confidence
+- open questions
+- recommendation or next step
+
+Every substantive finding should point to a source path, URL, or document reference.
+
+## 7. Anti-patterns
+
+Do not:
+
+- stop at the first plausible answer
+- cite a blog when the spec or source code is available
+- present inference as if the source said it directly
+- ignore conflicting evidence
+- use stale undated material for fast-moving topics without saying so
+- promote weak product evidence into committed requirements

package/rules/common/security.md

@@ -1,7 +1,8 @@
 <!--
-rules/common/security.md — <one-line purpose>
+rules/common/security.md — mandatory security checks and secret management.
 
-<2–6 line summary.>
+Defines pre-commit security checklist, secret management rules,
+and response protocol for discovered vulnerabilities.
 -->
 # Security Guidelines
 
@@ -28,7 +29,6 @@ Before ANY commit:
 
 If security issue found:
 1. STOP immediately
-2. Use **security-reviewer** agent
-3. Fix CRITICAL issues before continuing
-4. Rotate any exposed secrets
-5. Review entire codebase for similar issues
+2. Fix CRITICAL issues before continuing
+3. Rotate any exposed secrets
+4. Review entire codebase for similar issues

package/rules/common/skill-composition.md

@@ -0,0 +1,67 @@
+<!--
+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
+keeping domain knowledge reliably available when needed.
+-->
+# Skill Composition Policy
+
+Specialist agent prompts are lean on purpose. Domain depth lives in skill files and is pulled in on demand, not pre-inlined.
+
+## Default: on-demand skill loading
+
+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.
+
+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.
+
+On-demand loading means:
+
+- Quick tasks that don't need the full role body never pay the word cost
+- The agent can load only the flavor overlay it actually needs
+- Prompt caps become a real soft target, not a constant overage
+- Skill content can be updated without re-syncing every agent prompt
+
+## Opt-in preload: `preloadRoleGuidance: true`
+
+Set `preloadRoleGuidance: true` on a registry entry only when:
+
+- The agent ships to hosts that do not expose `get_skill` reliably
+- 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.
+
+## 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.
+
+## 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.
+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.
+
+## Anti-patterns
+
+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

package/rules/common/testing.md

@@ -1,7 +1,8 @@
 <!--
-rules/common/testing.md — <one-line purpose>
+rules/common/testing.md — test coverage requirements and TDD workflow.
 
-<2–6 line summary.>
+Defines minimum 80% coverage, TDD red-green-refactor cycle,
+AAA test structure, and descriptive naming conventions.
 -->
 # Testing Requirements
 
@@ -24,39 +25,26 @@ MANDATORY workflow:
 
 ## Troubleshooting Test Failures
 
-1. Use **tdd-guide** agent
-2. Check test isolation
-3. Verify mocks are correct
-4. Fix implementation, not tests (unless tests are wrong)
-
-## Agent Support
-
-- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first
+1. Check test isolation
+2. Verify mocks are correct
+3. Fix implementation, not tests (unless tests are wrong)
 
 ## Test Structure (AAA Pattern)
 
-Prefer Arrange-Act-Assert structure for tests:
-
-```typescript
-test('calculates similarity correctly', () => {
-  // Arrange
-  const vector1 = [1, 0, 0]
-  const vector2 = [0, 1, 0]
+Prefer Arrange-Act-Assert:
 
-  // Act
-  const similarity = calculateCosineSimilarity(vector1, vector2)
-
-  // Assert
-  expect(similarity).toBe(0)
-})
+```
+// Arrange - set up test data
+// Act - call the function under test
+// Assert - verify the result
 ```
 
 ### Test Naming
 
 Use descriptive names that explain the behavior under test:
 
-```typescript
-test('returns empty array when no markets match query', () => {})
-test('throws error when API key is missing', () => {})
-test('falls back to substring search when Redis is unavailable', () => {})
+```
+returns empty array when no items match query
+throws error when required config is missing
+falls back to default when service is unavailable
 ```

package/rules/golang/hooks.md

@@ -11,12 +11,8 @@ paths:
 ---
 # Go Hooks
 
-> This file extends [common/hooks.md](../common/hooks.md) with Go specific content.
-
 ## PostToolUse Hooks
 
-Configure in `~/.claude/settings.json`:
-
 - **gofmt/goimports**: Auto-format `.go` files after edit
 - **go vet**: Run static analysis after editing `.go` files
 - **staticcheck**: Run extended static checks on modified packages