@homericintelligence/athena-opencode 0.4.4

package/skills/finalize-plan/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: finalize-plan
+license: BSD-3-Clause
+description: Materialize one exact, actor-owned, GO-reviewed issue-planning epoch into its implementation-facing issue body. Use after plan-issue and issue-review approve a plan; `--draft` is read-only and every missing, foreign, stale, ambiguous, or unverifiable input fails closed.
+argument-hint: "[--draft] ISSUE_NUMBER_OR_URL"
+allowed-tools: [Read, Bash, Grep, Glob]
+---
+
+# Finalize an approved issue plan
+
+Why: an approved plan should be the readable implementation entry point without
+turning review history, suggestions, or a generated body into new requirements.
+
+Use the shared [issue-planning contract](../../docs/review/issue-planning.md),
+[review contract](../../docs/review/common.md),
+[design-document structure](../../docs/review/design-docs.md),
+[language routing](../../docs/review/language-routing.md), and
+[behavior-first testing](../../docs/review/behavior-first-testing.md).
+
+## Scope and delivery
+
+`--draft` is read-only. Without it, this skill may replace the resolved issue
+body once and, only after exact body readback, delete the two sealed,
+actor-owned plan and review comments. It must not update the title, labels,
+assignment, milestone, project fields, state, branches, pull requests, or
+repository files. The finalized body retains the required provenance after
+those intermediate comments are removed.
+
+Use the forge's native issue-body mechanism. If the host cannot authenticate the
+actor, enumerate and delete exact comments, read the issue body, compare
+identities, or make and read back one exact body update, return a
+ready-to-publish draft and identify the capability gap. Never create, adopt,
+edit, or replace plan or review comments to make finalization possible.
+
+## Finalized planning epoch
+
+An epoch has these sealed source identities:
+
+- `R`: the canonical digest of the original issue requirements: exact issue ID,
+  title, body, and acceptance criteria before finalization;
+- `P`: one actor-owned `<!-- athena:plan-issue -->` comment ID and canonical
+  plan-content digest; and
+- `V`: one actor-owned `<!-- athena:issue-review -->` comment ID and
+  review-content digest.
+
+The review must embed and exactly match the same issue, `R`, plan-comment ID,
+and `P`. It must have an exact `GO` disposition with no unresolved `critical`,
+`major`, or other `required` finding. A conditional, partial, malformed, stale,
+foreign, duplicated, absent, or unverifiable artifact is not authorization.
+
+The rendered body records exactly one marker:
+`<!-- athena:finalize-plan R=<R> P=<P> V=<V> F=<F> -->`. Define `F` by hashing
+the final body after replacing that marker's `F` value with the literal
+`<F>` placeholder; do not hash a marker containing its own digest. The marker
+lets a host distinguish sealed source identities from the generated body and
+verify later readback without recursion.
+
+## Finalize
+
+1. Resolve one exact issue, including node or URL, title, body, state, and
+   authenticated actor. Enumerate every current comment before interpreting a
+   marker.
+2. Resolve exactly one actor-owned plan marker and one actor-owned review marker.
+   Compute `R`, `P`, and `V`, then verify the review's embedded bindings and
+   clean GO result. Any ownership, multiplicity, binding, disposition, or
+   required-finding failure returns no write.
+3. Build a compact, lossless synthesis. Lead with **Why** (the preserved
+   original problem, outcome, and non-negotiable requirements), then include a
+   compact system-shape diagram only when it makes at least three relationships,
+   boundaries, or state transitions materially clearer. Follow with architecture
+   breakdown, implementation plan, operations, and provenance.
+4. Preserve every acceptance criterion, implementation boundary, validation,
+   migration or cutover step, rollback condition, dependency, residual risk, and
+   out-of-scope decision. Record review suggestions as optional residual context
+   unless the reviewed canonical plan already adopted them. Do not invent files,
+   commands, requirements, architecture, implementation results, or validation
+   evidence; do not copy historical revision transcripts or duplicate the plan
+   and review verbatim when a smaller lossless synthesis suffices.
+5. Add the finalized marker and compute `F` over its non-self-referential
+   canonical representation. In `--draft`, return the complete body, `R/P/V/F`,
+   source links, and all withheld-write reasons without invoking a forge write.
+6. Immediately before publication, resolve the issue, actor, every comment and
+   marker, `R/P/V`, review disposition, and target body again. If any input
+   drifted, return the ready-to-publish body as stale; do not write.
+7. Publish exactly one issue-body replacement. Read the issue back immediately
+   and verify the exact body, marker, `R/P/V`, and `F`. A timeout, indeterminate
+   response, or mismatched readback is an unknown outcome: do not retry or make
+   another mutation.
+8. After successful body readback, re-read each sealed comment by its exact ID,
+   actor, marker, and digest, then delete the plan comment and review comment.
+   Delete no foreign, replacement, or drifted comment. A failed, timed-out, or
+   indeterminate deletion is a partial-cleanup unknown outcome: do not retry,
+   compensate, or remove the finalized body; report the surviving identities.
+
+## Re-finalization and restart
+
+If the live body exactly verifies its finalized marker and both sealed comments
+are absent, re-running for that epoch returns a documented no-change result. A
+surviving sealed comment is partial cleanup, not authorization to retry a prior
+deletion. If the marker is absent, malformed, foreign, or its canonical `F` does
+not match, the epoch is not valid evidence. A later material human edit is a new
+requirements state and must pass a fresh `plan-issue` plus `issue-review` cycle
+before another finalization. Do not treat generated plan text or provenance
+fields as newly authored requirements.
+
+## Behavior-first verification
+
+Use controlled issue, comment, actor, and forge fixtures to demonstrate:
+
+- one clean GO plan/review epoch preserves requirements and operational details;
+- `--draft` returns the body without a forge mutation;
+- publish performs one body update, verifies its exact readback, then deletes
+  only the two sealed actor-owned comments;
+- an unchanged sealed epoch is idempotent; and
+- every absent, foreign, duplicate, mismatched, stale, NO-GO, required-finding,
+  drift, unsupported-write, timeout, readback-mismatch, or deletion-uncertainty
+  case fails before an unsafe mutation or retry.
+
+Assert identities, ordering classes, preservation, mutation count and scope, and
+failure-before-write behavior. Do not freeze editorial wording, headings,
+paragraph counts, or an example issue body.
+
+## Result
+
+Return the issue and actor identities; `R/P/V/F`; GO decision and finding
+summary; requirement-preservation map; draft, no-change, published, stale,
+partial-cleanup, or unknown-outcome status; body-update receipt, readback
+evidence, deleted-comment receipts when present; and every unresolved capability
+or residual risk.

package/skills/git-worktrees/SKILL.md

@@ -0,0 +1,113 @@
+---
+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
+argument-hint: <branch-name or feature description>
+allowed-tools: [Bash, Read]
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**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.
+
+## Directory Selection
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+The tested `scripts/prepare_worktree.py` helper checks `.worktrees` and then `worktrees`. If both
+exist, `.worktrees` wins.
+
+### 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`.
+
+### 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.
+
+The helper computes the project name from the repository root.
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is ignored before creating worktree.** The helper fails closed when its
+project-local directory is not ignored.
+
+**If NOT ignored:**
+
+1. Add `.worktrees/` to `.gitignore`
+2. Commit the change
+3. Then proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For /tmp Locations
+
+No `.gitignore` verification needed — outside the project entirely.
+
+## Creation Steps
+
+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`. 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.
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+## Cleanup
+
+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.
+
+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.
+
+## Quick Reference
+
+| Situation | Action |
+| ----------- | -------- |
+| `.worktrees/` exists + ignored | Use it |
+| Neither exists | Use the host temporary directory with `<project>-<branch>` |
+| Directory not ignored | Add to `.gitignore` + commit first |
+| Tests fail at baseline | Report failures + ask before proceeding |
+
+## Common Mistakes
+
+- **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
+
+**Pairs with:**
+
+- 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.
+
+---
+
+_Adapted from [obra/superpowers](https://github.com/obra/superpowers) under the [MIT License](https://github.com/obra/superpowers/blob/main/LICENSE). Copyright (c) 2025 Jesse Vincent._

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

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Select, validate, and optionally create an isolated Git worktree."""
+
+from __future__ import annotations
+
+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
+
+
+def git(
+    cwd: Path, *arguments: str, check: bool = True
+) -> subprocess.CompletedProcess[str]:
+    result = run_command(
+        ["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")
+    return result
+
+
+def reject_symlinks_below(trust_root: Path, target: Path) -> None:
+    """Reject symlinks in the 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}"
+        ) 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}")
+
+
+def select_path(
+    root: Path,
+    branch: str,
+    requested: Path | None,
+    exact_path: Path | None,
+    path_root: Path | None,
+) -> tuple[Path, bool]:
+    if exact_path is not None:
+        path = exact_path if exact_path.is_absolute() else root / exact_path
+        trust_root = path_root if path_root is not None else path.parent
+        if not trust_root.is_absolute():
+            trust_root = root / trust_root
+        reject_symlinks_below(trust_root, path)
+        resolved_path = path.resolve()
+        return resolved_path, resolved_path.is_relative_to(root)
+    if requested is not None:
+        base = requested if requested.is_absolute() else root / requested
+        path = base / branch
+        reject_symlinks_below(base, path)
+        return path.resolve(), path.resolve().is_relative_to(root)
+    for directory_name in (".worktrees", "worktrees"):
+        directory = root / directory_name
+        if directory.is_dir():
+            if directory.is_symlink():
+                raise RuntimeError(
+                    f"project-local worktree directory is a symlink: {directory}"
+                )
+            return (directory / branch).resolve(), True
+    project = root.name
+    return Path(tempfile.gettempdir()) / f"{project}-{branch}", False
+
+
+def verify_ignored(root: Path, path: Path) -> None:
+    try:
+        relative = path.relative_to(root)
+    except ValueError:
+        return
+    probe = relative.parent / ".athena-ignore-probe"
+    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"
+        )
+
+
+def main() -> int:
+    parser = argument_parser(description=__doc__)
+    parser.add_argument("branch")
+    path_selection = parser.add_mutually_exclusive_group()
+    path_selection.add_argument("--directory", type=Path)
+    path_selection.add_argument("--path", type=Path)
+    parser.add_argument("--path-root", type=Path)
+    parser.add_argument("--start-point", required=True)
+    parser.add_argument("--dry-run", action="store_true")
+    arguments = parser.parse_args()
+    try:
+        root = Path(git(Path.cwd(), "rev-parse", "--show-toplevel").stdout.strip())
+        branch_check = git(
+            root, "check-ref-format", "--branch", arguments.branch, check=False
+        )
+        if branch_check.returncode != 0:
+            raise RuntimeError(f"invalid branch name: {arguments.branch}")
+        if (arguments.path is None) != (arguments.path_root is None):
+            raise RuntimeError("--path and --path-root must be provided together")
+        path, project_local = select_path(
+            root,
+            arguments.branch,
+            arguments.directory,
+            arguments.path,
+            arguments.path_root,
+        )
+        start_sha = git(
+            root,
+            "rev-parse",
+            "--verify",
+            f"{arguments.start_point}^{{commit}}",
+        ).stdout.strip()
+        if project_local:
+            verify_ignored(root, path)
+        if path.exists():
+            raise RuntimeError(f"worktree path already exists: {path}")
+        if not arguments.dry_run:
+            git(
+                root,
+                "worktree",
+                "add",
+                str(path),
+                "-b",
+                arguments.branch,
+                start_sha,
+            )
+    except RuntimeError as error:
+        print(error, file=sys.stderr)
+        return 1
+    print(
+        json.dumps(
+            {
+                "branch": arguments.branch,
+                "created": not arguments.dry_run,
+                "path": str(path),
+                "start_sha": start_sha,
+            },
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/issue-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+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.
+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.
+
+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).
+
+## 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.
+
+`--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.
+
+## Review
+
+1. Read the issue, linked work, canonical plan, repository guidance, ADRs,
+   relevant code, tests, and public contracts.
+2. Decide architecture first: aligned, intentional and justified change, or an
+   unexplained violation. A material violation blocks a positive assessment.
+3. Map every acceptance criterion 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.
+5. Apply only activated language and change-surface checks, recording N/A
+   sections and reasons. 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.
+
+## 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.

package/skills/learn/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: learn
+license: BSD-3-Clause
+description: Preserve a verified, non-duplicate Mnemosyne lesson as a bounded generalized skill, with prior versions in .history and supporting evidence in .notes.md, through an isolated-worktree pull request when requested; otherwise report without mutation. A usable knowledge checkout is required before discovery or writing; read-only discovery may use its current contents without upstream synchronization, while new-PR delivery requires a fresh synchronized default-branch base.
+argument-hint: <lesson or session summary>
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# Learn
+
+Why: one concise, general rule is more discoverable and safer than many session-specific copies.
+First decide whether a durable delta exists; then partition it into retrievable guidance, history, and
+supporting notes before writing through a reviewable PR.
+
+## Prepare the knowledge repository
+
+Prepare Mnemosyne at `$HOME/.agent_brain/knowledge` under the canonical
+[`dependency-resolution` contract](../../docs/dependency-resolution.md). Report the resolved
+repository, commit SHA, and trust basis. A usable knowledge checkout is required before discovery
+or writing. Normal preparation may create it under the dependency-resolution contract. Any checkout
+or inspection failure blocks `learn`; upstream resolution, authentication, update, and revalidation
+may be deferred during read-only discovery but are required at the delivery boundary.
+
+**Read-only discovery:** require the existing checkout, but do not require upstream resolution,
+fetch, fast-forward, or automatic-fork revalidation. Bind discovery to its current `HEAD`, report
+its repository, revision, origin/trust status, and freshness or verification limitation, and use the
+checked-out content as best effort. If no usable checkout exists or inspection fails, report
+`blocked` and stop; do not substitute another repository or continue into duplicate analysis.
+
+Before creating a new PR, complete the normal dependency-resolution update and revalidation against
+the canonical default branch. Bind the delivery worktree to that exact fresh SHA. Planning and
+read-only discovery may use a stale checkout; PR delivery may not.
+
+## Decide before writing
+
+This phase is read-only.
+
+The steps below require the existing checkout described above. In read-only discovery, do not derive
+a durable write disposition or continue after the required checkout is unavailable.
+
+1. Run `advise` with the proposed lesson, using its planning-mode best-effort behavior for this
+   read-only discovery phase.
+2. Define retrieval intent as the trigger/context, desired outcome, constraints, and failure mode;
+   never use title, issue number, or session wording as identity.
+3. Resolve the installed `advise/scripts/list_retrievable_skills.py` helper and run it by absolute
+   path against the knowledge checkout. Group only its returned main-skill paths by intent; then
+   inspect each selected candidate, its `.history`, its relevant `.notes.md`, and Git history for
+   provenance and prior consolidation. A missing or failed selector is blocking because an ad hoc
+   glob could silently change the retrieval boundary.
+4. Inspect every open PR in the resolved Mnemosyne repository: enumerate its changed flat
+   `skills/*.md` artifacts and derive intent from their changed content. A title or path only finds a
+   candidate; it is never sufficient duplicate evidence.
+5. Record exactly one disposition before mutation:
+
+   | Disposition | Use when | Action |
+   | --- | --- | --- |
+   | `amend` | One canonical entry has a material verified delta. | Update that canonical artifact set only. |
+   | `consolidate` | Two or more current entries share intent. | Select one canonical artifact set, merge non-superseded rules, and retire duplicates in the same PR. |
+   | `create` | Intent is materially distinct. | Add one precisely named artifact set. |
+   | `reject` | No durable, verified delta exists. | Report `no learnable change`; leave Mnemosyne unchanged. |
+   | `blocked` | Provenance is uncertain, more than one open PR targets the selected canonical entry, the selected PR is not safely writable, or retirement is unsafe. | Leave Mnemosyne unchanged and request direction. |
+
+Never evade a blocked consolidation by creating a near-duplicate. When exactly one open PR changes
+the selected canonical entry, it is the delivery target: enter Existing-PR mode and incorporate the
+verified delta there. Never create a competing PR. Stop rather than guessing when multiple open PRs
+target that entry. Do not report `learn` complete after `reject` or `blocked`.
+
+Repository audits belong in `repo-review`; PR audits belong in `pr-review`; review depth is a mode.
+
+## Keep retrieval bounded
+
+Treat each lesson as three different information classes. Do not use the main skill as an append-only
+record.
+
+| Artifact | Contains | Excludes |
+| --- | --- | --- |
+| `skills/<name>.md` | Current generalized triggers, decision rules, workflow, failures, parameters, and zero to three concise examples that materially change a decision | Prior versions, changelog narrative, session chronology, transcripts, and repeated project cases |
+| `skills/<name>.history` | Superseded main-skill versions plus append-only version, change, and provenance records | Active instructions that exist only here |
+| `skills/<name>.notes.md` | Privacy-cleared source detail, long examples, commands, measurements, verification reports, and other supporting evidence worth retaining | Rules required for the skill to work |
+
+For every amendment, rewrite the main entry around the smallest reusable delta instead of appending
+the session. Merge overlapping rules, remove superseded guidance, and retain at most three examples;
+each example must cover a materially different decision branch and be shorter than the rule it
+illustrates. A repository name, issue narrative, transcript, or another instance of an established
+pattern is evidence, not a new main-skill example.
+
+Before replacing a main entry, archive its complete prior retrievable content in `.history` unless
+that version is already present. Append the new version and provenance record there. Put detailed
+evidence that remains useful for the current rule in `.notes.md`. Never move prohibited sensitive
+content merely to preserve it.
+
+Keep only a schema-required current version identifier in main-file frontmatter. Put all prior
+versions, change summaries, provenance, and other version-control narrative in `.history`. Obey the
+resolved repository's main-skill size budget; for Mnemosyne, a new or changed retrievable main file
+must not exceed 30,000 bytes. Notes and history must remain outside normal retrieval.
+
+## Privacy and proprietary-information gate
+
+Treat the session, its repositories, and all discovery output as sensitive source material. A
+durable lesson must capture only the general pattern, decision rule, and safely shareable evidence;
+it must never store any of the following in a main skill, notes, history, filename, frontmatter,
+example, commit, or PR description:
+
+- PII or identifiers that can identify a person, account, customer, or organization;
+- product, project, customer, vendor, or organization names and other non-public identifiers;
+- internal paths, hostnames, URLs, repository names, issue IDs, environment names, or infrastructure
+  details;
+- proprietary source, configuration, prompts, logs, data, metrics, or operational details; or
+- secrets, credentials, tokens, or other access material.
+
+Replace sensitive specifics with a faithful general pattern (for example, "an isolated checkout"
+instead of a local path). When public information provides an equivalent, cite or describe that
+public equivalent rather than copying internal evidence. Never invent a public analogue, a result,
+or verification evidence. If the lesson cannot be made useful without disclosing sensitive or
+proprietary information, select `reject`, leave Mnemosyne unchanged, and report that no safe
+learnable change exists.
+
+If a lesson requires Athena implementation, complete that normal development first. Follow
+[`development.md`](../../docs/policies/development.md): keep helpers in `skills/<name>/scripts/`,
+add behavior-based executable tests under `tests/unit/`, and do not add inline executable Markdown,
+wording tests, or non-consumed artifacts merely to support a lesson.
+
+## Scope
+
+Read-only discovery does not expand the requested scope. When the task requests durable learning,
+the resolved repository and full delivery path are constructive work that may proceed through either
+a new PR or the single Existing-PR target selected during discovery. A recommendation or indirect
+invocation remains read-only; return the proposed repository, base, branch, files, and PR target.
+
+## Existing-PR mode
+
+Use this mode when discovery identifies exactly one open PR that changes the selected canonical
+entry. Re-fetch and bind its canonical repository, URL/number, `OPEN` state, source repository/ref,
+and head OID before editing. Create an isolated worktree on that source ref at the bound head OID,
+verify its `HEAD`, and never modify the shared checkout or default branch.
+
+Immediately before publishing, re-fetch the same identity and head. Push only to the bound PR source
+ref, using the provider's safe expected-head/lease protection. If the ref moves, the source repository
+is not safely writable, or any binding differs, preserve the worktree and stop. Do not create a
+branch, open another PR, or retarget the change. Use the disposition-specific write allowlist below.
+
+## Coordinate safely
+
+When available, partition independent discovery, overlap analysis, drafting, and verification into
+bounded work items; otherwise perform them sequentially without weakening evidence. New-PR writers
+use isolated worktrees from the same resolved default-branch SHA; Existing-PR writers use only the
+bound PR head. Give writers non-overlapping ownership; read-only work items never edit. The
+coordinator owns each canonical entry or assigns one integration owner, rejects unrelated edits, runs
+focused validation after each integration and complete relevant validation after the combined result,
+and alone commits, pushes, and opens a new PR when applicable. Stop on ownership overlap, base drift,
+or unexpected scope.
+
+Without native isolation, use the installed `../git-worktrees/scripts/prepare_worktree.py` by absolute
+path only for new-PR work: retain the resolved checkout as the current directory; use branch
+`skill/<slug>`, `--path $HOME/.agent_brain/worktrees/knowledge-<slug>`,
+`--path-root $HOME/.agent_brain/worktrees`, and `--start-point <resolved-default-SHA>`. Never use
+this fallback to reconstruct an Existing-PR worktree.
+
+## Deliver a requested change
+
+1. Never modify the shared checkout. Before creating a new-PR worktree, complete the deferred
+   dependency-resolution update and bind it to the exact current default-branch SHA. Then derive
+   `slug` and `name` from lowercase ASCII
+   letters, digits, and single hyphens using `[a-z0-9][a-z0-9-]*`; reject empty, control, `/`, `..`,
+   and leading `-` values. Add a collision-resistant suffix when needed. Create `skill/<slug>` at
+   `$HOME/.agent_brain/worktrees/knowledge-<slug>` from the resolved default-branch SHA; resolve the
+   path first, require it directly below `$HOME/.agent_brain/worktrees`, and reject symlinked parents
+   or destinations. This is the new-PR path for `create` and `consolidate`, not Existing-PR mode.
+2. Before editing, resolve a closed, disposition-specific write allowlist of exact repository-relative
+   paths. Include only companions required by the artifact partition:
+
+   | Disposition | Allowed paths |
+   | --- | --- |
+   | `amend` | The canonical `.md`, its `.history`, and its `.notes.md` when supporting detail exists. |
+   | `create` | One new `.md`, its initial `.history`, and `.notes.md` only when supporting detail exists. |
+   | `consolidate` | The canonical three artifacts, each named duplicate to retire, and each verified active consumer that must migrate. |
+
+   Name every companion and retirement explicitly. Do not discover new write paths while editing.
+3. For `create`, read the resolved Mnemosyne template, schema, and validation rules before drafting.
+   Use every required frontmatter field, including `name`, `description`, `category`, `date`, and
+   the current `version`, plus the required section structure. Keep searchable intent, generalized
+   use and workflow, relevant failed approaches, and parameters in the main entry. Create the initial
+   version/provenance record in `.history`; route useful supporting detail to `.notes.md`.
+4. Apply the selected disposition inside its allowlist. For `amend` or `consolidate`, archive each
+   superseded canonical version before rewriting the main entry. Apart from that required historical
+   snapshot, partition rather than copy: current rules, history records, and notes evidence each have
+   one owner. During consolidation, migrate verified active consumers before retiring every named
+   duplicate.
+5. Before committing, review every proposed artifact and delivery text against the privacy and
+   proprietary-information gate. Remove or generalize sensitive specifics; use a faithful public
+   equivalent only when one exists. If safe generalization is not possible, reject the lesson.
+6. Run Mnemosyne's relevant complete validation. Verify exactly one active entry remains for the
+   intent; its main file is within the configured size budget; notes and history are excluded from
+   normal retrieval; and no duplicate intent, embedded version history, or stale consolidated name
+   was introduced.
+7. Sign and DCO-attest the commit. For a new PR, push the feature branch and open a PR against the
+   resolved default branch. For Existing-PR mode, push only to the already bound source ref and do
+   not open another PR. Never auto-merge.
+8. Report the disposition, bound or new PR URL, main-file byte size, archived version, companion
+   files, any retired entries, and exact validation evidence.
+
+A write disposition succeeds only with its PR URL. If validation, push, or PR creation fails, preserve
+the isolated worktree and report the blocker; never fall back to Athena, a default branch, or another
+repository. Preserve delegated and delivery worktrees until their unique work is integrated or
+explicitly rejected. Cleanup is separate: remove only worktrees created by this invocation, only with
+user authority, only after confirming no uncommitted or unintegrated state remains. Otherwise report
+each worktree's path, owner, revision, cleanliness, and integration state and leave it intact. Never
+delete branches, discard changes, force removal, or touch a pre-existing worktree.