@1aboveio/skills 0.17.0 → 0.19.0

package/skills/engineering/rush-issues/references/profiling.md

@@ -0,0 +1,78 @@
+# Profiling
+
+Profile the workflow for later performance analysis without blocking delivery.
+Track each unit, fleet stage, bounded attempt, retry, and diagnosis.
+
+## Metrics
+
+| Metric | Meaning |
+|---|---|
+| `wallMs` | Elapsed enter-to-exit time |
+| `llmMs` | Time attributed to active model work |
+| `programMs` | Time attributed to local commands/programs |
+| `waitMs` | Pure external wait, such as CI or queue pending |
+| `effectiveMs` | Union of intervals with LLM or program activity, excluding pure wait |
+| `retries` | Current-cycle and cumulative retries |
+| `diagnoses` | Number and duration of diagnosis checkpoints |
+| `outcome` | `succeeded`, `expired`, `blocked`, or `cancelled` |
+| `expireReason` | Stable reason code when an attempt expires |
+
+Avoid double counting nested program calls inside an LLM task. If only coarse
+telemetry exists, classify non-overlapping intervals by their primary state.
+Use `null` plus a note for unavailable timing; do not turn unknown into zero.
+Across parallel workers, report both run wall time and summed worker time.
+
+## Layout
+
+```text
+.resolve-issues/rush/<run-id>/
+  task-plan.json
+  exploration/FINDINGS.md
+  profiling/
+    run.jsonl
+    summary.json
+```
+
+Append one JSONL event at task-plan checkpoints. Example:
+
+```json
+{
+  "ts": "2026-08-22T12:00:00.000Z",
+  "runId": "rush-1200",
+  "planRevision": 12,
+  "scope": "unit",
+  "unit": "1201",
+  "stage": "implement",
+  "attempt": 2,
+  "event": "exit",
+  "outcome": "expired",
+  "expireReason": "timeout-task",
+  "wallMs": 1800000,
+  "llmMs": 1320000,
+  "programMs": 240000,
+  "waitMs": 240000,
+  "effectiveMs": 1560000,
+  "retries": {"cycle": 2, "total": 2},
+  "diagnoses": 0,
+  "headSha": "abc123"
+}
+```
+
+Diagnosis events include the changed hypothesis/plan and link to the expired
+attempt. Fleet stages use `scope: "fleet"` and stage `explore`, `combine`,
+`canary`, `review`, or `cicd`. Every event carries the same `planRevision` as
+the persisted transition it describes; summary generation refuses mismatched
+or missing revisions rather than reconciling them by guess.
+
+## Summary
+
+Rewrite `summary.json` on each task-plan checkpoint and at handoff with:
+
+- per-unit, per-stage, and per-attempt wall/effective/wait totals
+- run wall time and summed worker time
+- worker utilization: busy slot time / available slot time
+- retry, expiry, diagnosis, and blocker counts by reason
+- time to task-plan display, exploration completion, PR open, review success,
+  CI green, queue entry, and merge
+
+Link the files in the final handoff; do not paste the full event log.

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

@@ -0,0 +1,48 @@
+# Independent factual review
+
+Run one independent review stage on the combined PR HEAD using the
+`code-review` skill and the reviewer slot.
+
+## Independence
+
+- Reviewer model differs from the implementer and is a deep-reasoner when
+  available; prefer `gpt-5.5@high` when discovered.
+- Fresh context includes the original spec, repository standards, target
+  branch, combined branch/HEAD, and exploration path.
+- Fixed point is the reviewer's own merge-base with
+  `origin/<targetBranch>`.
+
+Producer summaries, validation notes, logs, and evidence are untrusted claims.
+They may point to a file, AC, or command, but the reviewer verifies facts by
+reading original sources, inspecting the actual diff/code, running relevant
+checks, and observing behavior where needed. Do not ask the producer to create
+new evidence collateral as a substitute for verification.
+
+## Review procedure
+
+1. When `warehouseCanaryRequired` is true, require a successful canary result
+   for the current exact HEAD. Then invoke the absolute `code-review` skill path
+   on the combined HEAD.
+2. Review both axes: repository **Standards** and original **Spec**.
+3. Independently run or reproduce the checks needed to support each material
+   conclusion. A producer-provided green log is not a factual substitute.
+4. Return findings with severity and file/line references, plus commands the
+   reviewer actually ran. The review result is coordination state, not an
+   evidence-generation deliverable.
+5. Succeed only with no Spec gap/wrongness/creep and no hard Standards
+   violation. Record non-blocking baseline observations as deferrals.
+
+## Fix loop
+
+For blocking findings, fix the combined PR branch, run relevant lint/build/
+test/smoke, rerun [canary.md](canary.md) when required, then spawn a fresh
+review of the new HEAD. Record that exact SHA as `reviewedHead` only after
+success. Never treat a fix as accepted before validation, required canary, and
+re-review. Any later code/config commit, including a CICD fix, clears
+`reviewedHead`, marks the prior canary result stale, and returns the new HEAD
+through required validation/canary and review before it may be enqueued or
+merged.
+
+After 2 failed fix/review cycles or a 30-minute review task, expire the attempt,
+diagnose the recurring class or task shape, revise the plan, and continue. A
+human/external blocker ends in `blocked`, not a false successful review.

package/skills/engineering/rush-issues/references/shared-modules.md

@@ -0,0 +1,66 @@
+# Shared modules
+
+Rush owns orchestration, not copies of model, review, smoke, or queue doctrine.
+Implementation method belongs to the active harness. Resolve installed leaf
+skills from the active skills root only for stages that explicitly invoke one,
+and pass absolute paths to those subagents.
+
+## Model catalog and recommendation
+
+**Owner:** [`harness-runtime`](../../harness-runtime/)
+
+| Piece | Path |
+|---|---|
+| Catalog doctrine | `harness-runtime/references/model-catalog.md` |
+| Team seed | `harness-runtime/references/model-catalog-seed.json` |
+| Catalog CLI | `harness-runtime/model-catalog.mjs` |
+| Discovery CLI | `harness-runtime/discover-models.mjs` |
+| Rush fast path | `rush-issues/scripts/preflight-models.mjs` |
+| Shared preflight planner | `resolve-issues/scripts/preflight-questions.mjs` |
+
+Before reading the longer catalog doctrine, run:
+
+```bash
+node <skillsRoot>/rush-issues/scripts/preflight-models.mjs \
+  --harness <pi|codex|claude-code> \
+  --risk <routine|high> \
+  --available <comma-separated-current-turn-model-ids> \
+  --ask-only
+```
+
+The fast path discovers current-turn availability, recommends the implementer,
+fills explorer and reviewer, and emits the implementer picker payload. Feed the
+model choices and fetched target-branch choices through the shared preflight
+planner so the native interaction asks exactly those two questions.
+
+| Slot | Selection |
+|---|---|
+| Implementer | Human picks from discovered eligible models; routine recommends balanced-coder |
+| Explorer | Filled balanced-coder; prefer `gpt-5.6-terra@high` when discovered |
+| Reviewer | Filled distinct deep-reasoner; prefer `gpt-5.5@high` when discovered |
+
+Only discovered or explicitly human-named models are eligible. Defer catalog
+sync/bank until after the human answers. Spawn read-back must match each
+recorded slot. The shared planner is also used by workflows that record an
+autonomy fill; Rush must discard that field and must not treat it as merge
+authorization.
+
+## Leaf skills
+
+| Stage | Skill | Rush-specific constraint |
+|---|---|---|
+| Independent review | `code-review` | One fresh review of the combined branch, Standards and Spec axes |
+| Runtime smoke | `smoke` | Run when applicable; record a concrete not-applicable reason otherwise |
+| Merge queue | Queue owner, such as `mergify` | Inspect live configuration and use its watcher/enqueue procedure |
+
+`code-review` may be externally installed; never assume a repository-relative
+path. Producer summaries or validation notes may help locate claimed behavior,
+but the independent reviewer establishes facts from source, diff, commands,
+and runtime behavior itself. Do not add evidence-generation work merely to
+make the review look substantiated.
+
+## Rush-owned behavior
+
+Rush owns the task plan, shared findings location, isolated workspaces,
+continuous scheduling with in-flight cap 4, one-branch combination, whole-spec
+PR boundary, expiry/diagnosis loop, and profiling logs.

package/skills/engineering/rush-issues/references/task-plan.md

@@ -0,0 +1,110 @@
+# Task plan
+
+After model/target preflight, build the task plan as the run's live source of
+truth. Show it before exploration or implementation and keep it synchronized
+with every worker and fleet transition.
+
+## Initialize the run
+
+1. Prefer a dedicated run branch and workspace based on the confirmed target.
+   The run workspace owns combination, the single PR, review fixes, and CI
+   fixes. Do not reuse a dirty unrelated checkout.
+2. Turn a plain issue into one unit; turn an epic or fat issue into
+   implementable units that collectively cover the entire original spec.
+3. Record each unit's source and acceptance criteria, blocking dependencies
+   including premise dependencies, likely shared surfaces, and the whole-spec
+   definition of done.
+4. Read repository hazard guidance and attach its implementation, test, and
+   review obligations to affected units. Risk never removes a unit, changes the
+   one-PR boundary, or routes the run to another workflow.
+5. Set `warehouseCanaryRequired` when the run changes executable warehouse
+   behavior or its data contract, and record the concrete classification reason.
+6. Create the run directory, shared findings path, profiling log, and initial
+   machine-readable plan, then render the first board.
+
+## Shape
+
+Fleet rows: `explore`, `combine`, `canary`, `review`, `cicd`. Render `canary` as
+not applicable when `warehouseCanaryRequired` is false.
+
+Per-unit fields:
+
+| Field | Meaning |
+|---|---|
+| `id`, `title` | Stable unit identity and short title |
+| `source` | Original issue/spec/AC locator |
+| `workspace`, `branch` | Absolute owned Git workspace and branch |
+| `dependsOn` | Blocking unit ids |
+| `stage` | `pending`, `implement`, `validate`, `self-review`, `diagnose`, or `done` |
+| `status` | `pending`, `in-flight`, `diagnosing`, `succeeded`, `blocked`, or `cancelled` |
+| `attempt` | Current bounded attempt number |
+| `retries`, `diagnoses` | Current-cycle and cumulative counters |
+| `worker` | Slot 1-4 while in flight |
+| `clock` | Current attempt and cumulative wall time |
+| `note` | SHA, failure, diagnosis, or blocker |
+
+Run-level fields include `planRevision`, models/efforts, `targetBranch`, run
+workspace/branch, original spec locator, explicit merge authorization when one
+was supplied, exploration path, combined PR/HEAD, `reviewedHead`, and
+`warehouseCanaryRequired`, its classification reason, durable canary result
+path, and start/update timestamps.
+
+Persist the machine-readable plan at:
+
+```text
+.resolve-issues/rush/<run-id>/task-plan.json
+```
+
+## Checkpoint consistency
+
+Use one ordered checkpoint protocol for every transition:
+
+1. Increment `planRevision` and apply the complete state transition in memory.
+2. Append the profiling event with that same revision.
+3. Persist the plan and profiling checkpoint.
+4. Render the board by reading the persisted plan revision, not from a separate
+   hand-built snapshot.
+
+A checkpoint is invalid if the board, `task-plan.json`, and profiling event
+disagree on status, stage, retry/diagnosis counters, clocks, HEAD, or revision.
+Do not display a future transition before persistence or reuse an old board
+after persistence.
+
+## First display
+
+The first board is the visible task-planning result and appears before any
+explorer or implementer spawn.
+
+```text
+rush-issues  rev 12  workers 2/4  elapsed 18m  PR pending
+fleet: explore OK  combine .  canary n/a  review .  cicd .
++------+---------------------------+-------------+------------+---------+-------+
+| id   | title                     | stage       | status     | retry   | clock |
++------+---------------------------+-------------+------------+---------+-------+
+| #1201| fix queue stall watcher   | self-review | in-flight  | 1/2     | 16m   |
+| #1202| parse rename edges        | validate    | in-flight  | 0/2     | 09m   |
+| #1203| split oversized importer  | diagnose    | diagnosing | 2/2 D1  | 30m   |
++------+---------------------------+-------------+------------+---------+-------+
+```
+
+Use compact Markdown or text that remains readable in the active harness. Do
+not hide blocked or diagnosing units from the board.
+
+## Refresh checkpoints
+
+Redisplay when:
+
+- task-plan initialization completes
+- a fleet stage enters/exits
+- a worker is acquired/freed
+- a unit enters/succeeds/expires/blocks
+- validation fails or becomes green
+- a required warehouse canary starts, fails, succeeds, blocks, or is invalidated
+- a retry or diagnosis is recorded
+- a dependency becomes runnable
+- the combined PR opens or HEAD changes
+- about every 5 minutes during long activity
+
+Skip a redraw only when no material state changed. The final board includes all
+unit outcomes, PR URL/SHA when one exists, exploration/profiling paths, retry
+and diagnosis totals, and any exact blocker that prevented a whole-spec PR.

package/skills/engineering/rush-issues/scripts/discover-models.mjs

@@ -0,0 +1,9 @@
+// Thin wrapper: canonical ownership lives in harness-runtime.
+export * from '../../harness-runtime/discover-models.mjs'
+
+import { runCli } from '../../harness-runtime/discover-models.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)))
+}

package/skills/engineering/rush-issues/scripts/model-catalog.mjs

@@ -0,0 +1,9 @@
+// Thin wrapper: canonical ownership lives in harness-runtime.
+export * from '../../harness-runtime/model-catalog.mjs'
+
+import { runCli } from '../../harness-runtime/model-catalog.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2)))
+}