@1aboveio/skills 1.0.14 → 1.0.16

package/skills/app-dev/android-development/scripts/failure_capture.py

@@ -0,0 +1,331 @@
+"""Record the evidence of a failed Android device case.
+
+Journey code wraps the steps it drives:
+
+    from failure_capture import FailureRecorder
+
+    recorder = FailureRecorder(case="checkout smoke", evidence_dir=os.environ["LOG_DIR"])
+
+    with recorder.step("tap Pay"):
+        tap(...)
+        wait_for("Thank you")
+
+The first step exception captures the screen, the UI hierarchy and a bounded logcat
+tail into the evidence directory, writes ``failure.json``, prints exactly one
+``NATIVE_FAILURE {...}`` line and lets the original exception propagate unchanged.
+``recorder.step`` is a context manager and a decorator, so a plain callable step can
+be wrapped the same way.
+
+Record shape, shared with the ``device-run.sh`` fallback and with the framework
+adapters described in ``references/diagnosis.md``:
+
+    case, step, error, screenshot, uiDump, logcatTail, evidenceDir, cleanupErrors
+
+``screenshot``, ``uiDump`` and ``logcatTail`` are file names relative to
+``evidenceDir`` and are ``null`` when that capture failed; the reason goes to
+``cleanupErrors`` and never replaces the original ``error``. A record is written
+once: the first failure is kept, and a later failure or a cleanup problem never
+overwrites it.
+
+Other languages implement the same contract. A repo that already uses Maestro or
+Detox maps that framework's failing-step artifacts to this record instead of adding
+this helper.
+
+If the evidence directory cannot be written, the reason goes to stderr and the
+``NATIVE_FAILURE`` line is still printed with its path; the original exception
+always propagates unchanged.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+
+RECORD_NAME = "failure.json"
+NATIVE_FAILURE_PREFIX = "NATIVE_FAILURE "
+SCREENSHOT_NAME = "screenshot.png"
+UI_DUMP_NAME = "ui-dump.xml"
+LOGCAT_NAME = "logcat-tail.txt"
+UI_DUMP_REMOTE = "/sdcard/failure-capture.xml"
+
+RECORD_KEYS = (
+    "case",
+    "step",
+    "error",
+    "screenshot",
+    "uiDump",
+    "logcatTail",
+    "evidenceDir",
+    "cleanupErrors",
+)
+NATIVE_FAILURE_KEYS = ("case", "step", "error", "evidenceDir")
+
+
+class CaptureError(RuntimeError):
+    """A bounded capture command failed, timed out or returned no usable output."""
+
+
+def describe_error(error: BaseException) -> str:
+    """A one-value error summary; JSON encoding keeps the line single-line."""
+    return "%s: %s" % (type(error).__name__, error)
+
+
+def _write_bytes(path: str, payload: bytes) -> None:
+    """Replace `path` atomically so a partial capture is never read as evidence."""
+    directory = os.path.dirname(path) or "."
+    handle, temporary = tempfile.mkstemp(dir=directory, prefix=".capture-", suffix=".part")
+    try:
+        with os.fdopen(handle, "wb") as stream:
+            stream.write(payload)
+        os.replace(temporary, path)
+    except BaseException:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+        raise
+
+
+def _text(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace").strip()
+    return str(value).strip()
+
+
+class AdbClient:
+    """Bounded adb captures for one device.
+
+    `serial` selects the device with `-s`, so the caller's private ADB endpoint and
+    device mapping stay authoritative. `adb` is the injectable runner: it receives
+    the full argv and the per-command timeout and must return an object with
+    `returncode`, `stdout` and `stderr` (like `subprocess.CompletedProcess`). Tests
+    pass a fake here; production uses `subprocess.run`.
+    """
+
+    def __init__(self, serial=None, adb=None, executable="adb"):
+        self.serial = serial
+        self.executable = executable
+        self._adb = adb if adb is not None else self._run_subprocess
+
+    @staticmethod
+    def _run_subprocess(command, timeout):
+        return subprocess.run(command, capture_output=True, timeout=timeout, check=False)
+
+    def command(self, *args):
+        serial_args = ("-s", str(self.serial)) if self.serial else ()
+        return [self.executable, *serial_args, *args]
+
+    def _call(self, *args, timeout):
+        label = "adb %s" % " ".join(str(arg) for arg in args)
+        try:
+            result = self._adb(self.command(*args), timeout)
+        except subprocess.TimeoutExpired as error:
+            raise CaptureError("%s timed out after %ss" % (label, timeout)) from error
+        except OSError as error:
+            raise CaptureError("%s could not run: %s" % (label, error)) from error
+        status = getattr(result, "returncode", 0)
+        if status != 0:
+            detail = _text(getattr(result, "stderr", None))
+            raise CaptureError("%s exited %s%s" % (label, status, ": " + detail if detail else ""))
+        return getattr(result, "stdout", b"") or b""
+
+    def screencap(self, destination, timeout):
+        payload = self._call("exec-out", "screencap", "-p", timeout=timeout)
+        if not payload:
+            raise CaptureError("adb exec-out screencap -p returned no image")
+        _write_bytes(destination, payload)
+
+    def ui_dump(self, destination, timeout):
+        self._call("shell", "uiautomator", "dump", UI_DUMP_REMOTE, timeout=timeout)
+        payload = self._call("exec-out", "cat", UI_DUMP_REMOTE, timeout=timeout)
+        if b"<hierarchy" not in payload:
+            raise CaptureError("uiautomator dump returned no hierarchy")
+        _write_bytes(destination, payload)
+
+    def logcat_tail(self, destination, lines, timeout):
+        payload = self._call("logcat", "-d", "-t", str(lines), timeout=timeout)
+        _write_bytes(destination, payload)
+
+
+@dataclass
+class Failure:
+    """One failed device case; also the payload of `failure.json`."""
+
+    case: str = None
+    step: str = None
+    error: str = ""
+    screenshot: str = None
+    uiDump: str = None
+    logcatTail: str = None
+    evidenceDir: str = None
+    cleanupErrors: list = field(default_factory=list)
+
+    def as_dict(self):
+        return {key: getattr(self, key) for key in RECORD_KEYS}
+
+    def native_failure_line(self):
+        compact = {key: getattr(self, key) for key in NATIVE_FAILURE_KEYS}
+        return NATIVE_FAILURE_PREFIX + json.dumps(compact, separators=(",", ":"))
+
+    @classmethod
+    def from_dict(cls, payload):
+        values = {key: payload[key] for key in RECORD_KEYS if key in payload}
+        errors = values.get("cleanupErrors")
+        values["cleanupErrors"] = list(errors) if isinstance(errors, list) else []
+        return cls(**values)
+
+
+def read_record(evidence_dir):
+    """The record already in `evidence_dir`, or None when there is no usable one."""
+    path = os.path.join(evidence_dir, RECORD_NAME)
+    try:
+        with open(path, "r", encoding="utf-8") as stream:
+            payload = json.load(stream)
+    except (OSError, ValueError):
+        return None
+    if not isinstance(payload, dict) or "error" not in payload:
+        return None
+    return Failure.from_dict(payload)
+
+
+def write_record(failure, evidence_dir):
+    """Store `failure` unless a record already exists; return the record on disk.
+
+    A valid earlier record wins, so a cleanup error or a second failing step cannot
+    replace the first failure. An unreadable file is not a record and is replaced,
+    with the replacement noted on the returned record's `cleanupErrors`.
+    """
+    os.makedirs(evidence_dir, exist_ok=True)
+    existing = read_record(evidence_dir)
+    if existing is not None:
+        return existing
+    path = os.path.join(evidence_dir, RECORD_NAME)
+    if os.path.exists(path):
+        failure.cleanupErrors.append("%s: replaced an unreadable record" % RECORD_NAME)
+    payload = json.dumps(failure.as_dict(), indent=2) + "\n"
+    handle, temporary = tempfile.mkstemp(dir=evidence_dir, prefix=".failure-", suffix=".json")
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            stream.write(payload)
+        os.replace(temporary, path)
+    except BaseException:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+        raise
+    return failure
+
+
+class FailureRecorder:
+    """Capture the first failing step of one device case.
+
+    `case` names the case; it defaults to `DEVICE_CASE`. `evidence_dir` defaults to
+    `LOG_DIR` so the record sits where the launcher and the harness already look.
+    Capture commands are bounded by `capture_timeout` each; a capture problem is
+    recorded on `cleanupErrors` and never replaces the original error.
+    """
+
+    def __init__(
+        self,
+        case=None,
+        evidence_dir=None,
+        *,
+        client=None,
+        serial=None,
+        adb=None,
+        logcat_lines=400,
+        capture_timeout=20.0,
+        stream=None,
+    ):
+        self.case = case if case is not None else os.environ.get("DEVICE_CASE")
+        self.evidence_dir = os.path.abspath(
+            evidence_dir or os.environ.get("LOG_DIR") or os.path.join(".cache", "logs")
+        )
+        self.client = client if client is not None else AdbClient(serial=serial, adb=adb)
+        self.logcat_lines = logcat_lines
+        self.capture_timeout = capture_timeout
+        self.stream = stream if stream is not None else sys.stdout
+        self.failure = None
+        self._recorded = False
+
+    def step(self, name):
+        return _Step(self, name)
+
+    def _captures(self):
+        timeout = self.capture_timeout
+        return (
+            ("screenshot", SCREENSHOT_NAME, lambda path: self.client.screencap(path, timeout)),
+            ("uiDump", UI_DUMP_NAME, lambda path: self.client.ui_dump(path, timeout)),
+            (
+                "logcatTail",
+                LOGCAT_NAME,
+                lambda path: self.client.logcat_tail(path, self.logcat_lines, timeout),
+            ),
+        )
+
+    def record(self, step, error):
+        """Capture evidence for `error` at `step`, once per recorder, then keep going."""
+        if self._recorded:
+            return self.failure
+        self._recorded = True
+        try:
+            directory_problem = None
+            os.makedirs(self.evidence_dir, exist_ok=True)
+        except OSError as problem:
+            directory_problem = problem
+        # An earlier record owns this directory: its evidence files are not replaced
+        # either, so the first failure stays readable.
+        kept = read_record(self.evidence_dir)
+        if kept is not None:
+            self.failure = kept
+            print(kept.native_failure_line(), file=self.stream, flush=True)
+            return kept
+        failure = Failure(
+            case=self.case,
+            step=step,
+            error=error,
+            evidenceDir=self.evidence_dir,
+        )
+        if directory_problem is not None:
+            failure.cleanupErrors.append("evidence dir %s: %s" % (self.evidence_dir, directory_problem))
+        for attribute, name, capture in self._captures():
+            try:
+                capture(os.path.join(self.evidence_dir, name))
+            except (CaptureError, OSError) as problem:
+                failure.cleanupErrors.append("%s: %s" % (attribute, problem))
+            else:
+                setattr(failure, attribute, name)
+        try:
+            failure = write_record(failure, self.evidence_dir)
+        except OSError as problem:
+            print(
+                "failure record not written: %s" % problem,
+                file=sys.stderr,
+            )
+        self.failure = failure
+        print(failure.native_failure_line(), file=self.stream, flush=True)
+        return failure
+
+
+class _Step(contextlib.ContextDecorator):
+    """A named journey step: capture on the first exception, then re-raise."""
+
+    def __init__(self, recorder, name):
+        self.recorder = recorder
+        self.name = name
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, error_type, error, traceback):
+        if error is None or error_type is None:
+            return False
+        # An interrupted or exited run is a cancellation, not a failed case.
+        if issubclass(error_type, (KeyboardInterrupt, SystemExit)):
+            return False
+        self.recorder.record(self.name, describe_error(error))
+        return False

package/skills/app-dev/android-development/scripts/init.mjs

@@ -1,4 +1,5 @@
 // Explicit Android project setup. Preview by default; adds only missing guidance.
+import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
@@ -7,15 +8,37 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const sectionTitle = 'Android development'
 const sectionId = 'android'
-const usage = 'node init.mjs [--repo-root <dir>] [--write]'
+const taskEntryTitle = 'Android task entry'
+const taskEntryBody = `## ${taskEntryTitle}
+
+For Android implementation, runtime debugging, native builds, or device validation,
+read and apply the installed \`android-development\` skill before choosing
+Android-specific commands. In issue workflows, load it during unit preflight.
+Delegated Android workers must load it too. After compaction, reload it if its
+instructions are no longer in context.`
+const usage = 'node init.mjs [--repo-root <dir>] [--install-scripts [<dir>]] [--write]'
+// The generic layer ships in the skill and is referenced from there by default.
+const defaultScriptsDir = 'scripts/android'
+const installableScripts = [
+  { name: 'device-run.sh', mode: 0o755 },
+  { name: 'failure_capture.py', mode: 0o644 },
+]
+const scriptHeaderPattern = /^# android-development skill (\S+) sha256:([0-9a-f]{64}) (\S+)$/
 
 function parseArgs(argv) {
-  const options = { write: false }
+  const options = { write: false, scripts: null }
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
     if (arg === '--write') options.write = true
     else if (arg === '--help') options.help = true
-    else if (arg === '--repo-root') {
+    else if (arg === '--install-scripts') {
+      // The optional target directory never starts with `--`; the flag alone copies
+      // the generic layer to its default location.
+      const value = argv[i + 1]
+      const explicit = value !== undefined && !value.startsWith('--')
+      options.scripts = explicit ? value : ''
+      if (explicit) i++
+    } else if (arg === '--repo-root') {
       const value = argv[++i]
       if (!value || value.startsWith('--') || /[\r\n]/.test(value)) throw new Error(`missing or invalid value for ${arg}`)
       options.repoRoot = path.resolve(value)
@@ -174,7 +197,7 @@ function stripHtmlComments(line, depth = 0) {
 
 // Markdown-aware view: inactive lines are fenced code, indented code or HTML comments.
 // Inline code and HTML comments are blanked from active text so examples never count.
-function markdownView(current) {
+function scanMarkdown(current) {
   const lines = []
   let fence = null
   let commentDepth = 0
@@ -217,10 +240,63 @@ function markdownView(current) {
     previousBlank = blank
     lines.push({ raw: line, text: active ? text : '', active, comments })
   }
-  return lines
+  // An open fence or comment at the end of the file would swallow anything appended after it.
+  return { lines, fence, commentDepth }
+}
+
+function markdownView(current) {
+  return scanMarkdown(current).lines
+}
+
+// End of the paragraph starting at `start`; a span never pairs across a blank line.
+function paragraphEnd(text, start) {
+  const blank = /\n[ \t]*\n/g
+  blank.lastIndex = start
+  const match = blank.exec(text)
+  return match ? match.index : text.length
+}
+
+// Marks inline code spans so a documented example is never read as a project rule.
+// Runs of equal length pair up inside one paragraph; an unmatched run is literal text, so it
+// never consumes a later rule. The rule text itself stays readable, only its span is marked.
+function inlineCodeMask(text) {
+  const mask = new Uint8Array(text.length)
+  const runs = [...text.matchAll(/`+/g)]
+  let index = 0
+  while (index < runs.length) {
+    const opening = runs[index]
+    const limit = paragraphEnd(text, opening.index)
+    let closing = index + 1
+    while (closing < runs.length && runs[closing].index < limit
+      && runs[closing][0].length !== opening[0].length) closing++
+    if (closing === runs.length || runs[closing].index >= limit) {
+      index += 1
+      continue
+    }
+    mask.fill(1, opening.index, runs[closing].index + runs[closing][0].length)
+    index = closing + 1
+  }
+  return mask
 }
 
-function append(current, body) {
+// Only a match that starts outside inline code is an instruction rather than an example.
+// The rule itself keeps its text, because the skill name is normally written as code.
+function matchesOutsideInlineCode(text, pattern) {
+  const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`
+  const global = new RegExp(pattern.source, flags)
+  const mask = inlineCodeMask(text)
+  for (const match of text.matchAll(global)) {
+    if (!mask[match.index]) return true
+  }
+  return false
+}
+
+function append(current, body, name) {
+  const { fence, commentDepth } = scanMarkdown(current)
+  if (fence || commentDepth) {
+    const construct = fence ? 'an unclosed fenced code block' : 'an unclosed HTML comment'
+    throw new Error(`${name} ends inside ${construct}; appended Android guidance would be inactive and appended again on every run. Close it and rerun init; nothing was changed`)
+  }
   const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n'
   return `${current}${separator}${body.trim()}\n`
 }
@@ -258,7 +334,7 @@ function countMarkers(lines, start, end) {
   return { starts, ends }
 }
 
-function preserveOrAdd(current, title, id, body) {
+function preserveOrAdd(current, name, title, id, body) {
   const start = `<!-- conventions:${id}:start -->`
   const end = `<!-- conventions:${id}:end -->`
   const { starts, ends } = countMarkers(markdownView(current), start, end)
@@ -266,7 +342,7 @@ function preserveOrAdd(current, title, id, body) {
     throw new Error(`malformed ${title} section markers; preserve and repair existing guidance first`)
   }
   if (starts.length || hasHeading(current, title)) return current
-  return append(current, `${start}\n${body}\n${end}`)
+  return append(current, `${start}\n${body}\n${end}`, name)
 }
 
 function linkFrom(from, to) {
@@ -295,7 +371,43 @@ function hasLoader(current, from, to) {
   return false
 }
 
-function planInitialization(root) {
+function addTaskEntry(current, name) {
+  const start = '<!-- conventions:android-task-entry:start -->'
+  const end = '<!-- conventions:android-task-entry:end -->'
+  const lines = markdownView(current)
+  const { starts, ends } = countMarkers(lines, start, end)
+  if (starts.length !== ends.length || starts.length > 1 || (starts.length && starts[0] > ends[0])) {
+    throw new Error('malformed Android task entry markers; preserve and repair existing guidance first')
+  }
+  // Only active prose can hold a rule: fenced code, indented code, HTML comments, inline code
+  // and fenced examples are documentation. A rule keeps its own inline code, so the skill name
+  // written as `android-development` is still matched by its position outside a code span.
+  const prose = lines.map(line => line.active && line.text.trim()
+    ? stripHtmlComments(line.raw).text : '')
+  const active = prose.join('\n')
+  // Recognize an existing direct loader, not a mere skill mention or guide link.
+  const loader = /^[ \t]*(?:(?:[-+*]|\d+[.)])\s+)?(?:read|load)\s+(?:and\s+apply\s+)?(?:the\s+)?(?:installed\s+)?`?android-development`?\s+skill\s+before\b/im
+  const negation = /\b(?:do not|don't|never|must not)\s+(?:automatically\s+)?(?:read|load|apply|use|follow)\b[^.]{0,120}\bandroid-development\b/i
+  if (matchesOutsideInlineCode(active, negation)) {
+    throw new Error('existing Android skill-loading rule conflicts with task entry; nothing was changed')
+  }
+  if (starts.length) {
+    const from = lines.findIndex(line => line.comments.includes(start))
+    const to = lines.findIndex(line => line.comments.includes(end))
+    const body = prose.slice(from + 1, to).join('\n')
+    if (!matchesOutsideInlineCode(body, loader)) {
+      throw new Error('preserved Android task entry has no active loader; nothing was changed')
+    }
+    return current
+  }
+  if (matchesOutsideInlineCode(active, loader)) return current
+  if (hasHeading(current, taskEntryTitle)) {
+    throw new Error('existing Android task entry needs manual reconciliation; nothing was changed')
+  }
+  return append(current, `${start}\n${taskEntryBody}\n${end}`, name)
+}
+
+function planInitialization(root, options = { scripts: null }) {
   const claude = inspectClaude(root)
   const [agents, contributing] = ['AGENTS.md', 'CONTRIBUTING.md'].map(name => resolveTarget(root, name))
   if (agents.target === contributing.target) {
@@ -316,17 +428,18 @@ function planInitialization(root) {
   const agentsEntry = readGuidance(agents)
   const contributingEntry = readGuidance(contributing)
 
-  let agentText = agentsEntry.current ?? '# Agent instructions\n'
+  let agentText = addTaskEntry(agentsEntry.current ?? '# Agent instructions\n', agentsEntry.name)
   if (!hasLoader(agentText, agentsEntry, contributingEntry)) {
     const heading = hasHeading(agentText, sectionTitle) ? '' : `## ${sectionTitle}\n\n`
-    agentText = append(agentText, `${heading}Follow [CONTRIBUTING.md](${linkFrom(agentsEntry, contributingEntry)}) for this project's Android validation ladder, device proof and required gates.`)
+    agentText = append(agentText, `${heading}Follow [CONTRIBUTING.md](${linkFrom(agentsEntry, contributingEntry)}) for this project's Android validation ladder, device proof and required gates.`, agentsEntry.name)
   }
 
-  const contributingText = preserveOrAdd(contributingEntry.current ?? '# Contributing\n', sectionTitle, sectionId, sectionBody())
+  const contributingText = preserveOrAdd(contributingEntry.current ?? '# Contributing\n', contributingEntry.name, sectionTitle, sectionId, sectionBody())
 
   const plan = [
     { ...agentsEntry, next: agentText },
     { ...contributingEntry, next: contributingText },
+    ...scriptPlan(root, options.scripts),
   ]
 
   for (const entry of plan) {
@@ -342,10 +455,103 @@ function planInitialization(root) {
   return plan
 }
 
+function skillVersion() {
+  const text = fs.readFileSync(fileURLToPath(new URL('../SKILL.md', import.meta.url)), 'utf8')
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? ''
+  return /^release-version:\s*(\S+)\s*$/m.exec(frontmatter)?.[1] ?? 'unknown'
+}
+
+function scriptSource(name) {
+  return fs.readFileSync(fileURLToPath(new URL(`./${name}`, import.meta.url)), 'utf8')
+}
+
+function scriptHeader(name, version, source) {
+  return `# android-development skill ${version} sha256:${createHash('sha256').update(source).digest('hex')} ${name}`
+}
+
+// A copy is identifiable by its header, and its body stays byte-identical to the
+// shipped script, so an unmodified copy is recognisable and a hand edit is drift.
+// The header follows a shebang or a module docstring, so neither stops being first.
+function withHeader(source, header) {
+  const lines = source.split('\n')
+  let index = 0
+  if (lines[0].startsWith('#!')) index = 1
+  else if (/^("""|''')/.test(lines[0])) {
+    const quote = lines[0].slice(0, 3)
+    const closing = lines[0].length > 3 && lines[0].trimEnd().endsWith(quote)
+      ? 0
+      : lines.findIndex((line, position) => position > 0 && line.trimEnd().endsWith(quote))
+    if (closing >= 0) index = closing + 1
+  }
+  return [...lines.slice(0, index), header, ...lines.slice(index)].join('\n')
+}
+
+function splitHeader(text) {
+  const lines = text.split('\n')
+  // Only the preamble can hold the installed header; the body's own docs cannot.
+  const limit = Math.min(lines.length, 40)
+  for (let index = 0; index < limit; index++) {
+    if (scriptHeaderPattern.test(lines[index])) {
+      return { header: lines[index], body: [...lines.slice(0, index), ...lines.slice(index + 1)].join('\n') }
+    }
+  }
+  return { header: null, body: text }
+}
+
+function scriptsTarget(value) {
+  if (value === null || value === undefined) return null
+  const relative = (value || defaultScriptsDir).trim()
+  const segments = relative.split(/[\\/]+/).filter(segment => segment && segment !== '.')
+  if (!segments.length || path.isAbsolute(relative)
+    || segments.includes('..') || /[\r\n]/.test(relative)) {
+    throw new Error(`--install-scripts target must be a relative directory inside the project: ${relative}`)
+  }
+  return segments.join('/')
+}
+
+function scriptPlan(root, requested) {
+  const target = scriptsTarget(requested)
+  if (target === null) return []
+  const version = skillVersion()
+  return installableScripts.map(script => {
+    const file = path.join(root, target, script.name)
+    assertScriptDirectory(root, file)
+    const source = scriptSource(script.name)
+    const next = withHeader(source, scriptHeader(script.name, version, source))
+    const entry = readGuidance(resolveTarget(root, path.posix.join(target, script.name)))
+    const base = { ...entry, mode: script.mode, script: script.name }
+    if (!entry.exists) return { ...base, next, action: 'create' }
+    if (entry.current === next) return { ...base, next, action: 'unchanged' }
+    if (splitHeader(entry.current).body === source) return { ...base, next, action: 'update' }
+    // A local edit wins: report it, never overwrite it, and do not claim the skill version.
+    return { ...base, next: entry.current, action: 'drift' }
+  })
+}
+
+// The copy's directory is created, so only its nearest existing ancestor can be checked:
+// it must be a directory that stays inside the selected project.
+function assertScriptDirectory(root, file) {
+  const directory = nearestExisting(path.dirname(file))
+  const resolved = fs.lstatSync(directory).isSymbolicLink() ? fs.realpathSync(directory) : directory
+  if (!contains(root, resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new Error(`${path.relative(root, path.dirname(file))} is not a directory inside the project; no scripts were copied`)
+  }
+}
+
+function nearestExisting(target) {
+  let current = target
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current)
+    if (parent === current) return current
+    current = parent
+  }
+  return current
+}
+
 function assertWritable(plan) {
   for (const entry of plan) {
     if (entry.current === entry.next) continue
-    const target = entry.current === null ? path.dirname(entry.target) : entry.target
+    const target = entry.current === null ? nearestExisting(path.dirname(entry.target)) : entry.target
     try {
       fs.accessSync(target, fs.constants.W_OK)
     } catch {
@@ -361,13 +567,24 @@ function main(argv) {
     return
   }
   const { root } = selectRoot(options)
-  const plan = planInitialization(root)
+  const plan = planInitialization(root, options)
   if (options.write) assertWritable(plan)
   console.log(`android-development init: ${options.write ? 'write' : 'preview only'} (${root})`)
   for (const entry of plan) {
-    const action = entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update'
-    if (options.write && action !== 'unchanged') fs.writeFileSync(entry.target, entry.next)
-    console.log(`  ${entry.name}: ${!options.write && action !== 'unchanged' ? 'would ' : ''}${action}`)
+    const action = entry.action ?? (entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update')
+    const planned = action === 'create' || action === 'update'
+    if (options.write && planned) {
+      fs.mkdirSync(path.dirname(entry.target), { recursive: true })
+      fs.writeFileSync(entry.target, entry.next)
+      if (entry.mode) fs.chmodSync(entry.target, entry.mode)
+    }
+    const label = !options.write && planned ? `would ${action}` : action
+    console.log(`  ${entry.name}: ${label}`)
+  }
+  if (options.scripts === null) {
+    console.log(`  scripts: referenced from the skill (pass --install-scripts [<dir>] to copy ${installableScripts.map(script => script.name).join(' and ')} into ${defaultScriptsDir})`)
+  } else if (plan.some(entry => entry.action === 'drift')) {
+    console.log('  scripts: a locally modified copy was kept; refresh it by hand rather than overwriting the edit')
   }
   console.log('Existing sections are preserved; initialization does not refresh project policy, install tools, provision devices or authorize delivery actions.')
 }