@1aboveio/skills 1.0.13 → 1.0.15

package/skills/engineering/engineering/scripts/persist-conventions.mjs

@@ -1,6 +1,8 @@
 // persist-conventions — the tracker routing rules as the `## Issue tracking`
-// section of a repo's CONTRIBUTING.md (../SKILL.md, First use in a repo).
+// section of a repo's CONTRIBUTING.md (../SKILL.md, Tracker routing).
 // Previews unless --write; --if-missing leaves an existing section alone.
+// --write also adds the skill's task-entry loader for issue and spec creation to
+// AGENTS.md (and to a regular CLAUDE.md that does not reach AGENTS.md).
 //
 //   node persist-conventions.mjs [--repo-root <dir>] [--github-repo <owner/name>]
 //     [--linear-project <name>]... [--if-missing] [--write]
@@ -10,11 +12,24 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
-import { CONTRIBUTING_FILE, LINK_TO_AGENTS, markers, renderAgents, renderClaude, runCli } from './persist-conventions-core.mjs'
+import { CONTRIBUTING_FILE, markers, persistIndex, runCli } from './persist-conventions-core.mjs'
 
 const ID = 'tracker'
 const TEMPLATE = fs.readFileSync(fileURLToPath(new URL('../references/tracker-conventions.md', import.meta.url)), 'utf8')
 
+// Scoped to issue and spec creation: this is tracker persistence, not a general
+// invitation to load the engineering defaults into every task.
+const LOADER = {
+  id: 'tracker',
+  skill: 'engineering',
+  title: 'Tracker task entry',
+  body: [
+    'Before creating an issue, spec, epic, or sub-issue, read and apply the installed',
+    "`engineering` skill's tracker routing. This setup installs tracker routing only;",
+    "the project's routing rules stay in its contributor guide. It selects no other workflow.",
+  ].join('\n'),
+}
+
 function githubRepoFromRemote(url) {
   const m = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(url.trim())
   return m ? m[1] : null
@@ -27,22 +42,18 @@ function renderBody(githubRepo, linearProjects) {
   return TEMPLATE.replaceAll('{{githubRepo}}', githubRepo).replaceAll('{{linearProjects}}', linear)
 }
 
-// The section stays as it is; only a missing AGENTS.md index or CLAUDE.md link is added.
-function indexOnly(repoRoot, write, log) {
-  let changed = 0
-  for (const [name, render] of [['AGENTS.md', renderAgents], ['CLAUDE.md', renderClaude]]) {
-    const file = path.join(repoRoot, name)
-    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) continue
-    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
-    const next = render(current)
-    if (next === current) continue
-    changed++
-    log(`  ${name}: ${write ? 'written' : 'would change'}`)
-    if (!write) continue
-    if (next === LINK_TO_AGENTS) fs.symlinkSync('AGENTS.md', file)
-    else fs.writeFileSync(file, next)
+// The section stays as it is; only a missing AGENTS.md pointer or CLAUDE.md link and
+// the missing task-entry loader are added.
+function indexOnly(repoRoot, section, write, log) {
+  const results = persistIndex(repoRoot, section, { write })
+  const conflicts = results.flatMap(result => result.conflicts ?? [])
+  for (const result of results) {
+    for (const conflict of result.conflicts ?? []) log(`  ${result.file}: ${conflict}`)
+    if (result.action === 'blocked') log(`  ${result.file}: blocked`)
+    else if (result.action !== 'unchanged') log(`  ${result.file}: ${write ? 'written' : 'would change'}`)
   }
-  return changed ? `${changed} index file(s) ${write ? 'written' : 'would change'}` : 'nothing written'
+  const changed = results.filter((result) => !['unchanged', 'blocked'].includes(result.action)).length
+  return { summary: changed ? `${changed} index file(s) ${write ? 'written' : 'would change'}` : 'nothing written', blocked: conflicts.length > 0 }
 }
 
 function main(argv, { log = console.log } = {}) {
@@ -73,12 +84,28 @@ function main(argv, { log = console.log } = {}) {
     const file = path.join(repoRoot, CONTRIBUTING_FILE)
     const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
     if (current.includes(markers(ID)[0])) {
-      log(`persist-conventions: Issue tracking: section already present; ${indexOnly(repoRoot, argv.includes('--write'), log)}`)
-      return 0
+      const section = sectionFor(githubRepo, linearProjects)
+      const indexed = indexOnly(repoRoot, section, argv.includes('--write'), log)
+      log(`persist-conventions: Issue tracking: section already present; ${indexed.summary}`)
+      return indexed.blocked ? 2 : 0
     }
   }
-  const section = { id: ID, owner: 'engineering', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
+  const section = sectionFor(githubRepo, linearProjects)
   return runCli(rest, section, { log })
 }
 
-process.exitCode = main(process.argv.slice(2))
+function sectionFor(githubRepo, linearProjects) {
+  return {
+    id: ID,
+    owner: 'engineering',
+    title: 'Issue tracking',
+    body: renderBody(githubRepo, linearProjects),
+    loader: LOADER,
+  }
+}
+
+try { process.exitCode = main(process.argv.slice(2)) }
+catch (error) {
+  console.error(`persist-conventions: setup refused: ${error.message}`)
+  process.exitCode = 2
+}

package/skills/engineering/engineering-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: engineering-runtime
 description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Engineering Runtime

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -369,7 +369,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "5a7d8e43506d55cf9ea6e4a7c3bc44caf32f384f61b2ac83048760f522ec74c8",
+      "contentDigest": "a91694b84a0cfd014714c53a7b91e3a470fd76daccf85582c21620a4d91523fb",
       "digestExcludes": []
     },
     {
@@ -382,7 +382,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "d60f3b5770b305d86d703aecf9a08f4ed9b1ea428e881c34212529ef8d12d1f4",
+      "contentDigest": "8c4c6f21ea637ce24245cf6f20d0aa46d811c35cb8f4b81a78d07907a8c3e8af",
       "digestExcludes": []
     },
     {
@@ -395,7 +395,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "a97b8b8e123e4da19f49614540de3dd607f0711eb8b406516ca023d695a3dcfe",
+      "contentDigest": "f66eee222aef4ca965a2e9fbfbfc16a95a69213fa30472485519799e9dc99487",
       "digestExcludes": []
     },
     {
@@ -408,7 +408,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "a0ac298524bc181d5310ee8f05eb0171a8ab801f68ca18ea55b90b9a8cf54b57",
+      "contentDigest": "647fb4c57154f3e84d4adff0dd44f32a09c8fd6eb0145afbe1141d674e7965db",
       "digestExcludes": []
     },
     {
@@ -421,7 +421,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "3d5b22f5e45edbcca8b88a6802231a830f90b083de6d3fbdc0ceb823ae5971a5",
+      "contentDigest": "a9085e135bfbe535f96c4915f8402303e98e663f182b3508376799bff1013763",
       "digestExcludes": []
     },
     {
@@ -434,7 +434,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "e66777d1d522e495078dfdcb506ae815810bf0c8aa648349da4a3bb12566cfdd",
+      "contentDigest": "e21ef0dbc6f4d423b310f78ca342a20aeb672a5fb517a27f3d318e14dacd3f45",
       "digestExcludes": []
     },
     {
@@ -447,7 +447,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "01d95a93132107140a55a13fceafb0d3993c742e80dd7f367018306d71690b36",
+      "contentDigest": "435361dd2f0aecda06c751825f75d918520203c53ba245b63630eeaa390ae0c5",
       "digestExcludes": []
     },
     {
@@ -460,7 +460,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "75aebb12f6d3461fe1892bce7b535ec8dcf94b3943aa8c488cf46255654f5e57",
+      "contentDigest": "fb0eadc4b382a5e6b863d76638949052d24f8c378a74971a0a28ccf43de49e0f",
       "digestExcludes": []
     },
     {
@@ -473,7 +473,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "c5f4d18c646ece47620c9d778860c96f2f3764caa1ecaff0ef821835b7421aa0",
+      "contentDigest": "86660760773ae4869968f5e85efdab6d23e179a02f8c7066bf497f9cc64275c5",
       "digestExcludes": []
     },
     {
@@ -486,7 +486,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "491cfe94839fa027fed6c79631a8dc581f65ef1e1b222a61f76e15863e540e5b",
+      "contentDigest": "35fc60a6348784ca9b269516a0afddcc8f8e6a2dbb2f281afa657b3abe459450",
       "digestExcludes": []
     },
     {
@@ -499,7 +499,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "ec5d51ec669aa5ed0693d54ef70efd97a19dd9817accfdb2ca7afe1a711547e7",
+      "contentDigest": "826e64ed07b75f1ba24da7cac6c6e67b4f8152f5c34e067548f1af24038a3fa0",
       "digestExcludes": []
     },
     {
@@ -512,13 +512,13 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "de617480630819345cb53fea3fbd5ca2e9d4d360680a9feace942c518806f59b",
+      "contentDigest": "0fc35665e627e1c1698ba10a1c9d00a3745df10c22562b7a3ef72267e2309c4b",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "4eabbf3d0e0d3af4e9436e1a4e4c07ef153a7cc07d74d42ab94c15717146dfa3",
+  "releaseIdentity": "30ddab5b3c21191385d102158a2eb2bd3dcbd6e82d350777722543931e01ad44",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",

package/skills/engineering/ensure-coverage/SKILL.md

@@ -2,7 +2,7 @@
 name: ensure-coverage
 description: "Define or audit behavior-first test criteria — ACs, required test levels, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT judging whether a single test is any good (test-quality), authoring browser tests (e2e-test), reviewing a PR (better-review), or delivering issues (resolve-issues)."
 disable-model-invocation: true
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Ensure Coverage

package/skills/engineering/golden-path/SKILL.md

@@ -3,7 +3,7 @@ name: golden-path
 description: "Golden-path E2E: the short list of user journeys whose failure blocks a release, kept in a repo as one contract (golden-paths.json) with a generated GOLDEN_PATHS.md and a generated GitHub Actions workflow, and run against a local build or a deployed URL for an ALIVE/DEAD verdict. Use to set golden paths up in a repo ('init golden paths', 'add golden-path CI'), to migrate an older smoke.manifest.json or a hand-built smoke setup ('audit', 'migrate smoke'), to add, change, or remove a golden path, to ask 'is the build alive?' or run them before a PR or release, or when a change touches a flow listed in GOLDEN_PATHS.md. NOT for writing the Playwright specs themselves (e2e-test), deciding what a change must prove (ensure-coverage), or general workflow YAML (github-actions)."
 dependencies:
   - e2e-test
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Golden path

package/skills/engineering/harness-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: harness-runtime
 description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Harness Runtime

package/skills/engineering/resolve-issues/SKILL.md

@@ -8,7 +8,7 @@ dependencies:
   - better-review
   - golden-path
   - harness-runtime
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve issues

package/skills/engineering/resolve-issues/references/exploration.md

@@ -100,7 +100,7 @@ four are copied.
        reproduce a failed journey with it before they push a fix; never a CI
        dispatch (`gh workflow run`, `gh run rerun`). `check` may be one.
      - `skill` (every suite, present or missing): the absolute `SKILL.md` path of the installed skill for this
-       kind of journey (an emulator journey: `android-foundation`; a browser
+       kind of journey (an emulator journey: `android-development`; a browser
        one: `e2e-test`), or `null` when none is installed.
        Example: `check` dispatches the workflow input that runs the Charge
        journey; `local` runs that Charge journey script on an owned emulator,

package/skills/engineering/resolve-issues/references/review.md

@@ -9,7 +9,10 @@ restate its rules in the brief beyond the two below.
 ## Brief
 
 - Reviewer model: a different id from the implementer's
-  ([preflight.md](preflight.md#1-model-slots)).
+  ([preflight.md](preflight.md#1-model-slots)). Take its model id and effort from
+  the plan's recorded reviewer slot, a model or effort the human named included,
+  and pass them as structured launch arguments (the spawn's model and effort
+  fields), never as brief text and never a model id hardcoded here.
 - Context: spec, repository standards, target branch, unit branch and HEAD,
   parent PR when stacked or chained, exploration path, and the contracts the unit
   provides and builds on.
@@ -92,6 +95,25 @@ pass (incomplete, an open P0/P1, a GitHub re-review awaited): pick the tier
 instead. Example: round 2 passed on
 `5f63348`; CI failed and the fix pushed `2035c74`: carry, no reviewer.
 
+### Resume an incomplete review
+
+An incomplete review is unfinished work, not evidence of a bad patch: start no
+fix round. Before another launch, read the retained record for unfinished passes,
+completed commands and findings, and why the review stopped. Resolve an open
+`executionIncident` first; ask the reviewer to record missing continuation details.
+
+For the same valid HEAD and scope, resume the same reviewer in the same round
+using its result file, review clone and retained context. Give it the unfinished
+work rather than repeating the whole assignment; preserve completed valid passes.
+A wrong HEAD or invalid scope must be corrected, not carried as completed proof.
+
+If that reviewer cannot continue, state why replacement is necessary, which
+retained evidence the replacement reads, and what it redoes before launching it.
+The replacement reviews every pass with `tier: "full"`. Keep the round number,
+`fixRound`, unit `attempt` and earlier round files; incompleteness neither resets
+history nor counts as progress. Use the plan's recorded model and effort in
+structured launch arguments as [the brief](#brief) requires.
+
 ## GitHub reviews
 
 Count reviews posted on the PR by any account with write access other than
@@ -135,8 +157,9 @@ the PR author; `github-reviews.mjs` reads them and decides what blocks.
    completed review left a P0/P1 open, so skips, and any review that follows
    a passing one, never consume a fix cycle; another attempt after a
    completed blocker does, even with an unchanged patch, so fix first.
-   Resume an incomplete review in the same round with the same reviewer when
-   it can continue; a new reviewer that replaces it reviews in full and keeps
+   Resume an incomplete review in the same round
+   ([Resume an incomplete review](#resume-an-incomplete-review)); a new
+   reviewer that replaces it reviews in full and keeps
    the prior counter. Legacy records without
    `fixRound` use their attempt number; never reset history. The verdict checks the counter against the immediate prior, given
    with `--prior` when the review's filename is not `<unit>-r<N>.json`. The
@@ -178,7 +201,7 @@ the PR author; `github-reviews.mjs` reads them and decides what blocks.
    | `handback` | `not-converging`: stop fixing; mark the unit `blocked` (`blockedReason: review-handback`) and defer the PR and its open findings on its issue |
    | `decide` | `spec-question`: the printed `decide` file holds the question. Answer it ([expire.md](expire.md#decide-before-you-defer)) as a `decisions` entry whose `answers` names that file, then rerun this step with `--decision <its id>`: it writes a `test-first` fix brief that carries the decision |
    | `wait` | No P0/P1 is open, but `awaiting` names a reviewer whose changes request a fix already answered: request their re-review (`gh pr edit <N> --add-reviewer <login>`) and keep the other units shipping; rerun step 3 on each completion notice, or every 5 minutes when nothing else runs; after 30 minutes, mark the unit `blocked` (`blockedReason: review-handback`) and defer it on its issue |
-   | `review-again` | Review incomplete (`complete` not true, passes, unresolved incident, no checks, P2 with neither a URL nor a dropbox id, wrong HEAD, or a skip the rerun no longer confirms): resolve any incident, then resume or spawn the reviewer for the same round; start no fix round |
+   | `review-again` | Review incomplete (`complete` not true, passes, unresolved incident, no checks, P2 with neither a URL nor a dropbox id, wrong HEAD, or a skip the rerun no longer confirms): resolve any incident, then [resume the same reviewer, or replace it and say what changes](#resume-an-incomplete-review), for the same round; start no fix round |
    | (exit 2, no verdict) | The script could not run: fix the command or path |
 
 ## What blocks

package/skills/engineering/resolve-release/SKILL.md

@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release f
 disable-model-invocation: true
 metadata:
   workflow-role: coordinator
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve release

package/skills/engineering/rush-issues/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-issues
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush issues (shortcut of resolve-issues)

package/skills/engineering/rush-release/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-release
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush release (shortcut of resolve-release)

package/skills/engineering/test-quality/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: test-quality
 description: "Seven principles for tests that catch real bugs, and an audit that reports weak, redundant, and not-coverage tests without fixing them. Use when writing, changing, or reviewing tests, or when asked whether tests are useful, redundant, over-mocked, flaky, only assert static text, or test config files, or asked to make a slow test suite faster without losing coverage, or when the user asks to write the testing conventions into a repo's CONTRIBUTING.md. NOT defining what a spec must prove (ensure-coverage) or authoring browser tests (e2e-test)."
-release-version: 0.45.2
+release-version: 0.47.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Test Quality
@@ -82,6 +82,8 @@ node "$SKILL_DIR/scripts/persist-conventions.mjs" --write   # write, once the us
 
 It writes the seven principles ([references/testing-conventions.md](references/testing-conventions.md)) as the `## Testing conventions` section of `CONTRIBUTING.md`, between `conventions:testing` markers: a re-run replaces only that section and keeps everything else, including the `## CI conventions` and `## Delivery` sections `github-flow` writes. It adds a pointer to `AGENTS.md` unless that already names `CONTRIBUTING.md`, and creates a missing `CLAUDE.md` as a symlink to `AGENTS.md` (a regular `CLAUDE.md` that names neither file gets the pointer); missing files are created. `CONTRIBUTING.md` is the file `code-review` reads as a standards source, so the principles then apply in review too. Report each file's result line; committing is the user's call.
 
+The same run also adds one `## Testing task entry` rule to `AGENTS.md`, between `conventions:testing-task-entry` markers: when writing, changing, or reviewing tests, read and apply this skill. It is a separate check from the guide pointer — a repo whose `AGENTS.md`, or whose regular `CLAUDE.md`, already names `CONTRIBUTING.md` still gets it, because a link says where the rules live, not that the skill is loaded. The rule routes to this skill and states no new requirements; the principles stay in `CONTRIBUTING.md`. An entrypoint that already loads `test-quality`, an unmanaged section with that heading, or malformed markers is preserved and reported instead of duplicated, and a `CLAUDE.md` that points at `AGENTS.md` inherits the rule rather than a copy. Repeating the run changes nothing.
+
 ## The lint
 
 Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file from, never your CWD. `node "$SKILL_DIR/scripts/lint-tests.mjs"` scans the tree; `--diff <base>` only lines changed since the merge-base. A tool-local **gate** rule fails the command's exit status; it is not automatically a repository merge requirement. Assess optional hits in context and preserve existing adopted gates. Rules, flags, and what a clean run proves (little, for Python and Go): [references/lint.md](references/lint.md).