feat(workflows): enforce research checkpoints across development phases

docs/skills.md

@@ -28,6 +28,8 @@ Language, framework, library, and security rules use directory indexes plus focu
 
 Every search or lookup must use `research` and the applicable specialist, including direct reads, exact matches, familiar areas, and follow-up queries during implementation or verification. Loaded instructions can be reused; their checks apply to each search. Semantic retrieval runs first for unknown repository identifiers; known identifiers still use direct reads or `rg` within the research workflow. Disabling QMD does not disable the research requirement. These are agent instructions, not a runtime tool interceptor.
 
+Context7 phase checkpoints are defined once in `research/technical-research/SKILL.md`. Focused planning, SQL and test-writing, and verification skills call them explicitly, as do the architect, implementer, and verifier roles. The global rule applies the same checkpoints inside Superpowers and other plugin workflows without modifying upstream plugin caches or duplicating general workflow skills. Planning verifies external assumptions before accepting a design; implementation checks them against actual versions before coding; verification requires both applicable source evidence and proportionate execution results. Evidence travels in the existing plan or handoff and is reused across phases when the behavior, version, and environment match. Queries contain only public, sanitized concepts, use bounded timeouts and refinement, and report source fallback or unresolved gaps explicitly. This enforces an instruction contract; it does not guarantee model compliance or add network calls to builds and tests.
+
 Other skills guide a task when needed; their availability does not require a full review, build, or test suite after every
 change. The shared Verification rules govern proportional checking, including when generic skill workflows call
 for more work than the change needs.

shared/agents/architect/instructions.md

@@ -1,3 +1,5 @@
 # Architect
 
 Start from the parent's requirements and references. Identify relevant boundaries and constraints, compare viable designs, and recommend the smallest maintainable architecture. Make evidence-based reversible technical decisions; return ambiguous business behavior, contracts, or high-impact choices to the main agent. Do not invent requirements or broadly explore unrelated code. Use the shared orchestration handoff protocol.
+
+Before accepting a design that relies on external technology behavior, MUST apply the planning checkpoint in `technical-research`. Carry supporting evidence or unresolved assumptions into the handoff.

shared/agents/implementer/instructions.md

@@ -2,4 +2,6 @@
 
 Understand requirements and existing code, implement the smallest complete solution, follow applicable rules, and choose proportionate verification. Inspect your changes to the degree needed for their risk; a separate or full review is not automatic. Preserve unrelated user work.
 
+For external technology behavior, MUST apply the implementation checkpoint in `technical-research` before coding and its verification checkpoint before reporting completion. Inspect evidence supplied with the plan and reuse it only when it matches actual dependencies and configuration.
+
 Stay within assigned ownership, start at supplied references, and inspect additional context only when needed. Return changes, evidence, and unresolved risks using the shared orchestration handoff protocol; the parent owns shared task state.

shared/agents/verifier/instructions.md

@@ -2,4 +2,6 @@
 
 Provide execution evidence against acceptance criteria. Start with the requested behavior and relevant test/build commands; inspect only enough implementation to choose the smallest sufficient checks. Run tests, builds, checks, generated-output validation, or behavior reproduction as needed. Reuse valid earlier results instead of repeating checks. Do not perform a static review of the diff; report implementation concerns only when they block or explain execution results.
 
+For criteria relying on external technology behavior, MUST apply the verification checkpoint in `technical-research`. Inspect supplied evidence and version applicability; retrieve only missing evidence. Keep documentation support separate from execution results and mark unsupported criteria unverified.
+
 Report commands, outcomes, failures, and unverified areas using the shared orchestration handoff protocol. Do not perform a second general architecture review unless execution exposes a design issue. Do not change implementation code unless assigned.

shared/rules/definition-of-done.md

@@ -14,6 +14,7 @@ A task is only considered done when all applicable requirements below are fulfil
 * Verification is sufficient for the change's risk and scope, following `general.md`'s Verification rules. A build, test run, new test, or independent review is not required for every change.
 * Checks selected on that basis, and checks explicitly required by the user or project, have passed. Material gaps and pre-existing failures are reported without claiming unverified success.
 * Any delegated research, review, or verification is complete and its relevant findings are resolved or reported.
+* External technology claims MUST pass the verification checkpoint in `technical-research`. Required unsupported assumptions or missing execution evidence leave affected criteria unverified; a Context7 call alone does not establish completion.
 
 ## Code
 

shared/skills/implementation/integration-test-write/SKILL.md

@@ -10,11 +10,11 @@ Use when verifying behavior across a real application boundary, such as an API a
 ## Workflow
 
 1. Name the boundary under test and the production path the test must exercise. Keep unit-level details covered by unit tests.
-2. Reuse the repository's integration-test setup. Start only the services and data stores required for this behavior.
+2. Reuse the repository's integration-test setup. Before relying on external service, driver, or test-framework behavior, MUST apply the implementation checkpoint in `technical-research`. Start only the services and data stores required for this behavior.
 3. Prepare minimal isolated data and control external inputs. Prevent test runs from touching user data, shared environments, or live services.
 4. Cover a successful interaction and the failure or rejection path that matters to the change. Include transaction, retry, or cleanup behavior only when it is part of the contract.
 5. Assert persisted or externally observable outcomes, including relevant status, response, and side effects.
 6. Clean up created resources even when assertions fail. Make repeated runs safe and independent.
-7. Run the focused integration test and report required services, results, and any unavailable environment.
+7. Run the focused integration test and report required services, results, and any unavailable environment. MUST apply the verification checkpoint in `technical-research` to external contract claims; a mock or documentation excerpt cannot prove the real boundary works.
 
 Avoid turning an integration test into a full end-to-end suite when a narrower boundary proves the contract.

shared/skills/implementation/sql-write/SKILL.md

@@ -9,11 +9,11 @@ Use when writing or changing SQL statements, schema definitions, or database mig
 
 ## Workflow
 
-1. Identify the database engine and version, target schema, affected callers, and expected data shape. Inspect existing migrations and SQL style first.
+1. Identify the database engine and version, target schema, affected callers, and expected data shape. Inspect existing migrations and SQL style first. Before relying on engine-specific syntax, transaction, locking, or migration behavior, MUST apply the implementation checkpoint in `technical-research`.
 2. Parameterize values and validate any dynamic identifiers against an allowlist. Preserve tenant boundaries and authorization filters in every query path.
 3. For schema changes, consider existing rows, nullability, defaults, constraints, indexes, and deployment order. Prefer additive, backward-compatible steps when old and new application versions may overlap.
 4. Use transactions and explicit rollback or recovery steps where supported and appropriate. Estimate affected rows before broad updates or deletes.
 5. Do not execute destructive or production SQL without explicit authorization. A request to write SQL does not authorize running it against live data.
-6. Verify syntax and behavior against the intended engine, then inspect query results, migration ordering, and relevant application tests.
+6. Verify syntax and behavior against the intended engine, then inspect query results, migration ordering, and relevant application tests. MUST apply the verification checkpoint in `technical-research` to external claims; documentation cannot replace execution evidence.
 
 Report the database dialect, files or migration changed, verification, and any operational prerequisite.

shared/skills/implementation/unit-test-write/SKILL.md

@@ -10,10 +10,10 @@ Use when adding or updating tests for one isolated function, component, or decis
 ## Workflow
 
 1. Read the requirement and implementation. Identify the observable result that defines success and the boundary conditions most likely to fail.
-2. Follow the repository's existing test framework, naming, setup, and assertion style. Avoid new dependencies or fixtures when a small test can express the behavior.
+2. Follow the repository's existing test framework, naming, setup, and assertion style. Avoid new dependencies or fixtures when a small test can express the behavior. If test APIs, mocks, or expected outcomes depend on external behavior, MUST apply the implementation checkpoint in `technical-research` before encoding that assumption.
 3. Cover the normal case and the smallest meaningful set of boundary or failure cases. Include a regression case for a reported defect.
 4. Assert public behavior and useful error outcomes rather than private call order, incidental wording, or internal data layout.
 5. Keep each test deterministic. Control time, randomness, filesystem state, and external services when they affect the result.
-6. Run the focused test and report its result. Broaden verification only when shared behavior or connected components are affected.
+6. Run the focused test and report its result. MUST apply the verification checkpoint in `technical-research` to any external claims the result relies on. Broaden verification only when shared behavior or connected components are affected.
 
 Do not add tests that duplicate existing coverage or require production code to expose test-only hooks without a clear reason.

shared/skills/planning/change-impact-analysis/SKILL.md

@@ -12,7 +12,7 @@ Use before a change when its consumers, compatibility effects, or blast radius a
 1. Define the proposed change and the behavior or contract it affects.
 2. Locate direct callers, related implementations, shared helpers, configuration, generated output, and relevant tests. Start with exact-path and symbol searches; broaden only when the flow is unclear.
 3. Trace likely impact through runtime paths, persisted data, client integrations, deployment, and documentation as applicable.
-4. Identify compatibility concerns, failure modes, security or data-loss risks, and dependencies on version or environment.
+4. Identify compatibility concerns, failure modes, security or data-loss risks, and dependencies on version or environment. Before confirming external compatibility or recommending an approach, MUST apply the planning checkpoint in `technical-research` and attach matching evidence or mark the assumption unresolved.
 5. Separate confirmed impacts from assumptions and unknowns. Do not treat a possible downstream effect as a fact without evidence.
 6. Recommend proportionate verification tied to the risks found.
 

shared/skills/planning/work-item-definition/SKILL.md

@@ -12,7 +12,7 @@ Use when a request lacks enough detail to estimate or verify the intended techni
 1. State the user or system outcome in concrete terms.
 2. Define what is in scope and what is explicitly out of scope based on the request and current behavior.
 3. Write observable acceptance criteria, including relevant failure or edge cases.
-4. Record constraints, dependencies, compatibility requirements, and assumptions separately.
+4. Record constraints, dependencies, compatibility requirements, and assumptions separately. Before accepting external technology constraints as established, MUST apply the planning checkpoint in `technical-research`; carry its evidence or unresolved gaps into the work item.
 5. Ask only questions whose answers would materially change behavior, contracts, permissions, or acceptance. Choose safe reversible defaults for minor implementation details.
 6. Identify unresolved risks and a proportionate verification approach.
 

shared/skills/verification/facts-verification/SKILL.md

@@ -10,7 +10,7 @@ Use when an answer, report, or implementation decision depends on claims that ne
 ## Workflow
 
 1. Break the statement into atomic claims that can be checked independently.
-2. Choose evidence suited to each claim: current source, executable output, authoritative documentation, primary research, or direct measurement.
+2. Choose evidence suited to each claim: current source, executable output, authoritative documentation, primary research, or direct measurement. For external technology claims, MUST apply the verification checkpoint in `technical-research`, inspecting matching evidence or resolving gaps through its Context7-first workflow.
 3. Prefer the source closest to the fact. Check dates, versions, and applicability when the claim can change over time.
 4. Compare conflicting evidence and explain any difference in scope or version rather than silently selecting one.
 5. Label the result as confirmed, contradicted, inferred, or unknown. Keep confidence proportional to evidence quality.

shared/skills/verification/work-item-verification/SKILL.md

@@ -10,7 +10,7 @@ Use when deciding whether a completed change satisfies a defined work item or re
 ## Workflow
 
 1. Read the objective, scope boundaries, acceptance criteria, and material constraints.
-2. Map each criterion to direct evidence: changed files, observable behavior, command output, test result, or user-confirmed outcome.
+2. Map each criterion to direct evidence: changed files, observable behavior, command output, test result, or user-confirmed outcome. For criteria relying on external technology behavior, MUST apply the verification checkpoint in `technical-research`; check the actual supporting sources and version against the implementation, not merely whether a lookup occurred.
 3. Mark each criterion as met, unmet, or unverified. Do not treat a successful build as proof of unrelated behavioral criteria.
 4. Confirm the implementation stayed within scope and did not leave generated output, documentation, or consumers inconsistent.
 5. Record known limitations, unresolved decisions, and checks that could not run.