@1aboveio/engineering-skills 0.1.12 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1aboveio/engineering-skills",
3
- "version": "0.1.12",
3
+ "version": "0.1.14",
4
4
  "description": "Issue-to-PR and release orchestrators, review, coverage, golden paths and test quality.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -27,7 +27,7 @@
27
27
  "id": "engineering",
28
28
  "core": "@1aboveio/core-skills",
29
29
  "coreSkills": [],
30
- "digest": "a9804afc2b06ea51e2ab9ba611a502f5a8e67936493473526b1e591d02a535b0"
30
+ "digest": "ee773914a3c184667b0ed70a19a7fda18a1633b177f44ad06f1b72b90b21ad5d"
31
31
  },
32
32
  "publishConfig": {
33
33
  "registry": "https://registry.npmjs.org/",
@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/better-review). Single-agent adversarial rev
4
4
  disable-model-invocation: true
5
5
  dependencies:
6
6
  - engineering-runtime
7
- release-version: 0.45.1
7
+ release-version: 0.46.0
8
8
  ---
9
9
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
10
10
  # Better Review
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: e2e-test
3
3
  description: "Playwright end-to-end guidance for affected browser journeys, render health and presentation checks, with route manifests and sweeps for broader audits. Use when browser routes or user flows ship or change, or a Playwright test flakes. NOT for non-browser tests, defining what to test (ensure-coverage), the curated ALIVE/DEAD golden-path gate (golden-path), or CI workflow YAML (github-actions)."
4
- release-version: 0.45.1
4
+ release-version: 0.46.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # E2E Testing Standard
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: engineering
3
3
  description: "Engineering conventions: feature-delivery priorities, focused verification and review, operational boundaries, and tracker routing. Standalone /engineering offers Global, Project, or Session setup and targeted resets for configured scopes; /engineering init keeps explicit project setup. Use when setting up AGENTS.md or CONTRIBUTING.md, saving or resetting engineering defaults, or before creating an engineering issue, spec, epic, ticket, or sub-issue on GitHub or Linear. Reads existing policy without writing during ordinary work. NOT the issue-to-PR workflow (resolve-issues), release execution (resolve-release), Git delivery (github-flow), or CI setup (github-actions)."
4
- release-version: 0.45.1
4
+ release-version: 0.46.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Engineering
@@ -140,8 +140,8 @@ resolve the destination before any issue creation. Never infer a Linear project.
140
140
 
141
141
  | File or section | Init owns |
142
142
  | --- | --- |
143
- | `AGENTS.md` | Missing `Feature delivery` section and a pointer to `CONTRIBUTING.md` |
144
- | `CONTRIBUTING.md` | Missing `Engineering conventions`, `Testing conventions`, and `Issue tracking` sections |
143
+ | `AGENTS.md` | Missing pointer to `CONTRIBUTING.md`; no policy sections |
144
+ | `CONTRIBUTING.md` | Missing `Feature delivery`, `Engineering conventions`, `Testing conventions`, and `Issue tracking` sections |
145
145
 
146
146
  The templates are [feature delivery](references/feature-delivery.md),
147
147
  [engineering conventions](references/engineering-conventions.md),
@@ -152,6 +152,12 @@ without invoking its writer. `test-quality` owns the testing rules and deliberat
152
152
  updates; init only adds a missing section. The [skill review](references/init-scope.md)
153
153
  explains what is included and what remains opt-in.
154
154
 
155
+ Project policy lives in `CONTRIBUTING.md`; `AGENTS.md` carries only the loader. A
156
+ `Feature delivery` section already in `AGENTS.md`, including one an earlier init wrote,
157
+ stays where it is: init neither migrates nor deletes it, and it does not add a competing
158
+ copy to `CONTRIBUTING.md`. Existing `CONTRIBUTING.md` policy wins the same way.
159
+ Initialization moves no existing rules between files and refreshes neither.
160
+
155
161
  Existing sections, including legacy `conventions:tracker` blocks written by
156
162
  `contributing`, are preserved byte-for-byte. Repeated init is not a refresh and
157
163
  leaves manual edits unchanged. No force/update mode is implied. If policy needs to
@@ -15,7 +15,7 @@ not initialization sources; pinned external skills keep their upstream ownership
15
15
 
16
16
  | Skill | Include in guidance | Keep as a separate action |
17
17
  | --- | --- | --- |
18
- | engineering (formerly contributing) | Feature priorities, guidance lookup, tracker routing | Tracker refresh or project-policy changes |
18
+ | engineering (formerly contributing) | Feature priorities, guidance lookup and tracker routing, written as `CONTRIBUTING.md` sections; `AGENTS.md` gets only the loading pointer | Tracker refresh or project-policy changes |
19
19
  | resolve-issues | Agreed outcome, bounded supporting work, explicit stopping point | Issue planning, workers, PRs, scheduling |
20
20
  | rush-issues | Same delivery principles as resolve-issues | Shortcut workflow invocation |
21
21
  | ensure-coverage | Smallest sufficient proof, stable acceptance, required checks preserved | Ledger adoption, broad audits, new gates |
@@ -37,8 +37,12 @@ not call other skills' convention writers: they own their sections and may need
37
37
  additional decisions. Init reads `test-quality`'s canonical template directly;
38
38
  the testing owner and `conventions:testing` section identity remain unchanged.
39
39
  Existing project sections, including old testing and tracker blocks, stay unchanged.
40
- Delivery, CI, and Data Catalog conventions require separate explicit setup with
41
- their owning skills. Setup may point to these capabilities without requiring them.
40
+ Project policy is persisted in `CONTRIBUTING.md`, so `AGENTS.md` keeps only the short
41
+ loader. A `Feature delivery` section written into `AGENTS.md` by an earlier release
42
+ stays there: init does not migrate or delete it, and it does not add a competing copy
43
+ to `CONTRIBUTING.md`. Delivery, CI, and Data Catalog conventions require separate
44
+ explicit setup with their owning skills. Setup may point to these capabilities without
45
+ requiring them.
42
46
 
43
47
  Stack-specific tools, commands, cloud projects, release branches, required gates,
44
48
  and golden paths are project facts, not defaults to manufacture. Read established
@@ -43,6 +43,10 @@ new global defaults or new loading pointer in unique `engineering:<id>:start/end
43
43
  comments before recording their hashes. Do not rewrap existing text or claim it as
44
44
  owned. Keep existing valid records and add only new entries; deduplicate entries.
45
45
 
46
+ Project policy sections, including `Feature delivery` (`conventions:feature-delivery`),
47
+ live in `CONTRIBUTING.md`; `AGENTS.md` holds only the loading pointer. Record a new
48
+ pointer as an `engineering:<id>` loading addition, never as a policy section.
49
+
46
50
  Set `createdFile` only when this save created that file. Preserve unrelated bytes
47
51
  and existing links. Do not create a sidecar, global settings entry, or project file
48
52
  for a session choice. A repeated save with no additions leaves files unchanged.
@@ -73,6 +77,11 @@ scope's saved defaults, not a reinstall, refresh, or reset of every scope.
73
77
  5. Remove owned loading pointers only if they are unchanged and no longer needed
74
78
  by retained guidance. Keep a pointer that still loads user policy. Remove an
75
79
  empty ownership record and any empty wrapper heading added by this save.
80
+ For a legacy `Feature delivery` section in `AGENTS.md`, honor a valid existing
81
+ ownership record and unchanged hash under step 3, even if an earlier initializer
82
+ recorded it. Preserve and report unrecorded or edited policy under step 4; do not
83
+ infer ownership from its location or migrate it during reset. Keep the pointer
84
+ while retained `CONTRIBUTING.md` policy still needs it.
76
85
  Delete a file only if `createdFile` proves this skill created it and nothing
77
86
  except the original generated title and whitespace remains. Preserve pre-existing
78
87
  files, symlinks, hand edits, and unrelated sections; never delete an instruction
@@ -2,7 +2,7 @@
2
2
  import fs from 'node:fs'
3
3
  import path from 'node:path'
4
4
  import { spawnSync } from 'node:child_process'
5
- import { fileURLToPath } from 'node:url'
5
+ import { fileURLToPath, pathToFileURL } from 'node:url'
6
6
 
7
7
  const reference = name => fs.readFileSync(fileURLToPath(new URL(`../references/${name}.md`, import.meta.url)), 'utf8').trim()
8
8
  const usage = 'node init.mjs [--repo-root <dir>] [--github-repo <owner/name>] [--linear-project <name>]... [--write]'
@@ -54,7 +54,7 @@ function append(current, body) {
54
54
  return `${current}${separator}${body.trim()}\n`
55
55
  }
56
56
 
57
- function preserveOrAdd(current, title, id, body) {
57
+ function sectionState(current, title, id) {
58
58
  const start = `<!-- conventions:${id}:start -->`
59
59
  const end = `<!-- conventions:${id}:end -->`
60
60
  const starts = current.split(start).length - 1
@@ -62,8 +62,12 @@ function preserveOrAdd(current, title, id, body) {
62
62
  if (starts !== ends || starts > 1 || (starts && current.indexOf(start) > current.indexOf(end))) {
63
63
  throw new Error(`malformed ${title} section markers; preserve and repair existing guidance first`)
64
64
  }
65
- if (starts || current.split(/\r?\n/).some(line => line.trim() === `## ${title}`)) return current
66
- return append(current, `${start}\n${body}\n${end}`)
65
+ return Boolean(starts) || current.split(/\r?\n/).some(line => line.trim() === `## ${title}`)
66
+ }
67
+
68
+ function addSection(current, title, id, body) {
69
+ if (sectionState(current, title, id)) return current
70
+ return append(current, `<!-- conventions:${id}:start -->\n${body.trim()}\n<!-- conventions:${id}:end -->`)
67
71
  }
68
72
 
69
73
  function linkFrom(from, to) {
@@ -73,11 +77,14 @@ function linkFrom(from, to) {
73
77
  function hasLoader(current, from, to) {
74
78
  const links = /\[[^\]\r\n]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"'\r\n]*["'])?\s*\)/g
75
79
  for (const match of current.matchAll(links)) {
76
- const href = (match[1] ?? match[2]).split(/[?#]/)[0]
80
+ const href = match[1] ?? match[2]
77
81
  if (!href || /^[a-z][a-z\d+.-]*:|^\/\//i.test(href)) continue
78
82
  let target
79
83
  try {
80
- target = path.resolve(path.dirname(from.target), decodeURIComponent(href))
84
+ const link = new URL(href, pathToFileURL(from.target))
85
+ if (link.hash) continue
86
+ link.search = ''
87
+ target = fileURLToPath(link)
81
88
  } catch {
82
89
  continue
83
90
  }
@@ -114,23 +121,38 @@ function planInitialization(root, options) {
114
121
  throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
115
122
  }
116
123
 
117
- let agentText = preserveOrAdd(agents.current ?? '# Agent instructions\n', 'Feature delivery',
118
- 'feature-delivery', reference('feature-delivery'))
124
+ // AGENTS.md loads the policy; it does not carry it. Init adds only the pointer.
125
+ const agentBase = agents.current ?? '# Agent instructions\n'
126
+ // An earlier release put Feature delivery in AGENTS.md. That policy stays where it is:
127
+ // init neither migrates it nor adds a competing copy to CONTRIBUTING.md.
128
+ const featureDeliveryInAgents = sectionState(agentBase, 'Feature delivery', 'feature-delivery')
129
+ let agentText = agentBase
119
130
  if (!hasLoader(agentText, agents, contributing)) {
120
131
  agentText = append(agentText, `## Contributing\n\nFollow [CONTRIBUTING.md](${linkFrom(agents, contributing)}) for this project's engineering conventions and existing delivery requirements.`)
121
132
  }
122
133
 
123
- let contributingText = preserveOrAdd(contributing.current ?? '# Contributing\n', 'Engineering conventions',
134
+ let contributingText = contributing.current ?? '# Contributing\n'
135
+ const featureDeliveryInContributing = sectionState(contributingText, 'Feature delivery', 'feature-delivery')
136
+ if (!featureDeliveryInAgents && !featureDeliveryInContributing) {
137
+ contributingText = addSection(contributingText, 'Feature delivery', 'feature-delivery',
138
+ reference('feature-delivery'))
139
+ }
140
+ contributingText = addSection(contributingText, 'Engineering conventions',
124
141
  'engineering', reference('engineering-conventions'))
125
142
  const testing = fs.readFileSync(new URL('../../test-quality/references/testing-conventions.md', import.meta.url), 'utf8').trim()
126
- contributingText = preserveOrAdd(contributingText, 'Testing conventions', 'testing', testing)
127
- contributingText = preserveOrAdd(contributingText, 'Issue tracking', 'tracker',
143
+ contributingText = addSection(contributingText, 'Testing conventions', 'testing', testing)
144
+ contributingText = addSection(contributingText, 'Issue tracking', 'tracker',
128
145
  trackerBody(options.githubRepo ?? githubRepo(root), options.linearProjects))
129
146
 
130
- return [
131
- { ...agents, next: agentText },
132
- { ...contributing, next: contributingText },
133
- ]
147
+ return {
148
+ entries: [
149
+ { ...agents, next: agentText },
150
+ { ...contributing, next: contributingText },
151
+ ],
152
+ notes: featureDeliveryInAgents
153
+ ? ['Feature delivery stays in AGENTS.md; no competing section added to CONTRIBUTING.md']
154
+ : [],
155
+ }
134
156
  }
135
157
 
136
158
  function main(argv) {
@@ -142,13 +164,14 @@ function main(argv) {
142
164
  const selected = options.repoRoot ?? gitOutput(process.cwd(), ['rev-parse', '--show-toplevel']) ?? process.cwd()
143
165
  const root = fs.realpathSync(selected)
144
166
  if (!fs.statSync(root).isDirectory()) throw new Error('project root is not a directory')
145
- const plan = planInitialization(root, options)
167
+ const { entries, notes } = planInitialization(root, options)
146
168
  console.log(`engineering init: ${options.write ? 'write' : 'preview only'} (${root})`)
147
- for (const entry of plan) {
169
+ for (const entry of entries) {
148
170
  const action = entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update'
149
171
  if (options.write && action !== 'unchanged') fs.writeFileSync(entry.target, entry.next)
150
172
  console.log(` ${entry.name}: ${!options.write && action !== 'unchanged' ? 'would ' : ''}${action}`)
151
173
  }
174
+ for (const note of notes) console.log(` note: ${note}`)
152
175
  console.log('Existing sections are preserved; initialization does not refresh project policy or authorize delivery actions.')
153
176
  }
154
177
 
@@ -3,7 +3,7 @@ name: engineering-runtime
3
3
  description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
4
4
  disable-model-invocation: true
5
5
  user-invocable: false
6
- release-version: 0.45.1
6
+ release-version: 0.46.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Engineering Runtime
@@ -369,7 +369,7 @@
369
369
  "repository": "1aboveio/ai",
370
370
  "revision": "main"
371
371
  },
372
- "contentDigest": "e1a3eda72480a554a71b876b0803ffadb6d975f57ce73e9ae84e3a30a75630bc",
372
+ "contentDigest": "d50381c5d34f05b3c4ac60bd0d1a5a56fdeb7112caf3a58303e2c8d5b9cd73d4",
373
373
  "digestExcludes": []
374
374
  },
375
375
  {
@@ -382,7 +382,7 @@
382
382
  "repository": "1aboveio/ai",
383
383
  "revision": "main"
384
384
  },
385
- "contentDigest": "4976da3d810ab0a712121dfc5acbd62f63f8ae42ec0116431ad7d27d0c52a324",
385
+ "contentDigest": "7fb81756e33e2582cc02b2a964af1361a474ddae64f1304dfdff680162e5f35e",
386
386
  "digestExcludes": []
387
387
  },
388
388
  {
@@ -395,7 +395,7 @@
395
395
  "repository": "1aboveio/ai",
396
396
  "revision": "main"
397
397
  },
398
- "contentDigest": "32204a3fe185c2ea79eb27b0dd4055c321ef7b9f152ffc3a374b714ae8d465fa",
398
+ "contentDigest": "08e07649d8ee91496a4275c9417cd679932d798c91cdbb483ca45979733dd0c3",
399
399
  "digestExcludes": []
400
400
  },
401
401
  {
@@ -408,7 +408,7 @@
408
408
  "repository": "1aboveio/ai",
409
409
  "revision": "main"
410
410
  },
411
- "contentDigest": "6dc6606527c8023eb1f79a188ae73bea4fafe8b339ed391a00fae60340107e0c",
411
+ "contentDigest": "45e72502bf9d1f707caf2990ba8a9bda7fbda4e748b5f798731a1d0d992b0b02",
412
412
  "digestExcludes": []
413
413
  },
414
414
  {
@@ -421,7 +421,7 @@
421
421
  "repository": "1aboveio/ai",
422
422
  "revision": "main"
423
423
  },
424
- "contentDigest": "0ec4a9d50c9918d1219a2454ea2aad7eb3ffdabe917319c55d7928c6d5e3580e",
424
+ "contentDigest": "5cf9c65216eda37ed0acebcaa97be9eea9239fad96397cdd858b4694cae9d906",
425
425
  "digestExcludes": []
426
426
  },
427
427
  {
@@ -434,7 +434,7 @@
434
434
  "repository": "1aboveio/ai",
435
435
  "revision": "main"
436
436
  },
437
- "contentDigest": "388bd68865a9af12e76b1a522f879684546d5d03427649df5639b16d0b0240b9",
437
+ "contentDigest": "6e1c15f7d61a3bb2af78df82b57674152d9c321cc17b5a83d32379cc0a9104ef",
438
438
  "digestExcludes": []
439
439
  },
440
440
  {
@@ -447,7 +447,7 @@
447
447
  "repository": "1aboveio/ai",
448
448
  "revision": "main"
449
449
  },
450
- "contentDigest": "d7552f7681020f9cd4ed72dbde105adb5b172e40ba4119bcbb0d4685688faf18",
450
+ "contentDigest": "303941d679cacbafc5594a6b8369e016cef3cdf3c065ae919edc8695cbce8a69",
451
451
  "digestExcludes": []
452
452
  },
453
453
  {
@@ -460,7 +460,7 @@
460
460
  "repository": "1aboveio/ai",
461
461
  "revision": "main"
462
462
  },
463
- "contentDigest": "414606c12207509b0d9207b0021dbb29bcb1689ca7d7486496ab2bc6a1dfecfc",
463
+ "contentDigest": "d8de3acaf463033d55e5bedf17b5aeac8e9a1d77267c5960af18bdebbaf18c7d",
464
464
  "digestExcludes": []
465
465
  },
466
466
  {
@@ -473,7 +473,7 @@
473
473
  "repository": "1aboveio/ai",
474
474
  "revision": "main"
475
475
  },
476
- "contentDigest": "274f5ac6be3224dfdafaa4264cfa0ed223e3b98cf3cbd2c083b6c85314a92791",
476
+ "contentDigest": "8b8a149b90292ae4b0c3dd8b34a387ea7fa8c154610c232c8c55ce9781cca03d",
477
477
  "digestExcludes": []
478
478
  },
479
479
  {
@@ -486,7 +486,7 @@
486
486
  "repository": "1aboveio/ai",
487
487
  "revision": "main"
488
488
  },
489
- "contentDigest": "a6efa258db14db8a4cab8600bcbdc2563c61531a51a486508ed42da70824be86",
489
+ "contentDigest": "553b2748b6357b92caa30ee29351add044d10cc6ad28e4cdb809f4f23bb5a9da",
490
490
  "digestExcludes": []
491
491
  },
492
492
  {
@@ -499,7 +499,7 @@
499
499
  "repository": "1aboveio/ai",
500
500
  "revision": "main"
501
501
  },
502
- "contentDigest": "869bf4214b7e80e4968e4488f2f6ad4a944b2393a343ad40157e45f694457814",
502
+ "contentDigest": "65bb8314e2fe1f2ebbdca60f2dcd433af44a8eeba080adf30f0682ef5c0a2acd",
503
503
  "digestExcludes": []
504
504
  },
505
505
  {
@@ -512,13 +512,13 @@
512
512
  "repository": "1aboveio/ai",
513
513
  "revision": "main"
514
514
  },
515
- "contentDigest": "bc78899c2a745aedee9f547a16b8c2be2ffab8a128695b033991802d033db303",
515
+ "contentDigest": "9fb61a9e59fee73ff803113e9d33e47bc19a2ef5ce92c06f63a4d5cca8a72189",
516
516
  "digestExcludes": [
517
517
  "coherence/workflow.json"
518
518
  ]
519
519
  }
520
520
  ],
521
- "releaseIdentity": "fed4e4c161cf525a08eee89fb30ba578ec21962b2d4cb9c9226fc61146fe4225",
521
+ "releaseIdentity": "d0f4c3cc3c13714b4d4be17f6b8b1f56aff7fe1901be7c7823f4faba348baeb6",
522
522
  "lifecycleAuthority": "native-skills-cli",
523
523
  "repairRecipe": {
524
524
  "id": "engineering-workflow-dependency-first",
@@ -2,7 +2,7 @@
2
2
  name: ensure-coverage
3
3
  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)."
4
4
  disable-model-invocation: true
5
- release-version: 0.45.1
5
+ release-version: 0.46.0
6
6
  ---
7
7
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
8
8
  # Ensure Coverage
@@ -3,7 +3,7 @@ name: golden-path
3
3
  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)."
4
4
  dependencies:
5
5
  - e2e-test
6
- release-version: 0.45.1
6
+ release-version: 0.46.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Golden path
@@ -3,7 +3,7 @@ name: harness-runtime
3
3
  description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
4
4
  disable-model-invocation: true
5
5
  user-invocable: false
6
- release-version: 0.45.1
6
+ release-version: 0.46.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Harness Runtime
@@ -8,7 +8,7 @@ dependencies:
8
8
  - better-review
9
9
  - golden-path
10
10
  - harness-runtime
11
- release-version: 0.45.1
11
+ release-version: 0.46.0
12
12
  ---
13
13
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
14
14
  # Resolve issues
@@ -41,7 +41,8 @@ what did not pass).
41
41
  ## Principles
42
42
 
43
43
  Read the [delivery principles](references/principles.md) before substantive work
44
- and include them verbatim in every worker brief. They are guidelines, not
44
+ for coordinator decisions. Give workers only the principles relevant to their task,
45
+ not the coordinator's scheduling instructions. They are guidelines, not
45
46
  restrictions: when two pull apart, take the one that ships sooner at the same bar.
46
47
 
47
48
  `/rush-issues` runs this workflow with every answer defaulted ([shortcut mode](references/preflight.md#shortcut-mode)).
@@ -130,7 +131,7 @@ infrastructure, and report verified behavior. Full acceptance and required CI st
130
131
  ## Every brief contains
131
132
 
132
133
  Use the full [brief checklist](references/delivery-progress.md#every-brief-contains),
133
- including the Goal and [Principles](references/principles.md) verbatim, checkpoint history and result contract.
134
+ including the worker-specific contract, checkpoint history and result contract.
134
135
  Treat a missing or unreadable result as incomplete; resume a dead spawn once in its workspace.
135
136
 
136
137
  ## Workflow
@@ -1,7 +1,11 @@
1
1
  # CI, queue, and merge
2
2
 
3
- Run per PR, in parallel with its review, from the moment its draft PR
4
- opens.
3
+ The coordinator owns external CI and PR monitoring, review scheduling, readiness,
4
+ enqueue and merge per PR, in parallel with review from the moment the draft opens.
5
+ Use background tasks for CI and delivery watching so scheduling can continue; follow
6
+ the queue owner's watcher where applicable. Workers may make short status reads or
7
+ fetch failed logs for diagnosis, but must not run `gh run watch`,
8
+ `gh pr checks --watch`, a delivery watcher, or create background monitoring.
5
9
 
6
10
  1. Watch the required checks for every pushed HEAD. Pushes to the unit's own
7
11
  PR branch need no approval. Green means every required check ran and passed
@@ -10,7 +14,9 @@ opens.
10
14
  2. On failure, read the logs; have a fix worker reproduce it, fix it on the
11
15
  same branch, rerun the failing check (a journey: off CI, with
12
16
  `proof.suite.local`) and the checks the fix affects plus
13
- typecheck and build, and return the commands and results. An
17
+ typecheck and build, push the permitted branch, write its result and return
18
+ without waiting for CI. Pending CI is not a pass and does not weaken acceptance.
19
+ Long local tests and builds needed for the repair are allowed. An
14
20
  infrastructure failure goes to [expire.md](expire.md#infrastructure-failures).
15
21
  3. A changed HEAD needs approval bound to that HEAD: push it and let CI
16
22
  run. After a passing review, [carry](review.md#carry-after-a-pass) it:
@@ -49,9 +49,19 @@ issue or automatic scheduler gate. They do not waive required validation.
49
49
  - the [immediate acceptance checkpoint](#delivery-progress), existing baseline (or none),
50
50
  and, for a continuation, the last result, remaining uncertainty and next distinguishing
51
51
  test; retain the same checkpoint/history when changing workers
52
- - the [Goal](../SKILL.md#goal) and [Principles](principles.md), verbatim (a reviewer gets review.md's two rules instead)
52
+ - a concise worker-specific contract: business outcome and context, full acceptance,
53
+ security and quality requirements, and principles relevant to the assigned work; a
54
+ reviewer gets review.md's two rules instead. Do not forward coordinator scheduling
55
+ instructions wholesale
56
+ - for implement and fix workers: implement or repair, run focused checks and required
57
+ local validation, push the permitted branch, write the result, and return. The
58
+ coordinator owns external CI/PR monitoring, review scheduling, readiness, enqueue
59
+ and merge. Short status reads and fetching failed logs for diagnosis are allowed;
60
+ no `gh run watch`, `gh pr checks --watch`, delivery watcher, or worker-created
61
+ background monitoring. Long local tests and builds remain allowed when needed.
62
+ Pending CI is a valid handoff, not a passed check or permission to weaken acceptance
53
63
  - the result path, `<run>/results/<unit>-<label>.json` (`<label>`: kind and attempt, e.g. `fix-2`), with `unit` and `decisionNeeded` (null or a choice)
54
- - at the deadline: stop starting work, commit, and report
64
+ - at the deadline: stop starting work, commit, and report; identify any unpushed work or pending checks
55
65
  - environment rules: write only inside the workspace and its planned resources (and the findings directory for the explorer),
56
66
  with private caches and temp files registered before use (`TMPDIR`, `npm_config_cache`, `UV_CACHE_DIR`);
57
67
  reuse them through retries and return them to the cleanup owner ([workspaces](workspaces.md)); use the machine's
@@ -109,14 +109,22 @@ Example: a worker ran from 08:16; its workspace last changed at 09:10, and
109
109
  nothing was checked until the human asked at 11:19. It had been stuck for two
110
110
  hours.
111
111
 
112
- - Record `workerSince` when you start a worker. While any worker runs, keep
113
- one heartbeat running (a background `sleep 1800`) so a completion notice
114
- reaches you even when no worker finishes; on each notice read fresh capacity
115
- and run `next-actions.mjs` with the [live capacity arguments](implementation.md#live-capacity).
116
- When it prints only `wait`, keep the heartbeat and end the turn: the harness
117
- wakes the run at the printed time.
118
- - `check-worker` means the worker changed no workspace file for
119
- `--quiet-minutes` (45 by default): read its latest output. Stuck: stop it
112
+ - Record `workerSince` when you start a worker. Pi's subagent extension attaches
113
+ every single or batch launch to one shared supervision watcher and stops it
114
+ when the last active worker ends. Leave stall detection enabled; do not start
115
+ a separate heartbeat or background watcher for subagents. On a completion or
116
+ stale-worker notice, read fresh capacity and run `next-actions.mjs` with the
117
+ [live capacity arguments](implementation.md#live-capacity).
118
+ - When the scheduler prints only `wait`, no worker is active. Arm one one-shot
119
+ background timer for the earliest retry time before ending the turn; the
120
+ scheduler prints the deadline but does not schedule a wakeup. Use the `wait`
121
+ action's `delaySeconds` for `sleep`, with its completion callback enabled.
122
+ Keep its task ID in the run's note. Reuse it while its deadline is unchanged;
123
+ cancel and replace it if the deadline changes, and cancel it when work resumes
124
+ or the run finishes. This retry timer is not a worker watcher.
125
+ - A stale-worker notice or `check-worker` calls for inspection, not automatic
126
+ termination. `check-worker` means no workspace file changed for
127
+ `--quiet-minutes` (45 by default): read the worker's latest output. Stuck: stop it
120
128
  and take the `timeout-task` response. A long test with advancing test/phase results
121
129
  inside its declared command deadline may continue. Repeated heartbeats, unchanged
122
130
  logs or an unbounded child wait are not that evidence.
@@ -100,7 +100,7 @@ four are copied.
100
100
  reproduce a failed journey with it before they push a fix; never a CI
101
101
  dispatch (`gh workflow run`, `gh run rerun`). `check` may be one.
102
102
  - `skill` (every suite, present or missing): the absolute `SKILL.md` path of the installed skill for this
103
- kind of journey (an emulator journey: `android-foundation`; a browser
103
+ kind of journey (an emulator journey: `android-development`; a browser
104
104
  one: `e2e-test`), or `null` when none is installed.
105
105
  Example: `check` dispatches the workflow input that runs the Charge
106
106
  journey; `local` runs that Charge journey script on an owned emulator,
@@ -2,9 +2,10 @@
2
2
 
3
3
  ## Principles
4
4
 
5
- Give these to every implementer and fix worker, with SKILL.md's
6
- [Principles](../SKILL.md#principles). Each is a guideline toward the
7
- [Goal](../SKILL.md#goal), then an example.
5
+ Use these worker-relevant guidelines in implementer and fix briefs, alongside the
6
+ [worker contract](delivery-progress.md#every-brief-contains). Each serves the
7
+ [Goal](../SKILL.md#goal), then gives an example; coordinator scheduling stays with
8
+ the coordinator.
8
9
 
9
10
  1. **Done is the requested outcome working and its agreed criteria passing at `proof.level`.**
10
11
  Example: the Charge layout persists per installation and the repository test passes
@@ -27,9 +28,9 @@ Give these to every implementer and fix worker, with SKILL.md's
27
28
  5. **Run focused checks locally; CI runs the rest.**
28
29
  Example: run the touched package's tests and typecheck, push, and let CI
29
30
  run the full matrix. Never rebuild a release device campaign in a unit.
30
- 6. **Report in one short record.**
31
+ 6. **Report in one short record and return.**
31
32
  Example: "Persists the Charge layout per installation. Ran charge tests
32
- and typecheck: pass. CI: <link>. Pending: release device campaign
33
+ and typecheck: pass. CI: pending. Pending: release device campaign
33
34
  (#1400)." Provenance, when required, is the CI run's artifacts.
34
35
 
35
36
  After the approval, schedule runnable units continuously within
@@ -104,7 +105,13 @@ implementer in its kept workspace with the brief and its findings entry.
104
105
  nothing else: no artifact hashes, version inventories, screenshots,
105
106
  copied logs, or earlier attempts. For a continuation, include the current checkpoint,
106
107
  outcome and relevant prior-result links in the existing integration notes; do not
107
- duplicate the full attempt history.
108
+ duplicate the full attempt history. After focused validation, the permitted push,
109
+ and the result, return without waiting for external CI or PR monitoring. Report
110
+ pending CI as pending; it does not meet full acceptance. The coordinator schedules
111
+ review and owns CI, readiness, enqueue and merge. Short status reads and failed-log
112
+ retrieval for diagnosis are allowed, but worker-created background monitoring,
113
+ delivery watchers, `gh run watch`, and `gh pr checks --watch` are not. This does
114
+ not prohibit long local tests or builds needed for the assigned validation.
108
115
 
109
116
  After 2 fix cycles without progress, or a stuck or late worker, follow
110
117
  [expire.md](expire.md). Start the next worker in the same workspace with the
@@ -125,7 +132,8 @@ transcript.
125
132
  only they show. A journey can satisfy several obligations it actually exercises;
126
133
  a new branch does not automatically need another test layer.
127
134
  - When CI runs the unit's `browser` or `emulator` suite, CI proves it: push
128
- and read the journey's result on the pushed HEAD. CI confirms a fix; it
135
+ and the coordinator reads the journey's result on the pushed HEAD. The worker
136
+ returns with CI pending. CI confirms a fix; it
129
137
  never debugs one. After a failed journey, reproduce it with
130
138
  `proof.suite.local` before the next push or dispatch. When `local` passes
131
139
  where CI fails, the difference is the environment: run CI once more with
@@ -1,7 +1,8 @@
1
1
  # Delivery principles
2
2
 
3
- Guidelines, not restrictions; put them in every brief. When two pull apart, take the one that
4
- ships sooner at the same bar.
3
+ Coordinator guidance, not a worker brief. Give workers only the principles relevant to
4
+ their assignment; do not forward scheduling instructions wholesale. These are guidelines,
5
+ not restrictions; when two pull apart, take the one that ships sooner at the same bar.
5
6
 
6
7
  1. **Deliver when the requested behavior works and the agreed checks pass.**
7
8
  Example: the cashier can submit the Charge, the plan's charge tests and typecheck
@@ -30,7 +31,8 @@ ships sooner at the same bar.
30
31
  reviewer. A P0/P1 fix: delta; one that rewrote most of the PR: full.
31
32
  7. **Coordinate first.** On every completion notice, read fresh capacity and run `scripts/next-actions.mjs --run <run>`
32
33
  with the [live capacity arguments](implementation.md#live-capacity); do everything it prints
33
- before resuming your own work; keep a [heartbeat](expire.md#waits).
34
+ before resuming your own work. The harness owns [worker monitoring](expire.md#waits);
35
+ do not start a duplicate heartbeat.
34
36
  Example: mid-way through an emulator debug, a notice says `impl-1322`
35
37
  finished; the script prints `start-review 1322` and `fill-slot 1323`, so
36
38
  start both, then return to the debug. On a new invocation, call it first with `--resume`.
@@ -67,7 +67,7 @@
67
67
  // retry-blocked everything else is settled and a unit blocked on a cause that can clear by
68
68
  // itself (retry-*, timeout-task, spawn-death, external-blocker) is due its next automatic attempt
69
69
  // (30m, 2h, 8h after blockedAt): set it in-flight, autoRetries + 1
70
- // wait the same, but no attempt is due yet: keep a heartbeat, never finish
70
+ // wait no worker is active and no retry is due: arm one one-shot timer, never finish
71
71
  // finish every unit is delivered, blocked, cancelled, or not started behind one of
72
72
  // those (named in the detail, with units built whose PR cannot open because a
73
73
  // parent will not land): write the handoff. For a
@@ -686,7 +686,10 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
686
686
  for (const u of retryable.filter((v) => !v.blockedAt || !Number.isFinite(now))) due.push({ action: 'retry-blocked', unit: String(u.id), detail: retryDetail(u) })
687
687
  } else if (retryable.length) {
688
688
  const next = retryable.reduce((a, u) => (dueAt(u) < dueAt(a) ? u : a))
689
- due.push({ action: 'wait', unit: String(next.id), detail: `unit ${next.id} is blocked (${next.blockedReason}); its next automatic attempt is at ${new Date(dueAt(next)).toISOString()}: keep a heartbeat until then and do not finish` })
689
+ const wakeAt = new Date(dueAt(next)).toISOString()
690
+ const delaySeconds = Math.max(0, Math.ceil((dueAt(next) - now) / 1000))
691
+ due.push({ action: 'wait', unit: String(next.id), wakeAt, delaySeconds,
692
+ detail: `unit ${next.id} is blocked (${next.blockedReason}); its next automatic attempt is at ${wakeAt}: arm one one-shot background retry timer (sleep ${delaySeconds}, completion callback enabled); cancel any obsolete retry timer and do not finish` })
690
693
  } else {
691
694
  const retained = units.filter((u) => managed(u) && u.lifecycle?.cleanup?.state === 'retained').map((u) => `${u.id}: ${u.lifecycle.cleanup.reason}`)
692
695
  due.push({ action: 'finish', unit: null, detail: `every unit is delivered, blocked, cancelled, or not started behind one of those: write the handoff${parked.length ? `; not started: ${parked.join(', ')}` : ''}${built.length ? `; built, PR not opened: ${built.join(', ')}` : ''}${openWaiting.length ? `; PR open, cannot land: ${openWaiting.join(', ')}` : ''}${retained.length ? `; retained environments (not cleaned): ${retained.join('; ')}` : ''}` })
@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release f
4
4
  disable-model-invocation: true
5
5
  metadata:
6
6
  workflow-role: coordinator
7
- release-version: 0.45.1
7
+ release-version: 0.46.0
8
8
  ---
9
9
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
10
10
  # Resolve release
@@ -6,7 +6,7 @@ metadata:
6
6
  workflow-role: coordinator
7
7
  dependencies:
8
8
  - resolve-issues
9
- release-version: 0.45.1
9
+ release-version: 0.46.0
10
10
  ---
11
11
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
12
12
  # Rush issues (shortcut of resolve-issues)
@@ -6,7 +6,7 @@ metadata:
6
6
  workflow-role: coordinator
7
7
  dependencies:
8
8
  - resolve-release
9
- release-version: 0.45.1
9
+ release-version: 0.46.0
10
10
  ---
11
11
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
12
12
  # Rush release (shortcut of resolve-release)
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: test-quality
3
3
  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)."
4
- release-version: 0.45.1
4
+ release-version: 0.46.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Test Quality