@1aboveio/engineering-skills 0.1.17 → 0.1.19

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.17",
3
+ "version": "0.1.19",
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": "eae585fe9a49dc577ca68ba48e060176008f7a2a6cd0e1f48e1b9f60fd12072d"
30
+ "digest": "0f52868df5188ad53194a31160c6584c37dbe248264ce40644729b928fca59a0"
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.48.1
7
+ release-version: 0.49.1
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.48.1
4
+ release-version: 0.49.1
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.48.1
4
+ release-version: 0.49.1
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Engineering
@@ -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.48.1
6
+ release-version: 0.49.1
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": "0ee641d7c1c90df5d1ca4d4f516f3aec0236ae224f2cfdf5e69a8d0023d0224f",
372
+ "contentDigest": "93ac20a3d5d41b233b13e521ba1b65d0a3e339958422a56ffad00a844656a23f",
373
373
  "digestExcludes": []
374
374
  },
375
375
  {
@@ -382,7 +382,7 @@
382
382
  "repository": "1aboveio/ai",
383
383
  "revision": "main"
384
384
  },
385
- "contentDigest": "b0c6b061b9d99a3fdf61ee41a3380986f8b0e6f687fc14158071ba5cfc4ad231",
385
+ "contentDigest": "915715a605bf78f6f69cb8c95f7227548a6d71a6ef0ce502b5b5c5a357676d19",
386
386
  "digestExcludes": []
387
387
  },
388
388
  {
@@ -395,7 +395,7 @@
395
395
  "repository": "1aboveio/ai",
396
396
  "revision": "main"
397
397
  },
398
- "contentDigest": "00afe10ecfc7fb382a3c9ddf7cfb1264eeeb003e935c3fd8eee09af7f0e6dc4c",
398
+ "contentDigest": "1ef2fd2ad328c373c7c6fe42007908766860cd8051e1807739797303aaadeae4",
399
399
  "digestExcludes": []
400
400
  },
401
401
  {
@@ -408,7 +408,7 @@
408
408
  "repository": "1aboveio/ai",
409
409
  "revision": "main"
410
410
  },
411
- "contentDigest": "807efefc218519809541349ebc10358d37c5688d5d657fe2a58dc85e2a9aa055",
411
+ "contentDigest": "3c9509027191a2b2612f3905defb5ed9c47580709ba77b46c0e8433d354c4d33",
412
412
  "digestExcludes": []
413
413
  },
414
414
  {
@@ -421,7 +421,7 @@
421
421
  "repository": "1aboveio/ai",
422
422
  "revision": "main"
423
423
  },
424
- "contentDigest": "efb97f0e66dec6c2d6894a1feb128892f6974d9aa71c83a29acabf22852f2228",
424
+ "contentDigest": "5e419edc77397a9021a24fc9da83d07c83aa786853dcb24916d8fb2655f81ea9",
425
425
  "digestExcludes": []
426
426
  },
427
427
  {
@@ -434,7 +434,7 @@
434
434
  "repository": "1aboveio/ai",
435
435
  "revision": "main"
436
436
  },
437
- "contentDigest": "a54c0d8d50bd9de11b98118072a87f1fefb1930e4936eae4ad1c8d369125e80b",
437
+ "contentDigest": "ecee12f24d18d49ec1be030e3f831c3d07a66f37b0b16aa5efef365ca381e558",
438
438
  "digestExcludes": []
439
439
  },
440
440
  {
@@ -447,7 +447,7 @@
447
447
  "repository": "1aboveio/ai",
448
448
  "revision": "main"
449
449
  },
450
- "contentDigest": "2700f926acbfc82dec992a81f42373f5ac03d8e6cdfd9288e447e72e4215ca11",
450
+ "contentDigest": "2fbd1a9e15087045fa80b47d9b6db8695009c900c2e4aeeab71207875b071c74",
451
451
  "digestExcludes": []
452
452
  },
453
453
  {
@@ -460,7 +460,7 @@
460
460
  "repository": "1aboveio/ai",
461
461
  "revision": "main"
462
462
  },
463
- "contentDigest": "a00c2848f686ee2d4775661f87c2569b4810480233f4a0649ca995f0bebdb2a8",
463
+ "contentDigest": "8c33282acdf9a7b3ba3adf46065249126efdd8669487ad7def1b4302155db3dd",
464
464
  "digestExcludes": []
465
465
  },
466
466
  {
@@ -473,7 +473,7 @@
473
473
  "repository": "1aboveio/ai",
474
474
  "revision": "main"
475
475
  },
476
- "contentDigest": "27b87c7ac54bfc217ffe5c68fae0a9d9b1dd8619286c470ca721200bb6962bd8",
476
+ "contentDigest": "e612b320be1b3aee539a26494e2048e0bbdc1947166fa4cffbdfe8085a64b50a",
477
477
  "digestExcludes": []
478
478
  },
479
479
  {
@@ -486,7 +486,7 @@
486
486
  "repository": "1aboveio/ai",
487
487
  "revision": "main"
488
488
  },
489
- "contentDigest": "a67d55dda1c9278b16d192efe28d2827d2a1010b7c14bde8bf3ac10ce78adf13",
489
+ "contentDigest": "53732d354995ca40c0325b2f860a4facf2e79b9d6d373fbc76a5ce5b3a1f1e29",
490
490
  "digestExcludes": []
491
491
  },
492
492
  {
@@ -499,7 +499,7 @@
499
499
  "repository": "1aboveio/ai",
500
500
  "revision": "main"
501
501
  },
502
- "contentDigest": "15626fe123fbf537b89af3cb34349430fc1c76c4ad04e8853f6e761c7f45db30",
502
+ "contentDigest": "61f8b7f04887b86338984f03527fdaf66ec90df7ff89c19ee9dca6f362fe212a",
503
503
  "digestExcludes": []
504
504
  },
505
505
  {
@@ -512,13 +512,13 @@
512
512
  "repository": "1aboveio/ai",
513
513
  "revision": "main"
514
514
  },
515
- "contentDigest": "1bdafd5f8149b4020319869ae83c17734cec9c2c52f7dc28d5c672985ca73111",
515
+ "contentDigest": "ad9bdbfbaeb4c575f8fad5b53367403096594aafce8e686926ddb734c185155a",
516
516
  "digestExcludes": [
517
517
  "coherence/workflow.json"
518
518
  ]
519
519
  }
520
520
  ],
521
- "releaseIdentity": "446559a9feac423ab3c67e5b391ea300aeb1e5a80ec94a66a69062025e47a87a",
521
+ "releaseIdentity": "2ed547516d442d0bfad21952001956420f71a972849049507530f80ad16eda83",
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.48.1
5
+ release-version: 0.49.1
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.48.1
6
+ release-version: 0.49.1
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.48.1
6
+ release-version: 0.49.1
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Harness Runtime
@@ -36,7 +36,8 @@
36
36
  // PI_AGENT_CATALOG_COMMAND JSON argv array: '["node","/abs/agent-catalog.mjs"]'
37
37
  // (preferred when arguments are needed), or a bare
38
38
  // executable token: 'pi-agent-catalog'.
39
- // default pi-agent-catalog on PATH.
39
+ // default pi-agent-catalog on PATH, then (Pi only) the
40
+ // catalog in Pi's installed npm packages on ENOENT.
40
41
  // A bare token cannot carry arguments — that is deliberate, so no quoting rule
41
42
  // sneaks shell semantics in. Nothing here runs npm/npx, resolves a sibling
42
43
  // checkout, or reads a registry.
@@ -48,8 +49,9 @@
48
49
  // install (`~/.agents/skills/{resolve-issues,harness-runtime}`). No path in this
49
50
  // file is relative to a source-domain layout.
50
51
  import { spawnSync } from 'node:child_process'
51
- import { readFileSync } from 'node:fs'
52
- import { resolve as resolvePath } from 'node:path'
52
+ import { readFileSync, statSync } from 'node:fs'
53
+ import { homedir } from 'node:os'
54
+ import { join, resolve as resolvePath } from 'node:path'
53
55
 
54
56
  export const AGENT_CATALOG_PROTOCOL_VERSION = 1
55
57
  export const DEFAULT_AGENT_CATALOG_COMMAND = 'pi-agent-catalog'
@@ -210,6 +212,27 @@ export function resolveCatalogCommand(env = process.env) {
210
212
  return parseCommandSpec(spec)
211
213
  }
212
214
 
215
+ function installedPiCatalogCommand(request, env) {
216
+ if (request.harness !== 'pi' || env?.[AGENT_CATALOG_COMMAND_ENV]?.trim()) return null
217
+ const configuredRoot = request.userRoot || env?.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent')
218
+ const root = configuredRoot === '~' ? homedir()
219
+ : configuredRoot.startsWith('~/') ? join(homedir(), configuredRoot.slice(2)) : configuredRoot
220
+ for (const entry of [
221
+ ['pi-better-harness', 'bin', 'pi-agent-catalog.mjs'],
222
+ ['pi-better-subagents', 'agent-catalog.mjs'],
223
+ ]) {
224
+ const script = resolvePath(root, 'npm', 'node_modules', ...entry)
225
+ try {
226
+ if (statSync(script).isFile()) {
227
+ return { executable: process.execPath, args: [script], source: 'pi-installed' }
228
+ }
229
+ } catch (error) {
230
+ if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error
231
+ }
232
+ }
233
+ return null
234
+ }
235
+
213
236
  function normalizeAvailable(value, label = 'available') {
214
237
  if (value === undefined) return { ok: true, available: [] }
215
238
  if (!Array.isArray(value)) {
@@ -864,17 +887,27 @@ export function resolveAgentCatalog({
864
887
  }
865
888
  const commandResult = resolveCatalogCommand(env)
866
889
  if (!commandResult.ok) return commandResult
867
- const { command } = commandResult
890
+ let { command } = commandResult
891
+ const invoke = () => runner({
892
+ executable: command.executable,
893
+ args: command.args,
894
+ input: `${JSON.stringify(request)}\n`,
895
+ timeoutMs,
896
+ env,
897
+ })
868
898
 
869
899
  let run
870
900
  try {
871
- run = runner({
872
- executable: command.executable,
873
- args: command.args,
874
- input: `${JSON.stringify(request)}\n`,
875
- timeoutMs,
876
- env,
877
- })
901
+ run = invoke()
902
+ // Only a missing default command permits installed-package lookup. An
903
+ // explicit choice or a resolver that ran and failed stays authoritative.
904
+ if (run?.error?.code === 'ENOENT') {
905
+ const installed = installedPiCatalogCommand(request, env)
906
+ if (installed) {
907
+ command = installed
908
+ run = invoke()
909
+ }
910
+ }
878
911
  } catch (error) {
879
912
  return blocked(
880
913
  AGENT_CATALOG_BLOCK_CODES.COMMAND_UNAVAILABLE,
@@ -14,4 +14,4 @@ When no supported native question tool is advertised, concise free-text input is
14
14
 
15
15
  Model discovery and catalog persistence remain separate from question planning. Current-turn tool availability is never inferred from model or harness configuration. Source-tree imports outside `skills/engineering` are unsupported until an installation-aware adapter entrypoint exists; consumers must not copy the runtime to work around that boundary.
16
16
 
17
- `agent-catalog.mjs` is the consumer bridge to the harness-owned agent catalog: one versioned JSON request on stdin (`version`, `harness`, `cwd`, `available`, `foregroundModel`, `fallbackToForeground`, `launchCapabilities`, `hostPreferences`, `overrides`, `tiers`, …) and one JSON response on stdout with four worker slots. It resolves the resolver command from `PI_AGENT_CATALOG_COMMAND` (a JSON argv array, or one bare executable token) or defaults to `pi-agent-catalog` on PATH, runs it with no shell, bounds its output and runtime, and validates the response. Those host fields are validated and forwarded unchanged — nothing is inferred or completed here, so an unstated launch control or tier stays unstated. A missing, broken, or declining resolver is a reported block; the bridge never falls back to a skill-owned model ladder and never installs anything. `discover-models.mjs` and `model-catalog.mjs` remain for consumers that still import them and are no longer part of model-slot selection.
17
+ `agent-catalog.mjs` is the consumer bridge to the harness-owned agent catalog: one versioned JSON request on stdin (`version`, `harness`, `cwd`, `available`, `foregroundModel`, `fallbackToForeground`, `launchCapabilities`, `hostPreferences`, `overrides`, `tiers`, …) and one JSON response on stdout with four worker slots. It resolves the resolver command from `PI_AGENT_CATALOG_COMMAND` (a JSON argv array, or one bare executable token) or defaults to `pi-agent-catalog` on PATH. For Pi only, when that default command is missing (`ENOENT`), it checks the installed `pi-better-harness` then standalone `pi-better-subagents` catalog under `<agent-dir>/npm/node_modules` and invokes the first installed entrypoint through the current Node executable. The agent directory is the request's `userRoot`, then `PI_CODING_AGENT_DIR`, then `~/.pi/agent`. Explicit commands and resolvers that execute but fail remain authoritative; there is no project-checkout search or second resolver after a catalog failure. The bridge runs with no shell, bounds its output and runtime, and validates the response. Those host fields are validated and forwarded unchanged — nothing is inferred or completed here, so an unstated launch control or tier stays unstated. A missing, broken, or declining resolver is a reported block; the bridge never falls back to a skill-owned model ladder and never installs anything. `discover-models.mjs` and `model-catalog.mjs` remain for consumers that still import them and are no longer part of model-slot selection.
@@ -8,7 +8,7 @@ dependencies:
8
8
  - better-review
9
9
  - golden-path
10
10
  - harness-runtime
11
- release-version: 0.48.1
11
+ release-version: 0.49.1
12
12
  ---
13
13
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
14
14
  # Resolve issues
@@ -83,6 +83,7 @@ Read each procedure right before its stage; never substitute your own.
83
83
  | Implementation loop and opening each PR | [references/implementation.md](references/implementation.md) |
84
84
  | Read-only warehouse canary | [references/canary.md](references/canary.md) |
85
85
  | Owned workspaces: plan, prepare, cleanup, recover, inventory | [references/workspaces.md](references/workspaces.md) |
86
+ | Daily resource retention: enrollment, age tiers, preview, registration, apply | [references/retention.md](references/retention.md) |
86
87
  | Independent review | [references/review.md](references/review.md) |
87
88
  | Routing small problems; posting them at the end | [references/dropbox.md](references/dropbox.md) |
88
89
  | CI, queue, and merge | [references/ci.md](references/ci.md) |
@@ -143,7 +144,8 @@ Treat a missing or unreadable result as incomplete; resume a dead spawn once in
143
144
 
144
145
  Follow [preflight.md](references/preflight.md):
145
146
 
146
- 0. **Ready label:** resume the spec's run if one exists; run `ready-check.mjs`;
147
+ 0. **Retention and ready label:** enroll this repository's daily resource cleanup
148
+ through the persistent installed skill; resume the spec's run if one exists; run `ready-check.mjs`;
147
149
  stop on an `unreadable` outcome; ask at step 6 on `unlabeled` or a `missing` compaction
148
150
  hook (`install-hooks.mjs --check`; shortcut: warn).
149
151
  1. **Model slots:** record the fast-path fills without asking; the models and
@@ -3,7 +3,21 @@
3
3
  Run these steps in order, in every run, including a one-unit run. Ask nothing
4
4
  until step 6.
5
5
 
6
- ## 0. Ready label
6
+ ## 0. Repository retention and ready label
7
+
8
+ Enroll this repository's daily tiered retention through the installed skill copy:
9
+
10
+ ```bash
11
+ node <skill-base-dir>/scripts/daily-cleanup.mjs install --repo <canonical-repo-root>
12
+ ```
13
+
14
+ Repeat on each invocation to refresh the same job, never discover sibling projects.
15
+ Use a persistent installed skill path, not a temporary worktree. Report an enrollment
16
+ failure as "daily cleanup not enabled" and continue the issue workflow. The daily
17
+ job cleans only explicitly registered disposable resources; it preserves run history.
18
+ See [retention.md](retention.md) for age tiers, registration and uninstall. Register
19
+ owned reconstructable resources when they are created and update their activity before
20
+ reuse; never turn an inventory guess into deletion authority.
7
21
 
8
22
  **One run per spec.** Before anything else, find the spec's run:
9
23
 
@@ -52,8 +66,8 @@ The script exits 0 whenever it ran (2 if it could not); read `outcome` in its JS
52
66
  planned from an issue that cannot be read.
53
67
  - **Exit 2** (the script could not run): fix the issue reference and rerun.
54
68
 
55
- Skip this step for a local or pasted spec. Count only GitHub's native
56
- sub-issues, never a checklist.
69
+ Skip only the ready-label check for a local or pasted spec; repository retention
70
+ enrollment still runs. Count only GitHub's native sub-issues, never a checklist.
57
71
 
58
72
  ### Compaction hook
59
73
 
@@ -0,0 +1,162 @@
1
+ # Daily resource retention
2
+
3
+ Keep run history and reclaim explicitly owned, reconstructable generated resources.
4
+ Enrollment belongs to the repository where `resolve-issues` or `rush-issues` is invoked;
5
+ it never discovers or enrolls sibling projects.
6
+
7
+ ## Enroll at preflight
8
+
9
+ Use the persistent installed skill copy and canonical main checkout:
10
+
11
+ ```bash
12
+ node <skill-base-dir>/scripts/daily-cleanup.mjs install --repo <repo-root>
13
+ ```
14
+
15
+ Repeat enrollment on each invocation to refresh the same job, including after a
16
+ skill or Node update. The installer prefers the stable PATH alias for its current
17
+ Node runtime. The skill directory must remain available; a temporary checkout or
18
+ unpack directory is not an installation.
19
+
20
+ macOS runs a user LaunchAgent every 12 hours and at load. Linux uses a persistent
21
+ user systemd daily timer with boot catch-up. The scheduler must be available; it
22
+ does not wake a powered-off machine. Report an unsupported host or failed enrollment
23
+ as "daily cleanup not enabled" and continue the issue workflow. A saved job file
24
+ alone does not prove that the job is loaded.
25
+
26
+ ```bash
27
+ node <skill-base-dir>/scripts/daily-cleanup.mjs plan --repo <repo-root>
28
+ node <skill-base-dir>/scripts/daily-cleanup.mjs uninstall --repo <repo-root>
29
+ ```
30
+
31
+ ## Preserve records; register resources
32
+
33
+ Keep plans, source requirements, decisions, findings, results, review verdicts,
34
+ progress and retry history, checkpoints, Git metadata, unpublished work, required
35
+ evidence and credentials. A directory name or an old timestamp proves no authority.
36
+ Whole-workspace cleanup still follows [the delivered-unit lifecycle](workspaces.md#cleanup-after-delivery-before-finish).
37
+
38
+ The default age floors are seven full days for generated resources and 30 full
39
+ days for explicitly disposable raw artifacts. Recorded activity authorizes the age
40
+ calculation; newer filesystem writes can only postpone removal. Eligible targets
41
+ are ranked by measured allocation, largest first. Shared blocks, hardlinks and local
42
+ filesystem snapshots mean allocation removed is not necessarily free space gained.
43
+ Report the two measurements separately. Removing OS backup snapshots is a separate,
44
+ explicitly authorized operation, never part of this scheduler.
45
+
46
+ The manifest `<repo>/.resolve-issues/retention.json` binds each resource to its
47
+ run/unit, exact path and filesystem identity, activity, reconstruction recipe and
48
+ explicit registration. Register only paths already owned by the task plan. A
49
+ legacy path needs explicit ownership reconciliation first; inventory never adopts it.
50
+
51
+ Registration records inventory; it does not release an unfinished owner's resource
52
+ for deletion. Declare each generated resource's `retention` intent in the task plan
53
+ as described in [workspaces.md](workspaces.md#what-the-plan-records). Register the
54
+ ready declarations in one operation before worker admission:
55
+
56
+ ```bash
57
+ node <skill-base-dir>/scripts/retention.mjs register-owned \
58
+ --repo <repo-root> --run <absolute-run> --unit <unit-id> \
59
+ --last-used-at <current-ISO-timestamp> --apply --json
60
+ ```
61
+
62
+ Without `--apply`, this previews registration and writes nothing. The command
63
+ considers only `lifecycle.resources` and their retention intent; legacy top-level
64
+ resource lists require explicit reconciliation. It never discovers neighboring
65
+ paths. Exit 0 means complete coverage, 1 means deferred or uncovered resources,
66
+ and 2 means the call was refused. Record its registered, deferred and uncovered results.
67
+ Refresh activity before reuse and repeat registration for newly populated resources
68
+ after their producing worker has settled. Keep that worker's resource report with
69
+ its result. A refusal means the resource remains unregistered; a loaded daily job
70
+ does not mean that every generated environment is covered.
71
+
72
+ ```bash
73
+ node <skill-base-dir>/scripts/retention.mjs register \
74
+ --repo <repo-root> --run <absolute-run> --unit <unit-id> \
75
+ --path <absolute-generated-child> --kind generated \
76
+ --last-used-at <ISO-timestamp> --recipe '<reconstruction instructions>' --json
77
+ ```
78
+
79
+ A resource containing credentials, private configuration, unique scripts or required
80
+ proof is retained. Malformed required-evidence declarations also retain candidates;
81
+ fix the ownership/evidence record rather than ignoring it. Registration and every
82
+ apply pass check these boundaries. Explicitly optional evidence is not a required pin.
83
+
84
+ For an unfinished task, use `--release-owner` only after explicit resource release
85
+ has been authorized and its reconstruction inputs remain available. It releases the
86
+ resource, not the task or source. Re-registering before reuse withdraws that release;
87
+ an existing pin remains pinned.
88
+
89
+ ## Verify generated formats and rebuild inputs
90
+
91
+ Use `generic` for explicitly classified caches without a supported format. Its
92
+ conservative metadata and link checks remain in force. A supported generated format
93
+ can distinguish installed package source directories from the run's own source:
94
+
95
+ | Format | Positive proof | Retained reconstruction inputs |
96
+ | --- | --- | --- |
97
+ | `pnpm-install` | pnpm installation metadata and virtual store | `package.json`, `pnpm-lock.yaml` |
98
+ | `pnpm-store` | versioned content-addressed package store | `package.json`, `pnpm-lock.yaml` |
99
+ | `uv-venv` | virtual-environment configuration, interpreter and installed-package layout | `pyproject.toml`, `uv.lock` |
100
+ | `next-build` | Next.js build output markers | `package.json`, `pnpm-lock.yaml` |
101
+
102
+ Supply the format and actual input paths explicitly. The inputs must be canonical
103
+ regular files outside the disposable target. The registration records their identity
104
+ and content hashes; changed or uncertain inputs require reassessment. Format proof
105
+ does not exempt credentials, nested Git, run metadata, required evidence or ownership
106
+ checks. Links in a verified generated installation are references: removal unlinks
107
+ them and preserves their destinations.
108
+
109
+ ```bash
110
+ node <skill-base-dir>/scripts/retention.mjs register \
111
+ --repo <repo-root> --run <absolute-run> --unit <unit-id> \
112
+ --path <workspace>/node_modules --kind generated --format pnpm-install \
113
+ --input <workspace>/package.json --input <workspace>/pnpm-lock.yaml \
114
+ --last-used-at <ISO-timestamp> --recipe 'pnpm install --frozen-lockfile' --json
115
+ ```
116
+
117
+ ## Check before reuse
118
+
119
+ Before admitting a worker that needs a registered resource, inspect its state:
120
+
121
+ ```bash
122
+ node <skill-base-dir>/scripts/retention.mjs status \
123
+ --repo <repo-root> --run <absolute-run> --unit <unit-id> --json
124
+ ```
125
+
126
+ Read `rebuildRequired`, the reason and retained recipe. A pin or protected credential
127
+ can prevent deletion without making a valid installation need reconstruction.
128
+ Readiness and cleanup eligibility are separate. A missing tree, changed
129
+ reconstruction inputs or a partial installation is not ready merely because its
130
+ parent directory exists. This includes environments left with protected credential
131
+ or configuration fragments after an explicitly authorized manual cleanup.
132
+
133
+ An unregistered or legacy resource has no readiness proof from this command. Read
134
+ its prior cleanup receipts and verify the repository's install/build contract before
135
+ reuse; do not infer readiness from an empty status result.
136
+
137
+ Reconstruct with the repository's retained lockfile and existing install/build
138
+ contract before continuing. Preserve protected files at their original paths; do
139
+ not run a clear/reset command that would discard them. Do not execute an arbitrary
140
+ recipe from an untrusted manifest. Verify the reconstructed format and then
141
+ re-register its new identity and current activity without `--release-owner`.
142
+ Until those steps pass, the dependent worker waits and the task stays unfinished.
143
+
144
+ ## Preview, apply and recover
145
+
146
+ ```bash
147
+ node <skill-base-dir>/scripts/retention.mjs plan --repo <repo-root> --json
148
+ node <skill-base-dir>/scripts/retention.mjs apply --repo <repo-root> --apply --json
149
+ node <skill-base-dir>/scripts/retention.mjs recover --repo <repo-root> --json
150
+ ```
151
+
152
+ Apply locks retention and rechecks owner activity, claims, required evidence, source,
153
+ filesystem identity and process use before each removal. Receipts live outside the
154
+ target under `.resolve-issues/retention-receipts`. A partial removal is a failure;
155
+ preserve both the original failure and cleanup errors.
156
+
157
+ Recovery is read-only by default. `recover --apply` may clear only a lock whose
158
+ record proves its owner is dead on this host. Live, foreign, unreadable, legacy or
159
+ ambiguous locks stay. The daily apply path can make the same proven-dead-owner
160
+ recovery. It never breaks a lock by age. An interrupted receipt or quarantined tree
161
+ remains visible for reconciliation; releasing its dead lock does not declare its
162
+ cleanup complete or remove the quarantined data.
@@ -17,7 +17,9 @@ checkout) and `targetBranch`. A unit already records `workspace`, `branch` and
17
17
  "baseSha": "<exact SHA>", "identity": "<returned by the helper>" },
18
18
  "resources": [ { "role": "review|scratch|tools", "kind": "directory|clone|worktree",
19
19
  "path": "<absolute>", "disposable": true,
20
- "state": "preparing|ready", "identity": "<returned by the helper>" } ],
20
+ "state": "preparing|ready", "identity": "<returned by the helper>",
21
+ "retention": { "kind": "generated", "format": "generic|pnpm-install|pnpm-store|uv-venv|next-build",
22
+ "recipe": "<retained rebuild command>", "inputs": ["<absolute source input>"] } } ],
21
23
  "cleanup": { "state": "pending|applying|complete|retained",
22
24
  "headSha": "<the unit's headSha>", "reason": "<retained only>" } }
23
25
  ```
@@ -75,11 +77,31 @@ Do not admit another worker while that owner's cleanup is `applying`; the
75
77
  3. Persist the returned `nextLifecycle` on the unit **before** spawning the
76
78
  worker, and give the worker that workspace path and only the resources it
77
79
  needs. Resources are recorded before they are used.
78
- 4. Reuse it. Retries, fix rounds, and every review round run in the same
79
- workspace and the same review clone; a later prepare verifies identity,
80
- branch, and base instead of recreating. Never reset, replace, or allocate a
81
- second tree for one attempt, and plan a private tool cache or scratch copy
82
- only when the work needs one.
80
+ 4. Each disposable generated resource carries its explicit `retention` intent:
81
+ kind, supported format, reconstruction recipe and retained source input paths
82
+ ([retention.md](retention.md#verify-generated-formats-and-rebuild-inputs)).
83
+ After persisting the ready lifecycle and before worker admission, run:
84
+
85
+ ```bash
86
+ node <skill-base-dir>/scripts/retention.mjs register-owned \
87
+ --repo <repo-root> --run <run> --unit <unit> \
88
+ --last-used-at <current-ISO-timestamp> --apply --json
89
+ ```
90
+
91
+ The command considers only declared resources. Record its registered, deferred
92
+ and uncovered results; report a refusal rather than claiming full daily coverage.
93
+ An empty typed installation can be deferred while its producing worker installs
94
+ it. After that worker settles and its handle is cleared, repeat registration
95
+ for the populated resource. Registration grants no early release of unfinished
96
+ work. Whole workspaces, credential directories, unique scripts and required
97
+ evidence stay outside disposable declarations.
98
+ 5. Before reusing a registered resource, run the read-only
99
+ [rebuild status check](retention.md#check-before-reuse). Rebuild a missing or
100
+ partial installation with the retained repository contract before admitting its
101
+ dependent worker; directory existence is not readiness. Refresh registration and
102
+ activity without releasing the owner after reconstruction. Retries, fix rounds
103
+ and review rounds reuse the same workspace and review clone. A later prepare
104
+ verifies identity, branch and base; it does not reset or replace them.
83
105
 
84
106
  `kind`: a linked `worktree` where a plain checkout is enough; an independent
85
107
  `clone` when the first Git-mutating worker runs in a sandbox that cannot write a
@@ -126,8 +148,10 @@ It removes nothing else: no ignored-file stripping, no pruning, and no
126
148
  answer retains everything, whole. Keep, never clean: a blocked, cancelled,
127
149
  pending, or supervised merge-ready unit's environment, whatever its timestamp; a
128
150
  tree a worker may still use; a tree whose ownership or delivery cannot be proved.
129
- No cleanup runs by age, idle time, or a name pattern, and a legacy
130
- `*-workspaces` directory is never adopted or deleted.
151
+ Whole-workspace cleanup never runs by age, idle time, or a name pattern, and a legacy
152
+ `*-workspaces` directory is never adopted or deleted. Separate [resource retention](retention.md)
153
+ uses explicit registrations and age thresholds for reconstructable children while keeping
154
+ the workspace, Git history and progress records.
131
155
 
132
156
  ## Evidence and handoff
133
157
 
@@ -149,8 +173,14 @@ On startup, before scheduling, read only:
149
173
  node <skill-base-dir>/scripts/cleanup-runs.mjs recover --repo <repo-root> --json
150
174
  ```
151
175
 
152
- It lists unfinished recorded operations — a `preparing` workspace, an `applying`
153
- cleanup, a lock, an orphaned worktree — in every run regardless of age. It
176
+ Also inspect resource-retention recovery before admission:
177
+
178
+ ```bash
179
+ node <skill-base-dir>/scripts/retention.mjs recover --repo <repo-root> --json
180
+ ```
181
+
182
+ Workspace recovery lists unfinished recorded operations — a `preparing` workspace,
183
+ an `applying` cleanup, a lock, an orphaned worktree — in every run regardless of age. It
154
184
  activates no workflow and cleans nothing by itself: continue the plan, then
155
185
  prepare or clean what it names and persist the result.
156
186