@1aboveio/engineering-skills 0.0.0-stage → 0.1.0
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/README.md +28 -2
- package/package.json +33 -4
- package/skills/better-review/LICENSE +3 -0
- package/skills/better-review/SKILL.md +249 -0
- package/skills/better-review/agents/openai.yaml +9 -0
- package/skills/better-review/references/domain-hazards.md +53 -0
- package/skills/better-review/references/passes.md +147 -0
- package/skills/better-review/references/result.md +151 -0
- package/skills/better-review/release-check.mjs +93 -0
- package/skills/better-review/scripts/pr-context.mjs +212 -0
- package/skills/better-review/scripts/pr-context.test.mjs +168 -0
- package/skills/better-review/scripts/rereview-scope.mjs +503 -0
- package/skills/better-review/scripts/rereview-scope.test.mjs +587 -0
- package/skills/better-review/scripts/scan-diff.mjs +365 -0
- package/skills/better-review/scripts/scan-diff.test.mjs +414 -0
- package/skills/better-review/scripts/vendor-sync.test.mjs +96 -0
- package/skills/e2e-test/LICENSE +3 -0
- package/skills/e2e-test/SKILL.md +98 -0
- package/skills/e2e-test/assets/ci-gates.cloudbuild.yaml +24 -0
- package/skills/e2e-test/references/authoring/auth-flows.md +159 -0
- package/skills/e2e-test/references/authoring/playwright-config.md +73 -0
- package/skills/e2e-test/references/authoring/playwright-patterns.md +144 -0
- package/skills/e2e-test/references/ci-integration.md +25 -0
- package/skills/e2e-test/references/ci-playwright-container.md +290 -0
- package/skills/e2e-test/references/presentation-sweep.md +104 -0
- package/skills/e2e-test/references/reviewing.md +41 -0
- package/skills/e2e-test/references/route-manifest.md +51 -0
- package/skills/e2e-test/release-check.mjs +93 -0
- package/skills/e2e-test/scripts/detect-routes-nextjs.mjs +200 -0
- package/skills/e2e-test/scripts/presentation-checks.mjs +171 -0
- package/skills/e2e-test/scripts/presentation-checks.test.mjs +106 -0
- package/skills/e2e-test/scripts/presentation-perceivability.mjs +179 -0
- package/skills/e2e-test/scripts/presentation-perceivability.test.mjs +117 -0
- package/skills/e2e-test/scripts/presentation-reachability.mjs +154 -0
- package/skills/e2e-test/scripts/presentation-reachability.test.mjs +69 -0
- package/skills/e2e-test/scripts/presentation-render-health.mjs +141 -0
- package/skills/e2e-test/scripts/presentation-render-health.test.mjs +98 -0
- package/skills/e2e-test/scripts/presentation-sweep.mjs +147 -0
- package/skills/e2e-test/scripts/presentation-sweep.test.mjs +71 -0
- package/skills/e2e-test/scripts/presentation-temporal.mjs +127 -0
- package/skills/e2e-test/scripts/presentation-temporal.test.mjs +59 -0
- package/skills/e2e-test/scripts/project-route-manifest.mjs +82 -0
- package/skills/e2e-test/scripts/project-route-manifest.test.mjs +76 -0
- package/skills/e2e-test/scripts/validate-manifest.mjs +106 -0
- package/skills/engineering-runtime/LICENSE +3 -0
- package/skills/engineering-runtime/SKILL.md +11 -0
- package/skills/engineering-runtime/agents/openai.yaml +6 -0
- package/skills/engineering-runtime/coherence/workflow.json +597 -0
- package/skills/engineering-runtime/engineering-runtime.test.mjs +68 -0
- package/skills/engineering-runtime/release-check.mjs +93 -0
- package/skills/engineering-runtime/scripts/exact-head-artifact.mjs +131 -0
- package/skills/engineering-runtime/scripts/head-check-set.mjs +398 -0
- package/skills/engineering-runtime/scripts/invocation-policy.mjs +187 -0
- package/skills/engineering-runtime/scripts/invocation-policy.test.mjs +95 -0
- package/skills/engineering-runtime/scripts/main-module.mjs +79 -0
- package/skills/engineering-runtime/scripts/main-module.test.mjs +288 -0
- package/skills/engineering-runtime/scripts/mergify-yaml.mjs +11 -0
- package/skills/engineering-runtime/scripts/package-lock.json +43 -0
- package/skills/engineering-runtime/scripts/package.json +10 -0
- package/skills/engineering-runtime/scripts/required-check-plan.mjs +223 -0
- package/skills/engineering-runtime/scripts/required-check-plan.test.mjs +96 -0
- package/skills/engineering-runtime/scripts/review-completion.mjs +56 -0
- package/skills/engineering-runtime/scripts/workflow-coherence.mjs +595 -0
- package/skills/engineering-runtime/scripts/workflow-policy.mjs +189 -0
- package/skills/engineering-runtime/scripts/yaml-mapping.mjs +18 -0
- package/skills/ensure-coverage/LICENSE +3 -0
- package/skills/ensure-coverage/SKILL.md +129 -0
- package/skills/ensure-coverage/references/breadth/coverage-ledger.md +92 -0
- package/skills/ensure-coverage/references/breadth/inventory-contract.md +85 -0
- package/skills/ensure-coverage/references/breadth/surface-baseline.md +44 -0
- package/skills/ensure-coverage/references/breadth/surface-discovery.md +16 -0
- package/skills/ensure-coverage/references/depth/characterization.md +68 -0
- package/skills/ensure-coverage/references/depth/coverage.config.example.json +19 -0
- package/skills/ensure-coverage/references/depth/grading.md +35 -0
- package/skills/ensure-coverage/references/depth/mock-policy.md +57 -0
- package/skills/ensure-coverage/references/depth/test-smells.md +39 -0
- package/skills/ensure-coverage/references/enforcement/ci-contract.md +44 -0
- package/skills/ensure-coverage/references/examples/coverage-ledger.md +110 -0
- package/skills/ensure-coverage/references/examples/refund-flow.md +35 -0
- package/skills/ensure-coverage/references/presentation/axis.md +64 -0
- package/skills/ensure-coverage/references/process/audit-mode.md +27 -0
- package/skills/ensure-coverage/references/process/output-template.md +139 -0
- package/skills/ensure-coverage/references/process/test-strategy.md +56 -0
- package/skills/ensure-coverage/release-check.mjs +93 -0
- package/skills/ensure-coverage/schemas/coverage-config.schema.json +67 -0
- package/skills/ensure-coverage/schemas/coverage-file.schema.json +140 -0
- package/skills/ensure-coverage/scripts/README.md +99 -0
- package/skills/ensure-coverage/scripts/adapters/nextjs-inventory.mjs +182 -0
- package/skills/ensure-coverage/scripts/adapters/nextjs-inventory.test.mjs +96 -0
- package/skills/ensure-coverage/scripts/check-quarantine-expiry.mjs +105 -0
- package/skills/ensure-coverage/scripts/check-quarantine-expiry.test.mjs +47 -0
- package/skills/ensure-coverage/scripts/ci-audit.mjs +137 -0
- package/skills/ensure-coverage/scripts/ci-audit.test.mjs +86 -0
- package/skills/ensure-coverage/scripts/coverage-ledger.mjs +674 -0
- package/skills/ensure-coverage/scripts/coverage-ledger.test.mjs +447 -0
- package/skills/ensure-coverage/scripts/design-parity.mjs +591 -0
- package/skills/ensure-coverage/scripts/design-parity.test.mjs +552 -0
- package/skills/ensure-coverage/scripts/lint-tests.mjs +282 -0
- package/skills/ensure-coverage/scripts/lint-tests.test.mjs +289 -0
- package/skills/ensure-coverage/scripts/mock-policy-config.mjs +176 -0
- package/skills/ensure-coverage/scripts/mock-policy-config.test.mjs +119 -0
- package/skills/ensure-coverage/scripts/package.json +19 -0
- package/skills/golden-path/LICENSE +3 -0
- package/skills/golden-path/SKILL.md +230 -0
- package/skills/golden-path/agents/openai.yaml +3 -0
- package/skills/golden-path/assets/golden-paths.example.json +57 -0
- package/skills/golden-path/references/contract.md +239 -0
- package/skills/golden-path/references/migration.md +111 -0
- package/skills/golden-path/release-check.mjs +93 -0
- package/skills/golden-path/scripts/golden-path-core.mjs +1779 -0
- package/skills/golden-path/scripts/golden-path.mjs +6 -0
- package/skills/golden-path/scripts/golden-path.test.mjs +1457 -0
- package/skills/harness-runtime/LICENSE +3 -0
- package/skills/harness-runtime/SKILL.md +19 -0
- package/skills/harness-runtime/agents/openai.yaml +6 -0
- package/skills/harness-runtime/bin/discover-models.mjs +4 -0
- package/skills/harness-runtime/bin/model-catalog.mjs +4 -0
- package/skills/harness-runtime/contracts.md +15 -0
- package/skills/harness-runtime/discover-models.mjs +392 -0
- package/skills/harness-runtime/discover-models.test.mjs +363 -0
- package/skills/harness-runtime/fixtures/native-question-schemas.json +33 -0
- package/skills/harness-runtime/fixtures/question-responses.json +54 -0
- package/skills/harness-runtime/harness-runtime.test.mjs +967 -0
- package/skills/harness-runtime/index.mjs +767 -0
- package/skills/harness-runtime/model-catalog-seed.test.mjs +829 -0
- package/skills/harness-runtime/model-catalog.mjs +787 -0
- package/skills/harness-runtime/model-catalog.test.mjs +366 -0
- package/skills/harness-runtime/native-question-contracts.md +37 -0
- package/skills/harness-runtime/references/model-catalog-seed.json +408 -0
- package/skills/harness-runtime/references/model-catalog.md +57 -0
- package/skills/harness-runtime/release-check.mjs +93 -0
- package/skills/resolve-issues/LICENSE +3 -0
- package/skills/resolve-issues/SKILL.md +250 -0
- package/skills/resolve-issues/agents/openai.yaml +9 -0
- package/skills/resolve-issues/plugin-hooks.json +17 -0
- package/skills/resolve-issues/references/canary.md +28 -0
- package/skills/resolve-issues/references/ci.md +105 -0
- package/skills/resolve-issues/references/done.md +25 -0
- package/skills/resolve-issues/references/dropbox.md +90 -0
- package/skills/resolve-issues/references/expire.md +318 -0
- package/skills/resolve-issues/references/exploration.md +202 -0
- package/skills/resolve-issues/references/implementation.md +303 -0
- package/skills/resolve-issues/references/preflight.md +445 -0
- package/skills/resolve-issues/references/review.md +228 -0
- package/skills/resolve-issues/references/shared-modules.md +44 -0
- package/skills/resolve-issues/references/task-plan.md +264 -0
- package/skills/resolve-issues/release-check.mjs +93 -0
- package/skills/resolve-issues/scripts/cleanup-runs.mjs +364 -0
- package/skills/resolve-issues/scripts/cleanup-runs.test.mjs +280 -0
- package/skills/resolve-issues/scripts/discover-models.mjs +9 -0
- package/skills/resolve-issues/scripts/dropbox.mjs +473 -0
- package/skills/resolve-issues/scripts/dropbox.test.mjs +346 -0
- package/skills/resolve-issues/scripts/findings-reuse.mjs +98 -0
- package/skills/resolve-issues/scripts/findings-reuse.test.mjs +88 -0
- package/skills/resolve-issues/scripts/github-reviews.mjs +384 -0
- package/skills/resolve-issues/scripts/github-reviews.test.mjs +264 -0
- package/skills/resolve-issues/scripts/install-hooks.mjs +135 -0
- package/skills/resolve-issues/scripts/install-hooks.test.mjs +79 -0
- package/skills/resolve-issues/scripts/issue-tree.mjs +162 -0
- package/skills/resolve-issues/scripts/issue-tree.test.mjs +107 -0
- package/skills/resolve-issues/scripts/manual-invocation.test.mjs +14 -0
- package/skills/resolve-issues/scripts/model-catalog.mjs +9 -0
- package/skills/resolve-issues/scripts/next-actions-capacity.test.mjs +149 -0
- package/skills/resolve-issues/scripts/next-actions.mjs +856 -0
- package/skills/resolve-issues/scripts/next-actions.test.mjs +915 -0
- package/skills/resolve-issues/scripts/plan-sync.mjs +269 -0
- package/skills/resolve-issues/scripts/plan-sync.test.mjs +156 -0
- package/skills/resolve-issues/scripts/preflight-models.mjs +736 -0
- package/skills/resolve-issues/scripts/preflight-models.test.mjs +448 -0
- package/skills/resolve-issues/scripts/ready-check.mjs +185 -0
- package/skills/resolve-issues/scripts/ready-check.test.mjs +217 -0
- package/skills/resolve-issues/scripts/rehydrate.mjs +98 -0
- package/skills/resolve-issues/scripts/rehydrate.test.mjs +91 -0
- package/skills/resolve-issues/scripts/review-verdict.mjs +509 -0
- package/skills/resolve-issues/scripts/review-verdict.test.mjs +1060 -0
- package/skills/resolve-issues/scripts/size-check.mjs +492 -0
- package/skills/resolve-issues/scripts/size-check.test.mjs +458 -0
- package/skills/resolve-release/LICENSE +3 -0
- package/skills/resolve-release/SKILL.md +215 -0
- package/skills/resolve-release/agents/openai.yaml +8 -0
- package/skills/resolve-release/flows/cloud-run-canary.md +13 -0
- package/skills/resolve-release/flows/cloud-run.md +7 -0
- package/skills/resolve-release/flows/root-tag-npm.md +13 -0
- package/skills/resolve-release/flows/workspace-npm.md +22 -0
- package/skills/resolve-release/references/canary.md +51 -0
- package/skills/resolve-release/references/candidate.md +41 -0
- package/skills/resolve-release/references/cut.md +131 -0
- package/skills/resolve-release/references/dark-launch.md +66 -0
- package/skills/resolve-release/references/flows.md +150 -0
- package/skills/resolve-release/references/preflight.md +154 -0
- package/skills/resolve-release/references/prepared-metadata.md +260 -0
- package/skills/resolve-release/references/promotion.md +82 -0
- package/skills/resolve-release/references/publish.md +232 -0
- package/skills/resolve-release/references/workspace-npm.md +103 -0
- package/skills/resolve-release/release-check.mjs +93 -0
- package/skills/resolve-release/scripts/apply.mjs +212 -0
- package/skills/resolve-release/scripts/apply.test.mjs +99 -0
- package/skills/resolve-release/scripts/dark-flags.mjs +134 -0
- package/skills/resolve-release/scripts/dark-flags.test.mjs +100 -0
- package/skills/resolve-release/scripts/flow.mjs +500 -0
- package/skills/resolve-release/scripts/flow.test.mjs +340 -0
- package/skills/resolve-release/scripts/green-head.mjs +231 -0
- package/skills/resolve-release/scripts/green-head.test.mjs +101 -0
- package/skills/resolve-release/scripts/npm-version-absence.mjs +138 -0
- package/skills/resolve-release/scripts/npm-version-absence.test.mjs +426 -0
- package/skills/resolve-release/scripts/plan-npm.test.mjs +659 -0
- package/skills/resolve-release/scripts/plan-toml-boundary.test.mjs +317 -0
- package/skills/resolve-release/scripts/plan-uv.test.mjs +291 -0
- package/skills/resolve-release/scripts/plan.mjs +806 -0
- package/skills/resolve-release/scripts/plan.test.mjs +428 -0
- package/skills/rush-issues/LICENSE +3 -0
- package/skills/rush-issues/SKILL.md +58 -0
- package/skills/rush-issues/agents/openai.yaml +8 -0
- package/skills/rush-issues/rehydrate.mjs +10 -0
- package/skills/rush-issues/release-check.mjs +93 -0
- package/skills/rush-release/LICENSE +3 -0
- package/skills/rush-release/SKILL.md +35 -0
- package/skills/rush-release/agents/openai.yaml +8 -0
- package/skills/rush-release/release-check.mjs +93 -0
- package/skills/test-quality/LICENSE +3 -0
- package/skills/test-quality/SKILL.md +79 -0
- package/skills/test-quality/references/audit.md +80 -0
- package/skills/test-quality/references/lint.md +24 -0
- package/skills/test-quality/references/principles.md +143 -0
- package/skills/test-quality/references/testing-conventions.md +9 -0
- package/skills/test-quality/release-check.mjs +93 -0
- package/skills/test-quality/scripts/lint-tests.mjs +574 -0
- package/skills/test-quality/scripts/lint-tests.test.mjs +591 -0
- package/skills/test-quality/scripts/mock-policy-config.mjs +176 -0
- package/skills/test-quality/scripts/mock-policy-config.test.mjs +119 -0
- package/skills/test-quality/scripts/persist-conventions-core.mjs +116 -0
- package/skills/test-quality/scripts/persist-conventions.mjs +17 -0
- package/skills/test-quality/scripts/persist-conventions.test.mjs +104 -0
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: resolve-issues
|
|
3
|
+
description: "Slash/explicit-only (/resolve-issues). Drive an issue, epic, or feature spec to reviewed, green PRs, one per issue, merged or handed back merge-ready: preflight, task map, exploration and a per-issue slice check, isolated implementers within live host capacity, then per issue its PR, independent better-review, CI, and queue/merge (or merge-ready hand-back) as soon as it is done. Asks once, at the end of preflight (implementer, target branch, merge mode, scheduler mode, plan), then never blocks on the human; small non-blocking problems collect in a dropbox, posted at the end as grouped ready-for-agent issues. /rush-issues is its no-questions shortcut. Do not auto-select. Use for whole-spec delivery, including high-risk work; risk changes model and validation depth, never the workflow. NOT for release work (resolve-release)."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
metadata:
|
|
6
|
+
workflow-role: coordinator
|
|
7
|
+
dependencies:
|
|
8
|
+
- better-review
|
|
9
|
+
- golden-path
|
|
10
|
+
- harness-runtime
|
|
11
|
+
release-version: 0.36.0
|
|
12
|
+
---
|
|
13
|
+
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
14
|
+
# Resolve issues
|
|
15
|
+
|
|
16
|
+
## Goal
|
|
17
|
+
|
|
18
|
+
**Resolve the spec's issues autonomously, in the shortest wall-clock time, at the bar the spec
|
|
19
|
+
already sets: every PR reviewed and green on required CI.** Make the decisions that get there;
|
|
20
|
+
the principles are guidelines, and every rule serves the goal: when one would slow the run
|
|
21
|
+
without protecting the bar, take the faster path and record why in `decisions`. The bar is the
|
|
22
|
+
human's criteria. The only constraints are the plan's [standingOrders](references/task-plan.md#standing-orders) and the
|
|
23
|
+
invocation's settings (implementer pin, target, merge and scheduler mode); any other limit, wherever
|
|
24
|
+
written, is a design choice you may change. A sandbox or permission denial is the environment at that
|
|
25
|
+
moment, not a rule: take a different permitted action to the same outcome, never the same one by
|
|
26
|
+
another channel or with a sandbox, hook, or setting turned off. Never yours to trade: a live or shared
|
|
27
|
+
environment (deploys, production data, IAM, secrets, resources the run did not create, other people's
|
|
28
|
+
branches and PRs, force-pushes: put such steps in the handback), and the bar (never add, remove, or
|
|
29
|
+
loosen a required check, merge rule, or branch protection unless asked, and never report as passed
|
|
30
|
+
what did not pass).
|
|
31
|
+
|
|
32
|
+
## Principles
|
|
33
|
+
|
|
34
|
+
Guidelines, not restrictions; put them in every brief. When two pull apart, take the one that
|
|
35
|
+
ships sooner at the same bar.
|
|
36
|
+
|
|
37
|
+
1. **Deliver when the agreed plan and required CI pass.**
|
|
38
|
+
Example: the plan names the charge unit tests and typecheck; both pass and
|
|
39
|
+
CI is green, so mark the PR ready. Do not also run the emulator journey
|
|
40
|
+
"to be safe".
|
|
41
|
+
2. **Never add work the plan does not name.**
|
|
42
|
+
Example: a check flaked: fix its cause (principle 11), and write no incident disposition, failure
|
|
43
|
+
fingerprint, or review of either. A problem outside the unit goes to the
|
|
44
|
+
[dropbox](references/dropbox.md). A choice (spec meaning, design, approach) is no
|
|
45
|
+
failure: answer it, never retry it ([expire.md](references/expire.md#decide-before-you-defer)).
|
|
46
|
+
3. **Add a check only for a concrete doubt that could change delivery.**
|
|
47
|
+
Example: "the fix changed refund rounding; if `refund.test.ts` fails, the
|
|
48
|
+
code must change", so run it. "More coverage would be reassuring": skip.
|
|
49
|
+
4. **Reuse a passing result until what it tested changes.**
|
|
50
|
+
Example: a commit that only rewords its message keeps every result. A
|
|
51
|
+
fix to `refund.ts` reruns the refund tests, not the whole plan.
|
|
52
|
+
5. **Push early; CI is the full test.**
|
|
53
|
+
Example: push each fix to the draft PR once its focused tests pass,
|
|
54
|
+
without asking first and without running the full suite locally.
|
|
55
|
+
6. **Carry a HEAD pushed after a passing review; give every other new HEAD the tier `better-review`'s scope script picks.**
|
|
56
|
+
Example: a CI fix or a merge of main after a pass: `--carry`, no
|
|
57
|
+
reviewer. A P0/P1 fix: delta; one that rewrote most of the PR: full.
|
|
58
|
+
7. **Coordinate first.** On every completion notice, read fresh capacity and run `scripts/next-actions.mjs --run <run>`
|
|
59
|
+
with the [live capacity arguments](references/implementation.md#live-capacity); do everything it prints
|
|
60
|
+
before resuming your own work; keep a [heartbeat](references/expire.md#waits).
|
|
61
|
+
Example: mid-way through an emulator debug, a notice says `impl-1322`
|
|
62
|
+
finished; the script prints `start-review 1322` and `fill-slot 1323`, so
|
|
63
|
+
start both, then return to the debug. On a new invocation, call it first with `--resume`.
|
|
64
|
+
Only it decides the run is done: end a turn only when it prints nothing due, only `wait`, or `finish`.
|
|
65
|
+
8. **Run as much at once as the plan and live host capacity allow.** Start every `fill-slot` before your own work;
|
|
66
|
+
never hold a ready unit back; link a unit only to what its change needs.
|
|
67
|
+
Example: a slot is free while you debug CI: start the ready unit, then debug. Five slices need one helper: the first builds it, the rest depend on it.
|
|
68
|
+
9. **Record what remains once, in the issue that owns it.**
|
|
69
|
+
Example: the release device campaign is still to run, so add one comment
|
|
70
|
+
on the release issue and link it from the handback. Never report "device
|
|
71
|
+
tests passed" from a unit build.
|
|
72
|
+
10. **Never block on the human.** After the approval, take the [automatic answer](references/preflight.md#never-block-on-the-human)
|
|
73
|
+
wherever you could ask or wait, record it, and keep going; a later message changes course from there.
|
|
74
|
+
11. **Fix the root cause.** Find why a failure happens and fix that, in the plan or outside it ([expire.md](references/expire.md#infrastructure-failures));
|
|
75
|
+
never only its symptom (a blind retry, a longer timeout, a skip, a guessed fix sent to CI: reproduce a failed journey
|
|
76
|
+
with `proof.suite.local` first). Defer only a [human-only](references/expire.md#human-only) cause.
|
|
77
|
+
|
|
78
|
+
`/rush-issues` runs this workflow with every answer defaulted ([shortcut mode](references/preflight.md#shortcut-mode)).
|
|
79
|
+
|
|
80
|
+
**Bounds:** the harness times and stops workers · retry while cycles reach new lows; 2 without one,
|
|
81
|
+
then [expire.md](references/expire.md) (a fix cycle progresses only on a new low; a resume, when it adds work the PR needs; diagnostics and records never) · workers within [live host capacity](references/implementation.md#live-capacity), one local emulator, queued for device-only work
|
|
82
|
+
and non-CI emulator proof ([scheduling](references/implementation.md#scheduling); CI confirms, never debugs) · one PR per issue · every runnable unit in one run, in dependency order · blocking review hands back
|
|
83
|
+
after 2 fix rounds without a new low of open P0/P1 path rows; no fixed round cap.
|
|
84
|
+
|
|
85
|
+
```text
|
|
86
|
+
preflight: ready label -> model fills -> plan draft
|
|
87
|
+
-> exploration -> size check (only scope or an open question holds a unit, with a split)
|
|
88
|
+
-> one approval (implementer, target branch, merge mode, scheduler mode, plan)
|
|
89
|
+
-> schedule runnable units within live host capacity:
|
|
90
|
+
implement -> first coherent commit: draft PR (CI starts) once parents' PRs are open
|
|
91
|
+
(stack, chain) or merged (wait) -> validate -> self-review -> fix and re-validate
|
|
92
|
+
-> when a unit's code is done, for that unit:
|
|
93
|
+
rebase on its parent (stack, chain) or the target (wait)
|
|
94
|
+
-> independent review, while CI runs -> review-verdict.mjs decides:
|
|
95
|
+
`pass`: review passes (P2 goes to the dropbox, never fixed
|
|
96
|
+
here; P3 is skipped); `fix`: only its fixBrief (P0/P1),
|
|
97
|
+
push, re-review; `review-again`: review again
|
|
98
|
+
-> CI red: fix, push; after a passing review, carry it (no reviewer)
|
|
99
|
+
-> review passed and CI green on one HEAD: mark ready
|
|
100
|
+
-> autonomous: merge (through the queue; stack, chain: enqueue a line's deepest PR); supervised: hand back merge-ready
|
|
101
|
+
-> after a merge, optional: read-only warehouse canary on that commit
|
|
102
|
+
-> done: every PR merged (autonomous) or handed back merge-ready (supervised)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Read each procedure right before its stage; never substitute your own.
|
|
106
|
+
|
|
107
|
+
| Stage | Procedure |
|
|
108
|
+
|---|---|
|
|
109
|
+
| Preflight: ready label, models, plan draft, exploration, size check, approval; what any filed text may say | [references/preflight.md](references/preflight.md) ([Filed text](references/preflight.md#filed-text)) |
|
|
110
|
+
| Task plan shape and live board | [references/task-plan.md](references/task-plan.md) |
|
|
111
|
+
| Exploration (preflight step 4) | [references/exploration.md](references/exploration.md) |
|
|
112
|
+
| Implementation loop and opening each PR | [references/implementation.md](references/implementation.md) |
|
|
113
|
+
| Read-only warehouse canary | [references/canary.md](references/canary.md) |
|
|
114
|
+
| Independent review | [references/review.md](references/review.md) |
|
|
115
|
+
| Routing small problems; posting them at the end | [references/dropbox.md](references/dropbox.md) |
|
|
116
|
+
| CI, queue, and merge | [references/ci.md](references/ci.md) |
|
|
117
|
+
| Expiry and stuck units | [references/expire.md](references/expire.md) |
|
|
118
|
+
| Model catalog and leaf skills | [references/shared-modules.md](references/shared-modules.md) |
|
|
119
|
+
|
|
120
|
+
## Run rules
|
|
121
|
+
|
|
122
|
+
- **Scope.** Deliver the whole spec in one run ([preflight.md](references/preflight.md#one-run-for-the-whole-spec)),
|
|
123
|
+
one unit per open issue with no open sub-issue (a spec without issues is one unit); the issue tree is the only
|
|
124
|
+
scope record ([sync](references/task-plan.md#issue-tree-sync)). Split a unit by filing its split
|
|
125
|
+
([preflight.md](references/preflight.md#file-a-split)). On expiry, take the failure kind's response and continue. Mark a unit stopped by its
|
|
126
|
+
own failure or a human-only decision `blocked` with a [`blockedReason`](references/expire.md#reason-codes)
|
|
127
|
+
([live-capacity scheduler](references/implementation.md#live-capacity): `next-actions.mjs` reopens any other block), keep its workspace, ship the rest, and settle what is left
|
|
128
|
+
([Done](#done)); an infrastructure or external blocker becomes a tree issue the units wait on
|
|
129
|
+
([expire.md](references/expire.md#infrastructure-failures)); a unit that only waits on another unit is not
|
|
130
|
+
started (`pending`), never `blocked`; what stays blocked ends deferred on its owning issue, never done.
|
|
131
|
+
- **Your role.** Coordinate first ([principle 7](#principles)); between notices you may do bounded work
|
|
132
|
+
yourself: reproduce a failing browser or emulator journey, investigate an infrastructure failure, run a short
|
|
133
|
+
check. Leave code changes to workers so your attention stays on scheduling, and record each worker as the
|
|
134
|
+
unit's `workerKind` (`implement`, `fix`, `review`). Exploration continues the run's one explorer. After a context compaction, read this file in
|
|
135
|
+
full again before your next step: the summary keeps the run's state, not these rules. Fill
|
|
136
|
+
free slots before starting your own work, stay within [expire.md](references/expire.md)'s limit, and send
|
|
137
|
+
large output to files (read only the lines you need). Expect Pi's **Completions while busy: Steer active run**
|
|
138
|
+
(`/harness-settings`) so notices reach you while you work; when it is off, run `next-actions.mjs` with
|
|
139
|
+
[fresh capacity](references/implementation.md#live-capacity) before each new step of your own work.
|
|
140
|
+
- **The human.** Ask once, at the approval. Record every decision, correction, and scope change in
|
|
141
|
+
`decisions` at once, and each standing instruction in `standingOrders`; re-read the standing orders on
|
|
142
|
+
resume and before any push, enqueue, data write, or deletion. Default merge mode is `autonomous`.
|
|
143
|
+
- **Proof.** Treat producer reports as claims until the reviewer or CI checks them. A check that exits 0 needs no
|
|
144
|
+
further evidence. A unit owes coding acceptance only: its criteria at its `proof.level` plus the required CI
|
|
145
|
+
on its final HEAD. Integrated release acceptance (a device or system campaign the spec or repository assigns
|
|
146
|
+
to a release or campaign gate) runs at that gate, never per unit; the handback links its owning issue. Produce
|
|
147
|
+
no evidence documents; the plan, findings, and reviews are the only records.
|
|
148
|
+
- **Delivery.** A dependent starts on its parent's finished code. Stack its PR on the parent's (a GitHub-native
|
|
149
|
+
stack) under a live Mergify queue; chain it when the merge keeps commits; else open it once the parent merges. Live
|
|
150
|
+
steps are only the read-only warehouse canary (never blocks) and the isolated, run-owned resources
|
|
151
|
+
[preflight.md](references/preflight.md#never-block-on-the-human) allows.
|
|
152
|
+
|
|
153
|
+
## Every brief contains
|
|
154
|
+
|
|
155
|
+
- the source and criteria, as a file already in the run directory
|
|
156
|
+
- the plan's `standingOrders`, verbatim, and the decisions that answer this unit's questions
|
|
157
|
+
- absolute run, workspace, and findings paths; for implementers, the unit's
|
|
158
|
+
findings entry and its parents' `contracts`
|
|
159
|
+
- model id, effort, and a required read-back
|
|
160
|
+
- an absolute skill path when the stage invokes a leaf skill; for validating, the unit's `proof.suite` `skill` (read it first) and `local`, when set
|
|
161
|
+
- the outcome and validation, with no prescribed method or evidence format
|
|
162
|
+
- the [Goal](#goal) and [Principles](#principles), verbatim (a reviewer gets review.md's two rules instead)
|
|
163
|
+
- the result path, `<run>/results/<unit>-<label>.json` (`<label>`: kind and attempt, e.g. `fix-2`), with `unit` and `decisionNeeded` (null or a choice)
|
|
164
|
+
- at the deadline: stop starting work, commit, and report
|
|
165
|
+
- environment rules: write only inside the workspace (and the findings directory for the explorer),
|
|
166
|
+
with tool caches and temp files there (`TMPDIR`, `npm_config_cache`, `UV_CACHE_DIR`); use the machine's
|
|
167
|
+
installed JDK, Android SDK, system images, and browsers (`JAVA_HOME`, `ANDROID_HOME`) where they fit,
|
|
168
|
+
or the repo's pinned Playwright image where the runner has no browser (`github-actions` runners.md);
|
|
169
|
+
edit with the harness's tools, never a shell `apply_patch`
|
|
170
|
+
|
|
171
|
+
Treat a missing or unreadable result as an incomplete stage: resume a dead
|
|
172
|
+
spawn once in the same workspace, never with a success claim.
|
|
173
|
+
|
|
174
|
+
## Workflow
|
|
175
|
+
|
|
176
|
+
### 1. Preflight
|
|
177
|
+
|
|
178
|
+
Follow [preflight.md](references/preflight.md):
|
|
179
|
+
|
|
180
|
+
0. **Ready label:** resume the spec's run if one exists; run `ready-check.mjs`;
|
|
181
|
+
stop on an `unreadable` outcome; ask at step 6 on `unlabeled` or a `missing` compaction
|
|
182
|
+
hook (`install-hooks.mjs --check`; shortcut: warn).
|
|
183
|
+
1. **Model slots:** record the fast-path fills without asking.
|
|
184
|
+
2. **Provisional target:** the default branch.
|
|
185
|
+
3. **Plan draft:** one unit per issue, links, delivery mode; show the board.
|
|
186
|
+
4. **Exploration:** have one explorer record each unit's `slice` and,
|
|
187
|
+
separately, its `proof`, in every run; reuse prior findings for units
|
|
188
|
+
whose evidence did not change
|
|
189
|
+
([exploration.md](references/exploration.md#reuse-first)).
|
|
190
|
+
5. **Size check:** run `size-check.mjs` (exit 0; read `verdict`). On `hold` or `stop`, hold the listed
|
|
191
|
+
units (their dependents wait, not started) and draft their splits (yours when none is drafted); on `exploration-unfinished`, continue the explorer.
|
|
192
|
+
6. **Approval:** ask once for implementer, target, merge mode, scheduler mode, and plan;
|
|
193
|
+
record the answers and create workspaces.
|
|
194
|
+
In shortcut mode, take the defaults: on `hold` or `stop`, file the splits (never defer
|
|
195
|
+
for size), accept recommended answers, and run the rest ([shortcut mode](references/preflight.md#shortcut-mode)).
|
|
196
|
+
|
|
197
|
+
### 2. Implement and open the PR
|
|
198
|
+
|
|
199
|
+
Give each unit a branch, workspace, and implementer with its findings entry
|
|
200
|
+
and parents' contracts; state outcome and validation, not method. Refill
|
|
201
|
+
slots at once. At a unit's first coherent commit its PR opens as a draft, so CI
|
|
202
|
+
starts and the work is safe; later work goes to the same PR (in a Mergify stack
|
|
203
|
+
repository, amend the one commit); review starts when its code is done
|
|
204
|
+
([implementation.md](references/implementation.md#open-the-pr)). Pushes to
|
|
205
|
+
the unit's own PR branch need no approval.
|
|
206
|
+
|
|
207
|
+
### 3. Review
|
|
208
|
+
|
|
209
|
+
Spawn one `better-review` reviewer once the unit's code is done, unless a
|
|
210
|
+
trusted complete result for that HEAD is posted on the PR; it runs alongside
|
|
211
|
+
CI. From round 2, carry a HEAD that follows a pass, else pick the tier: a
|
|
212
|
+
carry or skip writes its record and spawns no reviewer ([review.md](references/review.md#tier-then-verdict)).
|
|
213
|
+
Merge [GitHub reviews](references/review.md#github-reviews) into its result,
|
|
214
|
+
run `review-verdict.mjs`, and follow the `verdict` it prints (exit 0; 2 only if it could not run): `pass`; `fix`, give the
|
|
215
|
+
`fixBrief` (P0/P1 only) to a fix worker as its `action` says, then review
|
|
216
|
+
again; `review-again`; `handback`, defer the PR with its open findings; `wait`,
|
|
217
|
+
request the awaited re-review; `decide`, answer the `decide` file
|
|
218
|
+
([expire.md](references/expire.md#decide-before-you-defer)) and rerun with `--decision`.
|
|
219
|
+
|
|
220
|
+
### 4. CI and merge
|
|
221
|
+
|
|
222
|
+
Watch CI on every pushed HEAD; green means every required check ran and passed on that
|
|
223
|
+
HEAD (none reported is not green). Have a fix worker fix failures on the branch;
|
|
224
|
+
principle 6 decides the new HEAD's review.
|
|
225
|
+
Enqueue through the queue's skill only when CI is green and the verdict is `pass`
|
|
226
|
+
on the same HEAD.
|
|
227
|
+
After 2 cycles without progress ([expire.md](references/expire.md)), or a harness-reported stuck worker, take the failure kind's response
|
|
228
|
+
([expire.md](references/expire.md)).
|
|
229
|
+
|
|
230
|
+
## Task plan and board
|
|
231
|
+
|
|
232
|
+
Keep the task plan as the only source of truth; only you update it
|
|
233
|
+
([task-plan.md](references/task-plan.md)). On Pi, bind or reload with
|
|
234
|
+
`update_plan({workflow:{path:<absolute-plan-path>,revision:<persisted-planRevision>}})`;
|
|
235
|
+
with no event this is read-only. Save transitions through `update_plan`'s
|
|
236
|
+
`workflow` payload with the current revision; it persists the plan and
|
|
237
|
+
refreshes the TUI. Never edit the bound plan directly.
|
|
238
|
+
Render the board from the saved plan under that same `planRevision`.
|
|
239
|
+
|
|
240
|
+
## Done
|
|
241
|
+
|
|
242
|
+
First [settle blocked units](references/done.md#settle-blocked-units). Every PR is reviewed, green on its exact HEAD, and merged (`autonomous`) or
|
|
243
|
+
handed back merge-ready (`supervised`). For a blocked unit, hand back it, its
|
|
244
|
+
dependents, and the merged units. Link each issue the run filed into the spec's tree, and each `excluded` rollup to close;
|
|
245
|
+
hand back the draft from `<run>/splits/` only for a unit still held, and the link to the pending device record. Report one short record per unit:
|
|
246
|
+
behavior delivered, checks and results, the PR and its CI run, and any
|
|
247
|
+
outstanding blocker or pending obligation as an issue link, then
|
|
248
|
+
[post the dropbox](references/dropbox.md#post-at-the-end) and the run
|
|
249
|
+
line: elapsed time (as on the board) and the run directory.
|
|
250
|
+
Then [close the run](references/done.md#close-the-run): complete the goal; never pause it for a reply.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
interface:
|
|
2
|
+
display_name: "Resolve Issues"
|
|
3
|
+
short_description: "Slash/explicit-only spec to reviewed, merged PRs, one per issue; asks once at preflight"
|
|
4
|
+
|
|
5
|
+
policy:
|
|
6
|
+
# Codex counterpart to SKILL.md disable-model-invocation: true
|
|
7
|
+
# (Claude Code / Pi). Keeps $resolve-issues / explicit invoke; blocks
|
|
8
|
+
# description-based auto-selection.
|
|
9
|
+
allow_implicit_invocation: false
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "After a context compaction, tell a resolve-issues or rush-issues coordinator to read its skills in full again.",
|
|
3
|
+
"hooks": {
|
|
4
|
+
"SessionStart": [
|
|
5
|
+
{
|
|
6
|
+
"matcher": "compact",
|
|
7
|
+
"hooks": [
|
|
8
|
+
{
|
|
9
|
+
"type": "command",
|
|
10
|
+
"command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/engineering/resolve-issues/scripts/rehydrate.mjs\" --hook",
|
|
11
|
+
"timeout": 10
|
|
12
|
+
}
|
|
13
|
+
]
|
|
14
|
+
}
|
|
15
|
+
]
|
|
16
|
+
}
|
|
17
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Read-only data-warehouse canary
|
|
2
|
+
|
|
3
|
+
Optional and report-only. Run it on the merged commit, before any production
|
|
4
|
+
release, when a staging surface exists and the unit changes executable
|
|
5
|
+
warehouse behavior or its data contract (Spark, SQL, or ETL transforms,
|
|
6
|
+
schemas, keys, partitions, watermarks, checkpoints, backfills, writers).
|
|
7
|
+
Skip it for read-only application work or warehouse docs. Record the
|
|
8
|
+
classification and reason on the unit.
|
|
9
|
+
|
|
10
|
+
1. Record the 40-character merged SHA and bind every artifact or job to it.
|
|
11
|
+
2. Use the repository's real entry point on staging with read-only
|
|
12
|
+
credentials.
|
|
13
|
+
3. Use a bounded, representative snapshot and the repository's validate-only
|
|
14
|
+
or dry-run guard, placed before every writer, never a mode that skips the
|
|
15
|
+
transform under test.
|
|
16
|
+
4. Prove no output, table-format commit, checkpoint, watermark, offset,
|
|
17
|
+
scheduler-state change, or other publication. For Spark, require zero
|
|
18
|
+
output records and bytes and an explicit publication skip.
|
|
19
|
+
5. Record the command, the SHA, and the zero-write result on the unit's
|
|
20
|
+
`warehouseCanary` field.
|
|
21
|
+
|
|
22
|
+
Never run a write-enabled canary, trust a command name, or substitute local
|
|
23
|
+
tests. Without a provable read-only mode or a staging surface, skip it and
|
|
24
|
+
hand back what is missing. Never block a unit or the run on it.
|
|
25
|
+
|
|
26
|
+
On failure, never touch production: open one follow-up issue with the
|
|
27
|
+
command and its error, and list it in the handback. Stop after 2 attempts without
|
|
28
|
+
progress: the distinct-error count reached no new low, or a stuck worker.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# CI, queue, and merge
|
|
2
|
+
|
|
3
|
+
Run per PR, in parallel with its review, from the moment its draft PR
|
|
4
|
+
opens.
|
|
5
|
+
|
|
6
|
+
1. Watch the required checks for every pushed HEAD. Pushes to the unit's own
|
|
7
|
+
PR branch need no approval. Green means every required check ran and passed
|
|
8
|
+
on that HEAD: a check that never reported is missing, not passed. Example: a
|
|
9
|
+
PR with no checks at all is not green; find out why CI did not run.
|
|
10
|
+
2. On failure, read the logs; have a fix worker reproduce it, fix it on the
|
|
11
|
+
same branch, rerun the failing check (a journey: off CI, with
|
|
12
|
+
`proof.suite.local`) and the checks the fix affects plus
|
|
13
|
+
typecheck and build, and return the commands and results. An
|
|
14
|
+
infrastructure failure goes to [expire.md](expire.md#infrastructure-failures).
|
|
15
|
+
3. A changed HEAD needs approval bound to that HEAD: push it and let CI
|
|
16
|
+
run. After a passing review, [carry](review.md#carry-after-a-pass) it:
|
|
17
|
+
no reviewer, CI on it is the proof. Otherwise run the tier the scope
|
|
18
|
+
script picks ([review.md](review.md#tier-then-verdict)). A provider rerun keeps the
|
|
19
|
+
review. Required CI proves the final combined tree. Rerun only checks
|
|
20
|
+
whose inputs changed.
|
|
21
|
+
4. Before enqueueing, rerun the GitHub merge and require
|
|
22
|
+
`review-verdict.mjs --head <headSha>` verdict `pass` on the latest review file
|
|
23
|
+
(with `--base <review base>` for a scope-script skip record, never for a
|
|
24
|
+
carry) and green CI for that SHA; on `review-again`, review again.
|
|
25
|
+
Inspect the live queue configuration. With Mergify, use the `mergify`
|
|
26
|
+
skill's status and watcher, never PR-check polling.
|
|
27
|
+
5. Mark the draft ready only then. `autonomous`: merge through the
|
|
28
|
+
repository's flow (enqueue and watch under a queue); once the change lands on the target (the merge, or the push in a
|
|
29
|
+
direct-push repository), and only then, set the unit `succeeded` with
|
|
30
|
+
`delivery: merged`. `supervised`: hand back the green reviewed HEAD and
|
|
31
|
+
keep the unit `in-flight`; never approve or merge for the human.
|
|
32
|
+
|
|
33
|
+
## `stack` and `chain` mode
|
|
34
|
+
|
|
35
|
+
- `next-actions.mjs` prints one `deliver` per line: its deepest PR whose
|
|
36
|
+
whole line passed review. When CI is green on every HEAD in the line, mark
|
|
37
|
+
them all ready and enqueue only that deepest PR. A line is one queue entry,
|
|
38
|
+
even where the `mergify` skill says to enqueue the whole ready set.
|
|
39
|
+
Example: #3121 -> #3119 -> #3122 all passed review and are green: enqueue
|
|
40
|
+
#3122 alone.
|
|
41
|
+
- `stack`: `@mergifyio queue` on it queues every PR below it in the GitHub
|
|
42
|
+
stack, and Mergify lands them bottom first.
|
|
43
|
+
- `chain`: its merge lands the line, and GitHub marks the others merged.
|
|
44
|
+
|
|
45
|
+
Set each `succeeded` when it lands. While one is not green yet, enqueue the
|
|
46
|
+
deepest PR with every PR below it green, and the rest after: in `stack`
|
|
47
|
+
mode a queue on a red PR still lands the green ones below it, so never
|
|
48
|
+
queue a red one.
|
|
49
|
+
- Restack a parent's children once its new HEAD passes review, not on every
|
|
50
|
+
fix push: one restack, and one CI run per child, per settled parent.
|
|
51
|
+
`next-actions.mjs` prints `restack` for each child whose `parentHead` is
|
|
52
|
+
not its parent's passed HEAD, and delivers no line until every link
|
|
53
|
+
matches: a branch built on an older parent HEAD would land commits nobody
|
|
54
|
+
reviewed. Carry a passed child ([review.md](review.md#carry-after-a-pass)).
|
|
55
|
+
Cancel the CI runs on the HEADs a restack replaced; on a busy runner fleet
|
|
56
|
+
they delay the HEADs that count.
|
|
57
|
+
- On `restack`, rebase the PR off the ancestors it names, onto the parent it
|
|
58
|
+
names or the target; the new HEAD takes the scope script's tier. It fires
|
|
59
|
+
when a parent is blocked or cancelled, when a PR with a parent has no
|
|
60
|
+
recorded `offLine` (restack it and record one), and when a PR has passed review
|
|
61
|
+
but waits on an ancestor it only shares files with: at once if that ancestor
|
|
62
|
+
is in a fix round, else after 30 minutes. The ancestor rebases after the PR
|
|
63
|
+
lands. A dependency is never dropped. Example: wiki-kb #12's replay: without
|
|
64
|
+
this, chained PRs waited 872 minutes in all behind slow reviews, more than
|
|
65
|
+
`wait` mode's 534; with it, 281.
|
|
66
|
+
- In `stack` mode, a restack that moves a PR to the target takes it out of
|
|
67
|
+
its GitHub stack. Before any PR in that stack is queued (if one is, wait
|
|
68
|
+
until it lands): retarget the PR, `gh stack checkout <PR>`,
|
|
69
|
+
`gh stack unstack`, then `gh stack link` each line that remains, bottom
|
|
70
|
+
first, as the `restack` names them. Dequeuing a PR also dequeues the PRs
|
|
71
|
+
above it.
|
|
72
|
+
- In `stack` mode, `next-actions.mjs` changes a GitHub stack once per pass:
|
|
73
|
+
a PR leaving it, else another restack, else a queue, else a newly linked
|
|
74
|
+
child. Other actions on
|
|
75
|
+
that line wait for the next pass: `gh stack unstack` leaves a queued PR
|
|
76
|
+
stacked, and a child linked onto a queued parent lands on a branch that is
|
|
77
|
+
gone.
|
|
78
|
+
- When a parent is dequeued or fails, hold its children and fix the parent
|
|
79
|
+
([expire.md](expire.md)).
|
|
80
|
+
|
|
81
|
+
## `wait` mode
|
|
82
|
+
|
|
83
|
+
When a PR merges, rebase its dependents onto the freshly fetched target and
|
|
84
|
+
open their PRs (they started on its code already).
|
|
85
|
+
|
|
86
|
+
## Expiry
|
|
87
|
+
|
|
88
|
+
After 2 cycles without progress, or a harness-reported stuck worker, follow [expire.md](expire.md). Treat
|
|
89
|
+
a pending queue as a wait to watch, never a reason to change code. For a
|
|
90
|
+
human-only blocker, take its automatic answer ([preflight.md](preflight.md#never-block-on-the-human)); when
|
|
91
|
+
that defers it, mark the unit `blocked` (`blockedReason: human-decision`, its `humanItem` and `humanNeed`) and
|
|
92
|
+
record the PR URL, HEAD, check and queue state, and the next action on its
|
|
93
|
+
owning issue; an
|
|
94
|
+
external blocker becomes a tree issue the unit waits on
|
|
95
|
+
([expire.md](expire.md#infrastructure-failures)). Report a merge only when the
|
|
96
|
+
provider shows that PR merged.
|
|
97
|
+
|
|
98
|
+
## After the merge
|
|
99
|
+
|
|
100
|
+
Remove the unit workspace, then its review clone:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
node <skill-base-dir>/scripts/cleanup-runs.mjs --merged <unit-workspace> --apply
|
|
104
|
+
node <skill-base-dir>/scripts/cleanup-runs.mjs --merged <review-clone> --apply
|
|
105
|
+
```
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Done
|
|
2
|
+
|
|
3
|
+
End a run in three steps, in order: settle blocked units, report, then close
|
|
4
|
+
the run in the harness.
|
|
5
|
+
|
|
6
|
+
## Settle blocked units
|
|
7
|
+
|
|
8
|
+
When every remaining unit is blocked, or not started behind a blocked one,
|
|
9
|
+
and no worker is running, do not end yet: take each automatic answer
|
|
10
|
+
([preflight.md](preflight.md#never-block-on-the-human)) and continue; what
|
|
11
|
+
is deferred stays recorded on its owning issue. A block that can clear by
|
|
12
|
+
itself is not settled while `next-actions.mjs` prints `wait` or
|
|
13
|
+
`retry-blocked` for it ([expire.md](expire.md#reason-codes)). End only when
|
|
14
|
+
nothing is left to settle.
|
|
15
|
+
|
|
16
|
+
## Close the run
|
|
17
|
+
|
|
18
|
+
After the report ([SKILL.md](../SKILL.md#done)):
|
|
19
|
+
|
|
20
|
+
The run is done when nothing it can do is left: every unit landed,
|
|
21
|
+
cancelled, deferred, or (`supervised`) handed back merge-ready. Mark the goal
|
|
22
|
+
complete (`update_goal` with `complete`), which also releases the workflow;
|
|
23
|
+
never pause it for a reply. The report lists each deferred item with its
|
|
24
|
+
owning issue and what each not-started unit waits on; a later run on the
|
|
25
|
+
spec picks them up.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Dropbox
|
|
2
|
+
|
|
3
|
+
Collect the run's small, non-blocking problems in `<run>/dropbox.json` and
|
|
4
|
+
post them as grouped `ready-for-agent` issues once the main work is done,
|
|
5
|
+
with the facts only ([Filed text](preflight.md#filed-text)).
|
|
6
|
+
`scripts/dropbox.mjs` reads and writes the file; you are its only writer.
|
|
7
|
+
Workers report problems; you route them.
|
|
8
|
+
|
|
9
|
+
## Route every problem
|
|
10
|
+
|
|
11
|
+
Ask these in order; the first yes decides. Never route by the stated P-number:
|
|
12
|
+
labels miss in both directions.
|
|
13
|
+
|
|
14
|
+
1. **Could it hurt someone now?** Security, auth, tenancy, money, data loss,
|
|
15
|
+
a failure users see, a flake that knocks other PRs out of the queue, or a
|
|
16
|
+
check that reports a false verdict (a weak test is not one). **File it
|
|
17
|
+
now** (`post --ids`), and name it in the handback. "Unreachable" never
|
|
18
|
+
downgrades it when the input comes from outside the code.
|
|
19
|
+
Example: a reviewer notes, as P2, that a provider webhook amount is parsed
|
|
20
|
+
without a check, "unreachable today". The input is external: file it now.
|
|
21
|
+
2. **Does it stop this unit from being finished or proven?** Small and in the
|
|
22
|
+
unit's files: fix it in the unit. A question: take its automatic answer
|
|
23
|
+
([preflight.md](preflight.md#never-block-on-the-human)); defer it only when it is human-only. Anything else outside the unit's files, code or
|
|
24
|
+
environment: an [infrastructure failure](expire.md#infrastructure-failures).
|
|
25
|
+
Example: the shared test helper the unit's tests need is broken on the
|
|
26
|
+
target: an infrastructure failure.
|
|
27
|
+
3. **Did this unit cause it?** Fix it in the unit, however small; it costs
|
|
28
|
+
less now than as an issue. `dropbox.mjs check` decides (`inDiff` true inside the
|
|
29
|
+
unit's diff), and `add` refuses an implementer entry there. A reviewer's
|
|
30
|
+
P2 never starts a fix round: it stays in the dropbox marked `inDiff`.
|
|
31
|
+
4. **Would fixing it change nothing** for behavior or for a reader? A style
|
|
32
|
+
nit, a smell no documented rule names, hardening the
|
|
33
|
+
code shows cannot trigger (internal input only, and this unit adds no new
|
|
34
|
+
caller), upkeep of run records, code already slated for removal, or no
|
|
35
|
+
location to act on. Stale docs do change something: a reader is misled.
|
|
36
|
+
**Drop it** (`mark --drop <reason>` when it is already an entry).
|
|
37
|
+
5. **Does it need a human choice?** A missing or unclear criterion that does
|
|
38
|
+
not block the unit. **Decision**: `add --decision` or `mark --decision`;
|
|
39
|
+
listed in the handback, never posted.
|
|
40
|
+
6. **Otherwise: dropbox.** An agent can fix it alone at a known location.
|
|
41
|
+
Example: a weak assertion in a test file the unit did not touch, at
|
|
42
|
+
`src/reports/summary.test.ts:30`.
|
|
43
|
+
|
|
44
|
+
Record a blocking relation with `--blocks <#n | owner/name#n | issue URL>`:
|
|
45
|
+
the posted issue says `Blocks #n` so a later run takes it first.
|
|
46
|
+
|
|
47
|
+
## Commands
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
D=<skill-base-dir>/scripts/dropbox.mjs
|
|
51
|
+
# implementer, before reporting: is it my own change?
|
|
52
|
+
node $D check --git <workspace> --base <review base> --file <path> --line <n>
|
|
53
|
+
# coordinator, for each implementer report and each other problem
|
|
54
|
+
node $D add --dropbox <run>/dropbox.json --unit <id> --source implementer \
|
|
55
|
+
--kind bug|test|docs|typing|refactor|ci|perf|other --file <path> --line <n> \
|
|
56
|
+
--summary "<one line: what is wrong>" [--pr <url>] [--blocks <issue>] \
|
|
57
|
+
--git <workspace> --base <review base>
|
|
58
|
+
# coordinator, after every review round, before the verdict: adds every P2 (P3 is skipped),
|
|
59
|
+
# then route each new entry; questions 1, 4, 5 change it:
|
|
60
|
+
node $D from-review --dropbox <run>/dropbox.json --review <run>/reviews/<unit>-r<N>.json \
|
|
61
|
+
--pr <url> --git <unit review clone> --base <review base>
|
|
62
|
+
node $D post --dropbox <run>/dropbox.json --repo <owner/name> --ids D3 # 1: file now
|
|
63
|
+
node $D mark --dropbox <run>/dropbox.json --id D4 --drop "<reason>" # 4: drop
|
|
64
|
+
node $D mark --dropbox <run>/dropbox.json --id D5 --decision # 5: decision
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Paths are repository-relative, with the line in `--line`. `add` prints `refused`: the
|
|
68
|
+
problem is in the unit's own change; resume the unit's implementer with it.
|
|
69
|
+
Exit 2 (the script could not run): fix the command; a review clone missing the PR head needs it fetched
|
|
70
|
+
first.
|
|
71
|
+
|
|
72
|
+
## Post at the end
|
|
73
|
+
|
|
74
|
+
When every unit is merged, handed back, or blocked, run `plan`, then `post`:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
node $D plan --dropbox <run>/dropbox.json --git <repo> --ref origin/<targetBranch>
|
|
78
|
+
node $D post --dropbox <run>/dropbox.json --repo <owner/name> --git <repo> \
|
|
79
|
+
--ref origin/<targetBranch> [--only G1,G4]
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Post every group without asking, and earlier runs' pending dropboxes
|
|
83
|
+
(`pending --runs .resolve-issues/rush` lists them) each with its own
|
|
84
|
+
`--dropbox` (group ids repeat across files).
|
|
85
|
+
|
|
86
|
+
`post` groups by parent PR (the same file and kind join across PRs), skips
|
|
87
|
+
entries an open issue already carries, drops entries whose file is gone at
|
|
88
|
+
`--ref`, and labels each issue `ready-for-agent`. Put the posted links, the
|
|
89
|
+
dropped count, and the `decisions` in the handback, and end it with:
|
|
90
|
+
"N follow-up issues are ready for `/rush-issues`."
|