@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/backend/fm-doc-audience-check.sh

@@ -0,0 +1,269 @@
+#!/usr/bin/env bash
+# fm-doc-audience-check.sh - validate the tracked documentation audience inventory.
+#
+# Usage:
+#   bin/fm-doc-audience-check.sh
+#   bin/fm-doc-audience-check.sh --root <repo> [--inventory <path>]
+#
+# The inventory owns classification and setup routing.
+# This check validates structure only and does not keyword-lint prose.
+set -eu
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+exec python3 - "$@" <<'PY'
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from collections import Counter
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+MARKDOWN_LINK_RE = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
+HTML_LINK_RE = re.compile(r"\b(?:href|src)=[\"']([^\"']+)[\"']", re.IGNORECASE)
+REQUIRED_TRACKED_PATTERNS = ["*.md", "*.mdx", "*.rst", "*.txt", "docs/examples/*"]
+
+
+class CheckError(Exception):
+    """One deterministic audience-check failure."""
+
+
+def fail(message: str) -> None:
+    raise CheckError(message)
+
+
+def git_tracked(root: Path, patterns: list[str]) -> list[str]:
+    proc = subprocess.run(
+        ["git", "-C", str(root), "ls-files", "-z", "--", *patterns],
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    if proc.returncode != 0:
+        detail = proc.stderr.decode("utf-8", "replace").strip()
+        fail(f"git ls-files failed: {detail or 'unknown error'}")
+    return sorted(p for p in proc.stdout.decode("utf-8").split("\0") if p)
+
+
+def load_inventory(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        fail(f"inventory is missing: {path}")
+    except (OSError, json.JSONDecodeError) as exc:
+        fail(f"inventory is unreadable: {exc}")
+    if not isinstance(data, dict):
+        fail("inventory root must be an object")
+    if data.get("version") != 1:
+        fail("inventory version must be 1")
+    return data
+
+
+def list_of_strings(value: object, label: str) -> list[str]:
+    if not isinstance(value, list) or not value or not all(isinstance(v, str) and v for v in value):
+        fail(f"{label} must be a non-empty string array")
+    return value
+
+
+def normalized_link_value(raw: str) -> str:
+    value = raw.strip()
+    if value.startswith("<") and value.endswith(">"):
+        value = value[1:-1].strip()
+    if " " in value:
+        value = value.split()[0]
+    return value
+
+
+def resolve_local_target(root: Path, source: Path, raw: str) -> Path | None:
+    split = urlsplit(normalized_link_value(raw))
+    if split.scheme or split.netloc:
+        return None
+    if not split.path:
+        return source.resolve(strict=False) if split.fragment else None
+    decoded = unquote(split.path)
+    if decoded.startswith("/"):
+        fail(f"absolute local link in {source.relative_to(root)}: {raw}")
+    target = (source.parent / decoded).resolve(strict=False)
+    try:
+        target.relative_to(root.resolve())
+    except ValueError:
+        fail(f"local link escapes repository in {source.relative_to(root)}: {raw}")
+    return target
+
+
+def markdown_local_links(root: Path, source: Path) -> list[tuple[str, Path]]:
+    try:
+        text = source.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        fail(f"cannot read prose surface {source.relative_to(root)}: {exc}")
+    raw_links = MARKDOWN_LINK_RE.findall(text) + HTML_LINK_RE.findall(text)
+    result: list[tuple[str, Path]] = []
+    for raw in raw_links:
+        target = resolve_local_target(root, source, raw)
+        if target is not None:
+            result.append((raw, target))
+    return result
+
+
+def github_heading_slug(value: str) -> str:
+    value = re.sub(r"<[^>]+>", "", value)
+    value = value.replace("`", "").strip().lower()
+    value = re.sub(r"[^\w\- ]", "", value, flags=re.UNICODE)
+    return re.sub(r"\s", "-", value)
+
+
+def markdown_anchors(path: Path) -> set[str]:
+    anchors: set[str] = set()
+    counts: Counter[str] = Counter()
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError) as exc:
+        fail(f"cannot read link target {path}: {exc}")
+    for line in lines:
+        match = re.match(r"^#{1,6}\s+(.+?)\s*#*\s*$", line)
+        if match:
+            base = github_heading_slug(match.group(1))
+            if base:
+                count = counts[base]
+                anchors.add(base if count == 0 else f"{base}-{count}")
+                counts[base] += 1
+        for explicit in re.findall(r"<(?:a|span)\s+(?:name|id)=[\"']([^\"']+)[\"']", line, re.IGNORECASE):
+            anchors.add(explicit)
+    return anchors
+
+
+def validate(root: Path, inventory_path: Path) -> tuple[int, int]:
+    data = load_inventory(inventory_path)
+    scope = data.get("scope")
+    if not isinstance(scope, dict):
+        fail("scope must be an object")
+    patterns = list_of_strings(scope.get("trackedPatterns"), "scope.trackedPatterns")
+    if patterns != REQUIRED_TRACKED_PATTERNS:
+        fail("scope.trackedPatterns must match the fixed maintained-prose scope")
+    audiences = set(list_of_strings(data.get("allowedAudiences"), "allowedAudiences"))
+    setup_audiences = set(list_of_strings(data.get("setupAudiences"), "setupAudiences"))
+    if not setup_audiences <= audiences:
+        fail("setupAudiences contains an audience outside allowedAudiences")
+
+    surfaces = data.get("surfaces")
+    if not isinstance(surfaces, list):
+        fail("surfaces must be an array")
+    paths: list[str] = []
+    classifications: dict[str, str] = {}
+    for index, entry in enumerate(surfaces):
+        if not isinstance(entry, dict):
+            fail(f"surfaces[{index}] must be an object")
+        path = entry.get("path")
+        audience = entry.get("audience")
+        if not isinstance(path, str) or not path:
+            fail(f"surfaces[{index}].path must be a non-empty string")
+        if audience not in audiences:
+            fail(f"{path}: unsupported audience {audience!r}")
+        paths.append(path)
+        classifications[path] = audience
+
+    duplicates = sorted(path for path, count in Counter(paths).items() if count != 1)
+    if duplicates:
+        fail("surfaces classified more than once: " + ", ".join(duplicates))
+
+    tracked = set(git_tracked(root, patterns))
+    classified = set(paths)
+    missing = sorted(tracked - classified)
+    extra = sorted(classified - tracked)
+    if missing or extra:
+        details = []
+        if missing:
+            details.append("unclassified: " + ", ".join(missing))
+        if extra:
+            details.append("not tracked/in scope: " + ", ".join(extra))
+        fail("; ".join(details))
+
+    readme_path = root / "README.md"
+    readme_targets = {
+        os.path.relpath(target, root).replace(os.sep, "/")
+        for _, target in markdown_local_links(root, readme_path)
+    }
+    setup_targets = list_of_strings(data.get("readmeSetupTargets"), "readmeSetupTargets")
+    for target in setup_targets:
+        if target not in readme_targets:
+            fail(f"README setup target is not linked from README.md: {target}")
+        if classifications.get(target) not in setup_audiences:
+            fail(
+                f"README setup target {target} has disallowed audience "
+                f"{classifications.get(target)!r}"
+            )
+
+    pointers = data.get("requiredOwnerPointers")
+    if not isinstance(pointers, list) or not pointers:
+        fail("requiredOwnerPointers must be a non-empty array")
+    for index, pointer in enumerate(pointers):
+        if not isinstance(pointer, dict):
+            fail(f"requiredOwnerPointers[{index}] must be an object")
+        source = pointer.get("source")
+        target = pointer.get("target")
+        if not isinstance(source, str) or not isinstance(target, str) or not source or not target:
+            fail(f"requiredOwnerPointers[{index}] needs non-empty source and target")
+        source_path = root / source
+        target_path = root / target
+        if not source_path.exists():
+            fail(f"owner-pointer source is missing: {source}")
+        if not target_path.exists():
+            fail(f"owner-pointer target is missing: {target}")
+        try:
+            source_text = source_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            fail(f"owner-pointer source is unreadable {source}: {exc}")
+        linked_targets: set[str] = set()
+        if source_path.suffix.lower() in {".md", ".mdx"}:
+            linked_targets = {
+                os.path.relpath(linked, root).replace(os.sep, "/")
+                for _, linked in markdown_local_links(root, source_path)
+            }
+        if target not in source_text and target not in linked_targets:
+            fail(f"required owner pointer missing: {source} -> {target}")
+
+    checked_links = 0
+    anchor_cache: dict[Path, set[str]] = {}
+    for path in sorted(tracked):
+        if Path(path).suffix.lower() not in {".md", ".mdx"}:
+            continue
+        source = root / path
+        for raw, target in markdown_local_links(root, source):
+            checked_links += 1
+            if not target.exists():
+                fail(f"unresolved local link in {path}: {raw}")
+            fragment = unquote(urlsplit(normalized_link_value(raw)).fragment)
+            if fragment and target.is_file() and target.suffix.lower() in {".md", ".mdx"}:
+                anchors = anchor_cache.setdefault(target, markdown_anchors(target))
+                if fragment not in anchors:
+                    fail(f"unresolved local anchor in {path}: {raw}")
+
+    return len(tracked), checked_links
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate Firstmate documentation audiences and local links.")
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--inventory", type=Path)
+    args = parser.parse_args()
+    root = args.root.resolve()
+    inventory_path = args.inventory or (root / "docs/documentation-audiences.json")
+    if not inventory_path.is_absolute():
+        inventory_path = root / inventory_path
+    try:
+        surfaces, links = validate(root, inventory_path)
+    except CheckError as exc:
+        print(f"fm-doc-audience-check: {exc}", file=sys.stderr)
+        return 1
+    print(f"fm-doc-audience-check: ok surfaces={surfaces} local_links={links}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+PY

package/.agents/backend/fm-dod-lib.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Single owner of a ship task's mode-specific "Definition of done" block.
+# Sourced by bin/fm-brief.sh, which renders it into a generated ship brief, and by
+# bin/fm-promote.sh, which renders it into the ship instructions a promoted scout
+# receives. Both paths must hand the worker the same contract: a promoted
+# no-mistakes worker that never received the ask-user escalation rule or the
+# `--yes` ban is the exact delivery hole this single owner exists to close.
+# fm_dod_block <no-mistakes|direct-PR|local-only> <task-id> prints the block on
+# stdout with no trailing blank line. The caller validates the mode; an unknown
+# mode is refused rather than silently rendered as the pipeline contract.
+# The block opens with the fixed machine-readable "Delivery contract: mode=<mode>"
+# line that bin/fm-spawn.sh checks a ship brief against.
+# Every heredoc here stays outside a command substitution: `VAR=$(cat <<EOF ...)`
+# breaks parsing of the whole file on Bash 3.2 (tests/fm-brief.test.sh).
+
+fm_dod_block() {  # <mode> <task-id>
+  local mode=$1 id=$2
+  case "$mode" in
+    direct-PR)
+      cat <<EOF
+# Definition of done
+Delivery contract: mode=direct-PR
+This task ships **direct-PR**: you raise the PR yourself, without the no-mistakes pipeline.
+The task is complete only when committed on your branch.
+When it is implemented and committed, push your branch and open a PR with \`gh-axi\`, then append \`done: PR {url}\` to the status file and stop.
+Do NOT run /no-mistakes. The configured merge authority decides whether to merge the PR; firstmate relays the outcome.
+EOF
+      ;;
+    local-only)
+      cat <<EOF
+# Definition of done
+Delivery contract: mode=local-only
+This task ships **local-only**: no remote, no PR, no pipeline.
+The task is complete only when committed on your branch \`fm/$id\`. Do NOT push, do NOT open a PR, do NOT merge.
+Keep your branch a clean fast-forward onto the current default branch - if \`main\` has advanced, rebase onto it so the eventual merge stays a fast-forward.
+When it is implemented and committed, append \`done: ready in branch fm/$id\` to the status file and stop.
+The configured merge authority approves the ready branch, then firstmate merges it into local \`main\` through the guarded fast-forward path.
+EOF
+      ;;
+    no-mistakes)
+      cat <<EOF
+# Definition of done
+Delivery contract: mode=no-mistakes
+The task is complete only when committed on your branch.
+When you believe it is complete, append \`done: {summary}\` to the status file and stop.
+Firstmate will then instruct you to run /no-mistakes to validate and ship a PR.
+
+You drive no-mistakes by responding to its gates, not by implementing fixes.
+Follow the guidance no-mistakes itself provides for the mechanics: it loads when you invoke /no-mistakes, and \`no-mistakes axi run --help\` plus the \`help\` lines in each \`axi\` response are authoritative and version-matched to the installed binary.
+When starting no-mistakes, make \`--intent\` preserve all relevant content from this brief's \`# Task\` section plus every later accepted Firstmate requirement, clarification, constraint, exclusion, and supersession, carrying only each requirement's current accepted form; retain direct requirements instead of substituting a diff summary, and exclude generic operational, status, delivery, and other scaffold boilerplate unless it is task-specific.
+Do not hand-edit, commit, or fix findings yourself while a run is active - the pipeline applies every fix.
+
+Two firstmate-specific rules layer on top of that guidance:
+- ask-user findings are never yours to answer: escalate to firstmate (rule 6) and stop.
+  Firstmate applies \`ask-user-authority\` and obtains any required captain decision.
+  When the decision comes back, feed it to the gate with \`no-mistakes axi respond\` and let the pipeline apply it - do not route the question to "the user" or implement the fix yourself.
+- NEVER pass \`--yes\` (or \`-y\`) to \`no-mistakes axi run\` or \`no-mistakes axi respond\`. It is banned fleet-wide.
+  It auto-resolves every gate including ask-user findings with no escalation, and answering your own ask-user finding is a hard rule violation.
+
+After /no-mistakes reports CI green (the CI-ready return point - do not wait for it to keep monitoring in the background until merge), append \`done: PR {url} checks green\` and stop. You are finished.
+EOF
+      ;;
+    *)
+      echo "error: fm_dod_block: unknown delivery mode '$mode'" >&2
+      return 1 ;;
+  esac
+}

package/.agents/backend/fm-ensure-agents-md.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# Ensure a project worktree follows the agent-memory file convention.
+# AGENTS.md is the real project-intrinsic knowledge file; CLAUDE.md is a
+# real regular file whose canonical content is the two-line @AGENTS.md pointer
+# that Claude Code inlines at load time. Creates a minimal AGENTS.md skeleton
+# when neither file exists, promotes a real CLAUDE.md file when it is the only
+# file present (unless it is already the canonical pointer), converts a correct
+# CLAUDE.md -> AGENTS.md symlink into the pointer file, and refuses to clobber
+# distinct real files or wrong symlinks.
+# Owns the canonical "## Maintaining this file" self-governance wording for
+# project AGENTS.md files, injecting it idempotently into created skeletons,
+# promoted CLAUDE.md files, and any existing AGENTS.md that still lacks it.
+# Owns the canonical CLAUDE.md pointer content (the exact two-line @AGENTS.md
+# form). A real-file pointer cannot follow a write into AGENTS.md, which is why
+# the installer never creates a CLAUDE.md symlink.
+# Refuses a case-variant real memory file such as a lowercase agents.md, so the
+# pointer's @AGENTS.md import resolves to a real AGENTS.md on a case-sensitive
+# filesystem (issue #389). The real-file pointer also eliminates the old
+# uppercase-literal-target dangling-symlink hazard that a CLAUDE.md -> AGENTS.md
+# link would have carried for that same mismatch.
+# This is a worktree utility for crewmates, not a supervision script, so it does
+# not call fm-guard.sh.
+# Usage: fm-ensure-agents-md.sh [repo-or-worktree-dir]
+set -eu
+
+usage() {
+  echo "usage: fm-ensure-agents-md.sh [repo-or-worktree-dir]" >&2
+}
+
+case "${1:-}" in
+  -h|--help)
+    usage
+    exit 0
+    ;;
+esac
+[ "$#" -le 1 ] || { usage; exit 1; }
+
+DIR=${1:-.}
+[ -d "$DIR" ] || { echo "error: not a directory: $DIR" >&2; exit 1; }
+DIR=$(cd "$DIR" && pwd -P)
+cd "$DIR"
+
+AGENTS=AGENTS.md
+CLAUDE=CLAUDE.md
+
+write_maintenance_section() {
+  cat <<'EOF'
+## Maintaining this file
+
+Keep this file for knowledge useful to almost every future agent session in this project.
+Do not repeat what the codebase already shows; point to the authoritative file or command instead.
+Prefer rewriting or pruning existing entries over appending new ones.
+When updating this file, preserve this bar for all agents and keep entries concise.
+EOF
+}
+
+write_maintenance_section_with_eol() {
+  local eol=$1 line
+  while IFS= read -r line; do
+    printf '%s%s' "$line" "$eol"
+  done < <(write_maintenance_section)
+}
+
+# Idempotently append the canonical self-governance section to AGENTS.md when it
+# is absent. Sets MAINT_INJECTED=1 when it appends and 0 when the section is
+# already present, so callers can report whether the file changed.
+MAINT_INJECTED=0
+ensure_maintenance_section() {
+  MAINT_INJECTED=0
+  if grep -Fqx '## Maintaining this file' "$AGENTS" ||
+    grep -Fqx $'## Maintaining this file\r' "$AGENTS"; then
+    return 0
+  fi
+  local eol=$'\n' sep=''
+  if LC_ALL=C grep -q $'\r$' "$AGENTS"; then
+    eol=$'\r\n'
+  fi
+  if [ -s "$AGENTS" ]; then
+    if [ -n "$(tail -c 1 "$AGENTS")" ]; then
+      sep="${eol}${eol}"
+    else
+      sep=$eol
+    fi
+  fi
+  {
+    printf '%s' "$sep"
+    write_maintenance_section_with_eol "$eol"
+  } >> "$AGENTS"
+  MAINT_INJECTED=1
+}
+
+write_skeleton() {
+  cat > "$AGENTS" <<'EOF'
+# Project agent memory
+
+This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.
+
+- Add durable project-specific notes here as they are discovered through real work.
+EOF
+  ensure_maintenance_section
+}
+
+# Canonical CLAUDE.md pointer: a real file, never a symlink. Byte-identical
+# two-line form so a stray write clobbers only this recoverable pointer.
+claude_pointer_content() {
+  cat <<'EOF'
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
+@AGENTS.md
+EOF
+}
+
+is_canonical_claude_pointer() {
+  [ -f "$CLAUDE" ] && [ ! -L "$CLAUDE" ] || return 1
+  claude_pointer_content | cmp -s - "$CLAUDE"
+}
+
+# Write the canonical pointer as a regular file. Unlink a symlink first so the
+# write cannot follow it and destroy AGENTS.md. Never overwrite a distinct real
+# file; callers classify that as a conflict before invoking this.
+install_claude_pointer() {
+  if is_canonical_claude_pointer; then
+    return 0
+  fi
+  if [ -L "$CLAUDE" ]; then
+    rm -- "$CLAUDE"
+  elif [ -e "$CLAUDE" ]; then
+    echo "error: internal: refuse to overwrite existing CLAUDE.md" >&2
+    exit 1
+  fi
+  claude_pointer_content > "$CLAUDE"
+}
+
+is_correct_claude_symlink() {
+  [ -L "$CLAUDE" ] || return 1
+  target=$(readlink "$CLAUDE")
+  case "$target" in
+    "$AGENTS"|"./$AGENTS") return 0 ;;
+  esac
+  [ -e "$AGENTS" ] || return 1
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$CLAUDE" "$AGENTS" <<'PY'
+import os
+import sys
+sys.exit(0 if os.path.realpath(sys.argv[1]) == os.path.realpath(sys.argv[2]) else 1)
+PY
+    return $?
+  fi
+  return 1
+}
+
+# Refuse a case-variant real memory file (issue #389). On a case-insensitive
+# filesystem an existing lowercase agents.md satisfies every [ -e AGENTS.md ]
+# test below, so the script would emit a CLAUDE.md pointer whose @AGENTS.md
+# import dangles once the tree is checked out on a case-sensitive filesystem.
+# Reading the real directory entries catches the mismatch on both filesystem
+# kinds; surface it for manual reconciliation instead of writing the pointer
+# against the wrong name.
+for entry in *; do
+  if [ ! -e "$entry" ] && [ ! -L "$entry" ]; then
+    continue
+  fi
+  if [ "$entry" != "$AGENTS" ]; then
+    case "$entry" in
+      [Aa][Gg][Ee][Nn][Tt][Ss].[Mm][Dd])
+        echo "conflict: memory file is named $entry in $DIR but the convention is AGENTS.md; rename it to AGENTS.md so CLAUDE.md's @AGENTS.md pointer resolves portably" >&2
+        exit 1
+        ;;
+    esac
+  fi
+done
+
+if [ -L "$AGENTS" ]; then
+  echo "conflict: AGENTS.md is a symlink in $DIR; expected AGENTS.md to be the real file" >&2
+  exit 1
+fi
+if [ -e "$AGENTS" ] && [ ! -f "$AGENTS" ]; then
+  echo "conflict: AGENTS.md exists in $DIR but is not a regular file" >&2
+  exit 1
+fi
+
+if [ -e "$AGENTS" ]; then
+  if [ -L "$CLAUDE" ]; then
+    if is_correct_claude_symlink; then
+      ensure_maintenance_section
+      install_claude_pointer
+      if [ "$MAINT_INJECTED" -eq 1 ]; then
+        echo "updated: added ## Maintaining this file to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
+      else
+        echo "updated: replaced CLAUDE.md symlink with @AGENTS.md pointer in $DIR"
+      fi
+      exit 0
+    fi
+    echo "conflict: CLAUDE.md is a symlink in $DIR but does not point to AGENTS.md" >&2
+    exit 1
+  fi
+  if [ ! -e "$CLAUDE" ]; then
+    ensure_maintenance_section
+    install_claude_pointer
+    if [ "$MAINT_INJECTED" -eq 1 ]; then
+      echo "updated: added ## Maintaining this file to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
+    else
+      echo "wrote: CLAUDE.md @AGENTS.md pointer in $DIR"
+    fi
+    exit 0
+  fi
+  if [ -f "$CLAUDE" ]; then
+    if is_canonical_claude_pointer; then
+      ensure_maintenance_section
+      if [ "$MAINT_INJECTED" -eq 1 ]; then
+        echo "updated: added ## Maintaining this file to AGENTS.md in $DIR"
+      else
+        echo "unchanged: AGENTS.md with CLAUDE.md @AGENTS.md pointer in $DIR"
+      fi
+      exit 0
+    fi
+    echo "conflict: both AGENTS.md and CLAUDE.md are real files in $DIR; reconcile them manually" >&2
+    exit 1
+  fi
+  echo "conflict: CLAUDE.md exists in $DIR but is not a regular file or symlink" >&2
+  exit 1
+fi
+
+if [ -L "$CLAUDE" ]; then
+  if is_correct_claude_symlink; then
+    write_skeleton
+    install_claude_pointer
+    echo "created: AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
+    exit 0
+  fi
+  echo "conflict: CLAUDE.md is a symlink in $DIR but AGENTS.md is missing and the link does not point to AGENTS.md" >&2
+  exit 1
+fi
+
+if [ -e "$CLAUDE" ]; then
+  if [ -f "$CLAUDE" ]; then
+    if is_canonical_claude_pointer; then
+      write_skeleton
+      echo "created: AGENTS.md and kept CLAUDE.md @AGENTS.md pointer in $DIR"
+      exit 0
+    fi
+    mv "$CLAUDE" "$AGENTS"
+    ensure_maintenance_section
+    install_claude_pointer
+    echo "promoted: moved CLAUDE.md to AGENTS.md and wrote CLAUDE.md @AGENTS.md pointer in $DIR"
+    exit 0
+  fi
+  echo "conflict: CLAUDE.md exists in $DIR but is not a regular file or symlink" >&2
+  exit 1
+fi
+
+write_skeleton
+install_claude_pointer
+echo "created: AGENTS.md and CLAUDE.md @AGENTS.md pointer in $DIR"