@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/skills/git-worktrees/SKILL.md

@@ -1,141 +1,161 @@
 ---
 name: git-worktrees
 license: BSD-3-Clause
-description: Use when starting feature work that needs isolation from current workspace — creates isolated git worktrees with safety verification. Fails closed, reporting and stopping without creating or deleting anything when the target directory is not ignored or a clean base commit cannot be verified.
+description: Use for feature work that needs an isolated Git worktree. If Git does not ignore a project-local directory, use the verified temporary-directory fallback. If repository guidance requires the local directory, report the problem. In that case, stop before creation. If the helper cannot verify a clean base commit, report the problem. In that case, stop before creation. Do not delete anything.
 argument-hint: <branch-name or feature description>
 allowed-tools: [Bash, Read]
 ---
 
-# Using Git Worktrees
+# Use Git worktrees
 
 ## Overview
 
-Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+Git worktrees are isolated workspaces that share one repository. You can work on multiple branches
+at the same time. You do not have to switch the active branch.
 
-**Working rule:** Systematic directory selection plus safety verification produces reliable
-isolation.
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to all
+prose that it produces.
 
-**When NOT to use this skill manually:** The `myrmidon-swarm` skill owns worktree creation for its
-background subagents. Use this skill for manual development work, not to duplicate swarm setup.
+**Rule:** Select the directory systematically. Then complete the safety checks. These actions give
+reliable isolation.
+
+**Do not use this skill for `myrmidon-swarm` worktrees.** That skill creates worktrees for its
+background subagents. Use this skill for manual development work.
 
 ## Engineering principles
 
-Use the [canonical engineering-principles catalog](../../docs/principles/README.md) through these
+Use the [canonical engineering-principles catalog](../_support/docs/principles/README.md) for these
 workflow-specific rules:
 
-- [P010 — Scope Fidelity](../../docs/principles/README.md#p010): create only the requested isolated
-  branch and worktree; leave cleanup and unrelated repository changes to their owning workflows.
-- [P012 — Evidence Before Modification](../../docs/principles/README.md#p012): inspect repository
-  guidance, the selected base revision, directory state, ignore rules, and baseline checks first.
-- [P021 — Evolutionary and Reversible Design](../../docs/principles/README.md#p021): isolate feature
-  work at an exact base so it can be reviewed, integrated, preserved, or abandoned independently.
-- [P033 — State-Safe Failure Semantics](../../docs/principles/README.md#p033): fail before creation
-  when validation fails and preserve any created worktree when later setup or tests fail.
-- [P053 — Validate at Trust Boundaries](../../docs/principles/README.md#p053): pass branch, base, path,
-  and path-root values through the tested helper's validation rather than composing raw Git commands.
-- [P058 — Bounded Agent Authority](../../docs/principles/README.md#p058): bind creation to the named
-  branch, exact start SHA, validated destination, and requested feature scope.
-- [P065 — Verify Before Claiming Completion](../../docs/principles/README.md#p065): report the actual
-  path and start SHA and run the repository-defined clean-baseline checks before declaring readiness.
-- [P083 — Irreversible Actions Last](../../docs/principles/README.md#p083): complete dry-run and safety
-  validation before creating the branch and worktree, and delegate later removal to `tidy`.
-
-## Directory Selection
+- [P010 — Scope Fidelity](../_support/docs/principles/README.md#p010): Make only the requested isolated
+  branch and worktree. Delegate cleanup and unrelated changes to the applicable workflows.
+- [P012 — Evidence Before Modification](../_support/docs/principles/README.md#p012): Before creation,
+  examine repository guidance, the selected base revision, directory state, ignore rules, and
+  baseline checks.
+- [P021 — Evolutionary and Reversible Design](../_support/docs/principles/README.md#p021): Put feature work
+  in an isolated worktree at the selected base commit. Only if you have user authority and can use
+  the cleanup workflow, remove the worktree.
+- [P033 — State-Safe Failure Semantics](../_support/docs/principles/README.md#p033): If validation is not
+  satisfactory, stop before creation. If setup or a test after creation is not satisfactory, keep
+  the worktree.
+- [P053 — Validate at Trust Boundaries](../_support/docs/principles/README.md#p053): Use the tested helper
+  to validate branch, base, path, and path-root values. Do not use these values in a Git command
+  without the helper.
+- [P058 — Bounded Agent Authority](../_support/docs/principles/README.md#p058): Make only the named branch
+  and worktree for the requested feature. Use the selected start commit and validated destination.
+- [P065 — Verify Before Claiming Completion](../_support/docs/principles/README.md#p065): Before you report
+  that you prepared the worktree, do the repository checks for a clean baseline. Report the path
+  and start commit.
+- [P083 — Irreversible Actions Last](../_support/docs/principles/README.md#p083): Before creation, complete
+  the dry-run. Before creation, complete the safety validation. Use `tidy` for removal.
+
+## Select the directory
 
 Follow this priority order:
 
-### 1. Check Existing Directories
+### 1. Check existing directories
 
 The tested `scripts/prepare_worktree.py` helper checks `.worktrees` and then `worktrees`. If both
-exist, `.worktrees` wins.
+directories exist, the helper selects `.worktrees`.
 
 ### 2. Check repository guidance
 
-Read `AGENTS.md` and its referenced repository guidance. If a preference is specified, pass it to
-the helper with `--directory DIRECTORY`.
+Read `AGENTS.md` and its referenced repository guidance. If repository guidance specifies a
+preference, pass it to the helper with `--directory DIRECTORY`.
 
 ### 3. Portable default
 
-When no repository preference exists, use the host's temporary directory from
-`tempfile.gettempdir()` with `<project>-<branch>`. This is commonly `/tmp` on Unix-like hosts and
-avoids polluting the project directory.
+If the repository does not specify a location, use the host temporary directory from
+`tempfile.gettempdir()` with `<project>-<branch>`. On Unix-like hosts, this directory is usually
+`/tmp`. This location keeps the worktree outside the project directory.
 
 The helper computes the project name from the repository root.
 
-## Safety Verification
+## Verify safety
 
-### For Project-Local Directories (.worktrees or worktrees)
+### For project-local directories
 
-**MUST verify directory is ignored before creating worktree.** The helper fails closed when its
-project-local directory is not ignored.
+Before you create a project-local worktree, verify that Git ignores its directory. If Git does not
+ignore the directory, the helper stops before it makes a change.
 
-**If NOT ignored:**
+#### If Git does not ignore the directory
 
-1. Do not silently edit or commit `.gitignore`, and do not create the project-local worktree.
-2. Prefer a safe temporary destination by passing both
-   `--path <temporary-root>/<project>-<branch>` and `--path-root <temporary-root>` to the helper;
-   derive `<temporary-root>` from the host and report the fallback path.
-3. If repository guidance requires the project-local directory, report the unmet ignore-policy
-   prerequisite and stop. Change `.gitignore` only as a separately authorized, scoped change; after
-   that change is validated and committed, rerun worktree preparation.
+1. Do not edit `.gitignore`.
+2. Do not commit `.gitignore`.
+3. Do not create the project-local worktree.
+4. If repository guidance requires the project-local directory, report the ignore-policy
+   prerequisite.
+5. If repository guidance requires the project-local directory, stop.
+6. Change `.gitignore` only in a separate authorized change.
+7. After that change is validated and committed, prepare the worktree again.
+8. If repository guidance does not require the project-local directory, get `<temporary-root>` from
+   the host.
+9. Give preference to a safe temporary destination.
+10. Pass `--path <temporary-root>/<project>-<branch>` and `--path-root <temporary-root>` to the helper.
+11. Report the fallback path.
 
-**Why critical:** Prevents accidentally committing worktree contents to repository.
+This check prevents Git from tracking the worktree contents.
 
-### For /tmp Locations
+### For `/tmp` locations
 
-No `.gitignore` verification needed — outside the project entirely.
+You do not have to verify `.gitignore` for a path under `/tmp`. This path is outside the project.
 
-## Creation Steps
+## Create the worktree
 
-1. Resolve and record the intended base commit SHA.
-2. Keep the target repository as the current working directory. Resolve `scripts/prepare_worktree.py`
-   against this installed skill directory and invoke that absolute helper path with
-   `BRANCH_NAME --start-point BASE_SHA --dry-run`. For a contract requiring a distinct branch and
-   path, also pass exact `--path` and `--path-root` values.
-3. Create it with the same arguments without `--dry-run`, optionally supplying the documented
-   repository preference through `--directory`. When an unignored local directory requires the
-   temporary fallback, pass the same exact `--path` and `--path-root` to both calls. Never replace
-   the recorded SHA with ambient HEAD.
-4. Change to the returned path and run the repository-defined bootstrap when one exists.
-5. Verify a clean baseline with the repository-defined tests and report the path, start SHA, and result.
+1. Resolve the intended base commit SHA.
+2. Record the intended base commit SHA.
+3. Keep the target repository as the current working directory.
+4. Resolve `scripts/prepare_worktree.py` from this installed skill directory.
+5. Prepare `BRANCH_NAME --start-point BASE_SHA --dry-run` as the helper arguments.
+6. If the contract requires a distinct branch and path, add exact `--path` and `--path-root` values.
+7. If repository guidance specifies a directory, add it through `--directory`.
+8. If an unignored local directory requires the temporary fallback, retain the exact `--path` and
+   `--path-root` values.
+9. For this fallback, use those values for both helper calls.
+10. Invoke the helper by its absolute path with the prepared dry-run arguments.
+11. Create the worktree with the same arguments without `--dry-run`.
+12. Do not replace the recorded SHA with the current `HEAD`.
+13. Change to the returned path.
+14. If the repository defines a bootstrap, run it.
+15. Use the repository tests to verify a clean baseline.
+16. Report the path, start SHA, and result.
 
-**If tests fail:** Report failures, ask whether to proceed or investigate.
+**If the tests fail:** Report the failures. Ask whether to continue or investigate.
 
-**If tests pass:** Report ready.
+**If the tests pass:** Report that the worktree is ready.
 
-## Cleanup
+## Clean up
 
-When work is done, invoke `tidy` for branch and worktree cleanup. It prepares the trusted
-Hephaestus dependency and delegates directly to `hephaestus-tidy`, whose interactive workflow owns
-discovery, preservation rules, deletion prompts, rebases, and cleanup safeguards. Do not duplicate
-that policy or improvise deletion commands in this skill.
+When the work is complete, invoke `tidy` for branch and worktree cleanup. `tidy` prepares the trusted
+Hephaestus dependency. It delegates the work directly to `hephaestus-tidy`. The interactive workflow
+controls discovery, preservation rules, deletion prompts, rebases, and cleanup safeguards. Do not
+duplicate that policy. Do not write deletion commands in this skill.
 
 Preserve the worktree by default. Delivery, merge, abandonment, or a general cleanup request does
-not itself authorize this skill to remove it; route any cleanup through `tidy` and leave the
-decision to the Hephaestus workflow and the user's answers to its prompts.
+not authorize this skill to remove the worktree. Use `tidy` for each cleanup. The Hephaestus
+workflow and the user's answers to its prompts control the removal decision.
 
 ## Quick Reference
 
 | Situation | Action |
 | ----------- | -------- |
-| `.worktrees/` exists + ignored | Use it |
+| `.worktrees/` exists and is ignored | Use it. |
 | Neither exists | Use the host temporary directory with `<project>-<branch>` |
-| Directory not ignored | Use and report an explicit temporary path, or stop on a repository-mandated local path |
-| Tests fail at baseline | Report failures + ask before proceeding |
+| Directory is not ignored | Use an explicit temporary path. Report the path. If the repository requires a local path, stop. |
+| Tests fail at baseline | Report the failures. Ask before you continue. |
 
 ## Failed approaches
 
-- **Skipping ignore verification** for project-local worktrees → contents get tracked
-- **Proceeding with failing baseline** → can't distinguish new bugs from pre-existing
-- **Not cleaning up** → stale worktrees accumulate
-
-## Integration
+- Do not skip ignore verification for a project-local worktree. Git can track the worktree contents.
+- If the baseline tests fail, do not continue unless the user explicitly tells you to continue. You
+  cannot separate new defects from existing defects.
+- When cleanup is authorized, use `tidy`. Do not leave stale worktrees.
 
-**Pairs with:**
+## Related workflow
 
 - Invoke `tidy` for dependency-locked delegation to Hephaestus branch and worktree cleanup.
-- Verify with fresh runnable evidence per the evidence-integrity policy before finishing and
-  cleaning up.
+- Before you report completion or start cleanup, get fresh runnable evidence. Follow the
+  [evidence-integrity policy](../_support/docs/policies/evidence-integrity.md).
 
 ---
 

package/skills/git-worktrees/scripts/prepare_worktree.py

@@ -1,18 +1,31 @@
 #!/usr/bin/env python3
-"""Select, validate, and optionally create an isolated Git worktree."""
+"""Prepare an isolated Git worktree."""
 
 from __future__ import annotations
 
+import importlib.util
 import json
 import subprocess
 import sys
 import tempfile
 from pathlib import Path
-
-if __package__ in {None, ""}:
-    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
-
-from skills._cli import argument_parser, run_command
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING or __package__ not in {None, ""}:
+    from skills._cli import argument_parser, run_command
+else:
+    _cli_path = Path(__file__).resolve().parents[2] / "_cli.py"
+    _cli_spec = importlib.util.spec_from_file_location(
+        "athena_installed_cli", _cli_path
+    )
+    if _cli_spec is None or _cli_spec.loader is None:
+        raise RuntimeError(
+            f"The installed Athena CLI helper is unavailable: '{_cli_path}'."
+        )
+    _cli = importlib.util.module_from_spec(_cli_spec)
+    _cli_spec.loader.exec_module(_cli)
+    argument_parser = _cli.argument_parser
+    run_command = _cli.run_command
 
 
 def git(
@@ -22,23 +35,27 @@ def git(
         ["git", *arguments], cwd=cwd, capture_output=True, text=True, check=False
     )
     if check and result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or f"git {' '.join(arguments)} failed")
+        raise RuntimeError(
+            result.stderr.strip() or f"The git {' '.join(arguments)} command failed."
+        )
     return result
 
 
 def reject_symlinks_below(trust_root: Path, target: Path) -> None:
-    """Reject symlinks in the caller-controlled path below a trusted root."""
+    """Reject symbolic links in a caller-controlled path below a trusted root."""
     lexical_root = trust_root.absolute()
     lexical_target = target.absolute()
     try:
         lexical_target.relative_to(lexical_root)
     except ValueError as error:
         raise RuntimeError(
-            f"worktree path escapes trusted root {lexical_root}"
+            f"The worktree path is outside the trusted root: '{lexical_root}'."
         ) from error
     for component in (*reversed(lexical_target.parents), lexical_target):
         if component.is_symlink():
-            raise RuntimeError(f"worktree path component is a symlink: {component}")
+            raise RuntimeError(
+                f"A component of the worktree path is a symbolic link: '{component}'."
+            )
 
 
 def select_path(
@@ -66,7 +83,8 @@ def select_path(
         if directory.is_dir():
             if directory.is_symlink():
                 raise RuntimeError(
-                    f"project-local worktree directory is a symlink: {directory}"
+                    "The project-local worktree directory is a symbolic link: "
+                    f"'{directory}'."
                 )
             return (directory / branch).resolve(), True
     project = root.name
@@ -82,7 +100,8 @@ def verify_ignored(root: Path, path: Path) -> None:
     result = git(root, "check-ignore", "-q", "--", str(probe), check=False)
     if result.returncode != 0:
         raise RuntimeError(
-            f"project-local worktree directory {relative.parent} is not ignored"
+            "Git did not confirm that it ignores the project-local worktree directory: "
+            f"'{relative.parent}'."
         )
 
 
@@ -102,9 +121,9 @@ def main() -> int:
             root, "check-ref-format", "--branch", arguments.branch, check=False
         )
         if branch_check.returncode != 0:
-            raise RuntimeError(f"invalid branch name: {arguments.branch}")
+            raise RuntimeError(f"The branch name is not valid: '{arguments.branch}'.")
         if (arguments.path is None) != (arguments.path_root is None):
-            raise RuntimeError("--path and --path-root must be provided together")
+            raise RuntimeError("Specify '--path' and '--path-root' together.")
         path, project_local = select_path(
             root,
             arguments.branch,
@@ -121,7 +140,7 @@ def main() -> int:
         if project_local:
             verify_ignored(root, path)
         if path.exists():
-            raise RuntimeError(f"worktree path already exists: {path}")
+            raise RuntimeError(f"The worktree path already exists: '{path}'.")
         if not arguments.dry_run:
             git(
                 root,

package/skills/issue-review/SKILL.md

@@ -1,106 +1,163 @@
 ---
 name: issue-review
 license: BSD-3-Clause
-description: Review a GitHub or GitLab issue and its current plan-issue artifact for architecture alignment, scope, risks, and behavior-first verification. Use before implementation; `--report-only` is read-only.
+description: Use before implementation to review a GitHub or GitLab issue and its current `plan-issue` artifact. Check architecture, scope, risk, and behavior-first verification. Use `--report-only` for read-only work.
 argument-hint: "[--report-only] ISSUE_NUMBER_OR_URL"
 allowed-tools: [Read, Bash, Grep, Glob, Agent, WebFetch]
 ---
 
 # Review an issue and plan
 
-Why: find architecture, scope, and verification gaps while changing the plan is
-still cheaper than changing code.
+Purpose: Review the plan before implementation. Early review helps you find architecture, scope,
+and verification gaps before code changes start.
 
-Use the shared [issue-planning contract](../../docs/review/issue-planning.md),
-[review contract](../../docs/review/common.md),
-[language routing](../../docs/review/language-routing.md), and
-[behavior-first testing](../../docs/review/behavior-first-testing.md).
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to all
+prose that it produces.
+
+Use the shared [issue-planning contract](../_support/docs/review/issue-planning.md),
+[review contract](../_support/docs/review/common.md),
+[language routing](../_support/docs/review/language-routing.md), and
+[behavior-first testing](../_support/docs/review/behavior-first-testing.md).
 
 ## Engineering principles
 
-Apply the canonical [engineering-principles catalog](../../docs/principles/README.md) through these
-review decisions:
-
-- [P010 Scope Fidelity](../../docs/principles/README.md#p010) keeps the current issue and canonical
-  plan as the complete review target, while
-  [P066 Preserve Existing Work](../../docs/principles/README.md#p066) prevents the review from
-  rewriting foreign or historical artifacts.
-- [P012 Evidence Before Modification](../../docs/principles/README.md#p012),
-  [P063 Requirement-to-Code Traceability](../../docs/principles/README.md#p063), and
-  [P072 Technical Evidence Over Preference](../../docs/principles/README.md#p072) require every gap
-  to be grounded in current requirements, repository evidence, and an affected contract.
-- [P015 Architecture Conformance](../../docs/principles/README.md#p015) makes unexplained boundary
-  violations blocking;
-  [P071 Consistency Over Personal Preference](../../docs/principles/README.md#p071) preserves
-  repository conventions unless contrary technical evidence exists; and
-  [P008 Understand Before Subtracting](../../docs/principles/README.md#p008) requires evidence about
-  consumers and purpose before approving deletion or consolidation.
+Use the canonical [engineering-principles catalog](../_support/docs/principles/README.md) for these review
+decisions:
+
+- [P010 Scope Fidelity](../_support/docs/principles/README.md#p010): Use the current issue and canonical
+  plan as the full review target.
+- [P066 Preserve Existing Work](../_support/docs/principles/README.md#p066): Do not rewrite historical
+  artifacts or artifacts that a different actor owns.
+- [P012 Evidence Before Modification](../_support/docs/principles/README.md#p012): Before you accept a
+  plan, examine current requirements and repository evidence.
+- [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063): For each gap,
+  find the related requirement or contract.
+- [P072 Technical Evidence Over Preference](../_support/docs/principles/README.md#p072): Give technical
+  evidence for each gap. Do not use personal preference as evidence.
+- [P015 Architecture Conformance](../_support/docs/principles/README.md#p015): If a boundary violation has
+  no explanation, do not accept the plan.
+- [P071 Consistency Over Personal Preference](../_support/docs/principles/README.md#p071): If technical
+  evidence does not show a necessary change, obey repository conventions.
+- [P008 Understand Before Subtracting](../_support/docs/principles/README.md#p008): Before you accept
+  deletion or consolidation, examine the consumers and purpose.
 
 ## Scope and delivery
 
-The issue is the requirements source; review only its current canonical plan.
-Resolve plan ownership, marker, absence, and identity under the issue-planning
-contract. Historical plans and reviews are bounded context, not the artifact
-under review.
+Use the issue as the requirements source. Review only its current canonical plan. Use the
+issue-planning contract to identify the plan owner, marker, presence or absence, and identity. Use
+historical plans and reviews only as background information.
+
+If the request includes `--report-only`, this skill is read-only. Do not publish a comment. If the
+request does not include this option, first compare the required identities. Then, confirm a safe
+forge capability. You can then publish exactly one actor-owned structured review comment. Do not
+expand the scope to these items:
 
-`--report-only` is read-only. A requested review without it may publish exactly
-one actor-owned structured review comment after the required identity comparison
-and forge-capability check. It does not expand scope to labels, assignment,
-implementation, commit, push, pull request, merge, or issue closure.
+- labels;
+- assignment;
+- implementation;
+- commit;
+- push;
+- pull request;
+- merge; or
+- issue closure.
 
 ## Review
 
-1. Read the issue, linked work, canonical plan, repository guidance, ADRs,
-   relevant code, tests, and public contracts.
-2. Decide architecture first under
-   [P015 Architecture Conformance](../../docs/principles/README.md#p015): aligned, intentional and
-   justified change, or an unexplained violation. A material violation blocks a positive assessment.
-3. Map every acceptance criterion under
-   [P063 Requirement-to-Code Traceability](../../docs/principles/README.md#p063) to a concrete plan
-   step, affected boundary, and behavior-first validation step. For a material architecture change,
-   verify that the plan includes or cites a
-   [design record](../../docs/review/design-docs.md).
-4. Verify cited paths, symbols, commands, dependencies, assumptions, risks,
-   migration, and rollback claims against current repository evidence as required by
-   [P012 Evidence Before Modification](../../docs/principles/README.md#p012).
-5. Apply only activated language and change-surface checks, recording N/A
-   sections and reasons. Activate
-   [P001 KISS — Keep It Simple, Stupid](../../docs/principles/README.md#p001) for added
-   complexity, [P022 Test Behavior, Not Implementation](../../docs/principles/README.md#p022) for
-   testable behavior,
-   [P029 Generalize Error Policy; Preserve Specific Cause](../../docs/principles/README.md#p029) for
-   error paths, and [P048 Secure by Design](../../docs/principles/README.md#p048) for security or new
-   trust boundaries. Confirm that relevant prior findings are resolved, rather than merely
-   acknowledged.
-
-Prioritize architecture violations, missing requirements, unsafe scope,
-unresolved dependencies, untestable outcomes, invalid references,
-non-deterministic tests, empty selections, and unsupported claims.
-
-When reviewing after a finalized epoch, do not reinterpret generated plan text
-or sealed provenance as new requirements. Review only a later material issue
-change and its current canonical plan; an unchanged finalized epoch is not a
-new review target.
-
-Immediately before a requested publication, re-resolve the canonical planning
-identity. On drift, foreign or multiple markers, verified absence changes, or
-missing safe forge capability, withhold the comment and return the review as
-stale. Otherwise publish exactly one actor-owned structured comment, including
-a clean result or verified absent-plan coverage gap.
+1. Read the issue, linked work, canonical plan, repository guidance, architecture decision records
+   (ADRs), applicable code, tests, and public contracts.
+2. Under [P015 Architecture Conformance](../_support/docs/principles/README.md#p015), select one architecture
+   result:
+
+   - aligned;
+   - intentional and justified change; or
+   - unexplained violation.
+
+   A material violation prevents a positive assessment.
+3. Under [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063), map each
+   acceptance criterion to a concrete plan step, affected boundary, and behavior-first validation
+   step.
+4. If the plan contains a material architecture change, verify that it includes or cites a
+   [design record](../_support/docs/review/design-docs.md).
+5. Under [P012 Evidence Before Modification](../_support/docs/principles/README.md#p012), verify these claims
+   against current repository evidence:
+
+   - paths;
+   - symbols;
+   - commands;
+   - dependencies;
+   - assumptions;
+   - risks;
+   - migration; and
+   - rollback.
+
+6. Apply only the language and change-surface checks that the review scope activates.
+7. Record each not applicable (`N/A`) section and its reason.
+8. Activate these principle checks only for their specified surfaces:
+
+   - Use [P001 KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001) for added
+     complexity.
+   - Use [P022 Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022) for testable
+     behavior.
+   - Use
+     [P029 Generalize Error Policy; Preserve Specific Cause](../_support/docs/principles/README.md#p029) for
+     error paths.
+   - Use [P048 Secure by Design](../_support/docs/principles/README.md#p048) for security or new trust
+     boundaries.
+
+9. Confirm that each applicable prior finding is resolved. Acknowledgment alone does not resolve a
+   finding.
+
+Give priority to these findings:
+
+- architecture violations;
+- missing requirements;
+- unsafe scope;
+- unresolved dependencies;
+- outcomes that cannot be tested;
+- invalid references;
+- nondeterministic tests;
+- empty selections; and
+- unsupported claims.
+
+After a finalized epoch, do not treat generated plan text or sealed provenance as new requirements.
+Review only a later material issue change and its current canonical plan. An unchanged finalized
+epoch is not a new review target.
+
+Immediately before you publish the requested comment, resolve the canonical planning identity again.
+If one of these conditions is true, withhold the comment:
+
+- identity drift;
+- a foreign marker;
+- multiple markers;
+- a change to verified absence; or
+- no safe forge capability.
+
+If you withhold the comment, report the `stale` status.
+
+Otherwise, publish exactly one actor-owned structured comment. Include a clean result or verified
+absent-plan coverage gap.
 
 ## Failed approaches
 
-- Reviewing issues or plans outside the requested scope set, or treating historical plans as the
+- Do not review issues or plans outside the requested scope. Do not treat historical plans as the
   artifact under review.
-- Editing the issue, labels, or assignment instead of reporting findings through the review
-  comment.
-- Inventing acceptance criteria the reporter did not state, or accepting acknowledged-but-unresolved
-  prior findings as resolved.
-- Republishing after drift instead of withholding the comment as stale.
+- Do not edit the issue, labels, or assignment. If publication is authorized, report findings only in
+  the structured review comment. For `--report-only`, return the findings without publication.
+- Do not invent acceptance criteria that the reporter did not state. Do not accept an unresolved
+  prior finding only because someone acknowledged it.
+- After drift, do not publish the comment again. Withhold it. Report `stale`.
 
 ## Result
 
-Return issue and plan identities, architecture decision first, requirement
-mapping, severity-ranked findings, test-quality coverage, N/A sections,
-residual risks, and whether the comment was published or withheld. A review
-never expands scope to implementation or merge.
+Return these items:
+
+- issue and plan identities;
+- the architecture decision first;
+- the requirement map;
+- severity-ranked findings;
+- test-quality coverage;
+- `N/A` sections;
+- residual risks; and
+- whether you published or withheld the comment.
+
+Do not expand the review scope to implementation or merge.