Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
130 changes: 113 additions & 17 deletions .agents/skills/adaptive-wait/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,125 @@
---
name: adaptive-wait
description: Adaptive WAIT stage for agentic GitHub ops. After any dispatch, commit, rebase, or merge request — re-check jobs/steps/logs/artifacts, do concurrent non-conflicting work, classify stalls, and only promote when dual gates + task outcome are verified. Triggers when waiting on CI, after PR open/update, during /continue cycles, or when operator says wait adaptively. Cross-session SSOT — always load from master, never chat-only.
description: Adaptive WAIT for agentic GitHub operations. Re-fetch authoritative state, detect progress or stalls, keep useful disjoint work moving, and promote only from current-SHA evidence.
---

# Skill: adaptive-wait
# Adaptive WAIT

**Owner:** ArchW1z / Grok Administrator
**Complements:** `evidence-led-monorepo-ops`, `adaptive-feedback-cycle`, `production-reconciliation`, `review-loop`
Use this skill whenever work is asynchronous: GitHub Actions, reviews, deployments, provider jobs, external agents, or any operation whose next action depends on new state.

While one PR's checks run: preserve immutable IDs; work on a disjoint path; do not idle.
## Control objective

Promote only when dual gates success, extract-clean scope, and task outcome verified.
Waiting is an evidence-collection phase, not an idle timer. HOLD is not an idle parking state.

## Failure / stall classes (do not soft-pedal)
The controller must answer, on every cycle:

| Class | Severity | Notes |
|-------|----------|-------|
| **comment-storm** | **FAILURE** | issue_comment / bot / ledger fan-out that cancels useful jobs. Mitigate: concurrency by event_name, `cancel-in-progress: false` on ledgers. Landed #603 on `dc30bf83`. |
| dual-gate red | FAILURE | Block promote |
| update-branch-conflict | STALL | Extract-later; do not force dirty |
| dirty-behind-master | STALL | Rebase/extract from live master |
| extra-red | FAILURE (non-gate) | Fix root cause |
1. What immutable state am I watching?
2. What evidence changed since the last observation?
3. Can that evidence change the next action?
4. If not, should I back off, do disjoint work, or stop?
5. What authoritative re-fetch will prove the next state?

HEAD after #603: `dc30bf83fc17b394510f99328f7a081b6a64f28c`. #601 ML dirty/behind — WAIT extract.
Continuous Fully Automated Agentic Development: agents auto-promote when dual-gate + task outcome are verified on the candidate SHA. Sovereignty cockpit = ArchWiz + chat (goals/constraints, not a synchronous merge checkpoint).

Session 2026-09-18T17:03Z: merged #603; CodeRabbit `queue: max` rejected (invalid GHA concurrency key).
## State machine

BIUDL. Agent-Identity: Grok (Administrator)
| State | Entry evidence | Action |
|---|---|---|
| ACTIVE | run/job/review/artifact state is changing or useful work is still executing | re-fetch at an adaptive cadence; do not duplicate work |
| QUIET | no meaningful delta, but the operation remains live | increase the wait interval; work on a disjoint bounded task |
| STALLED | repeated identical state, no progress, deadlock, expired deadline, or repeated non-informative retry | stop blind retries; classify and change the experiment/approach |
| TERMINAL | authoritative success/failure/cancellation or task outcome is verified | validate current SHA and close the cycle |
| BLOCKED | required authority, credential, input, or external capacity is missing | record the blocker; request only the missing authority/input |

Never treat elapsed time, HTTP 200, a successful dispatch, or a green individual job as task completion.

## Adaptive cadence

Choose the next observation from evidence, not a universal polling constant:

- Immediate re-fetch: after a material commit, workflow dispatch, rerun, steering action, review response, or newly reported failure.
- Short wait: while a run/job is actively producing new steps, logs, artifacts, or review events.
- Backoff: when repeated observations contain no material delta and the authoritative state remains live.
- Stop retrying: when the same failure repeats without a changed input, environment, or hypothesis.
- One-shot: when no new feedback can change the next action.
- Deadline stop: when the platform/task deadline is authoritative; do not invent a second application-level timeout.

Record why the cadence changed.

## Mandatory re-fetch contract

After every material commit or steering action, re-fetch: SHA -> workflow/run -> jobs -> steps/logs/artifacts -> reviews/comments -> resulting SHA/status.

Bind every conclusion to the SHA that produced its evidence. A newer SHA invalidates approval evidence from an older head unless the evidence is explicitly historical.

## Disjoint-work rule

While useful work is running, continue only with work that cannot mutate or invalidate the watched operation. Good disjoint work includes deterministic documentation or inventory improvements, bounded repository reconnaissance, non-invasive tests, relationship-graph queries, and review/evidence ingestion.

Do not create competing writes, duplicate workflow dispatches, or overlapping branches merely to stay busy.

## Retry / steering rule

Retry only when the new attempt has an evidence-backed reason to differ: changed input or SHA; transient infrastructure/provider failure; recovered capacity/quota; corrected workflow/reference; or a new review finding or authoritative instruction.

Preserve every attempt. Never rewrite history to hide a failed wait cycle.

## Evidence receipt

Each cycle should be representable by a compact receipt:

observed_at: <UTC>
watched:
repo: <owner/name>
ref: <branch/tag/SHA>
sha: <immutable SHA>
state: ACTIVE|QUIET|STALLED|TERMINAL|BLOCKED
evidence:
runs: [<run ids>]
jobs: [<job ids>]
reviews: [<stable ids>]
artifacts: [<stable ids>]
delta: <what changed since prior observation>
decision: WAIT|BACKOFF|STEER|RETRY|STOP|PROMOTE
reason: <evidence-backed reason>
next_check: <authoritative condition>
outcome: PASS|FAIL|UNKNOWN

Never store secrets, authorization headers, raw discussion bodies, or private session state in the receipt.

## Promotion boundary

Promotion requires: current immutable SHA; current-base relationship verified; relevant validation evidence terminal; requested task outcome verified; no unresolved actionable finding; and evidence attributable to the candidate SHA.

Dual-gate status is necessary where the repository defines it, but it is not a substitute for task-outcome verification.

Repository dual-gate: `hygiene + portability gate` + `agentic termux smoke`. Vercel rate-limit is non-gate (#772). Copilot / CodeRabbit / Devin are advisory only. `mergeable_state=dirty` or a GitHub merge conflict is a hard block even when dual-gate is green — rebase/re-extract onto live tip.

**Mega-merge (Operator 2026-09-24):** Allowed when dual-gate + mergeable. CodeRabbit ~100-file limit is advisory review capacity, not a promote ban. Size alone does not block.

## Terminal states

- success — requested outcome verified;
- clean-no-op — no change required;
- blocked — new authority/input is required;
- approval-required — policy requires escalation;
- exhausted — authoritative task/platform limit reached;
- stagnated — repeated cycles produced no measurable progress.

Never report exhausted, stalled, or blocked as success.

## Closeout

Record what was proven, what remains unproven, the watched SHA, the final authoritative evidence, and the next disjoint action or terminal state.

This skill is the wait/controller layer. adaptive-feedback-cycle owns broader continuous learning; production-reconciliation owns ref alignment; evidence-envelope owns normalized observation fields.

## Session 2026-09-28 17:15 PDT

- Live master `8daeeb72d71ecdefa2f9cde6698426131117e474`.
- Dual-gate PASS: repo-gate 36497249095 / termux-smoke 36497249115.
- #904 merged. Watching #899 rebase onto live tip.
- Instant-fail path-unfiltered workflows are noise.
- #903 HOLD. Do not merge #892/#894. Do not pulse #175. #184 names-only.

Agent-Identity: Grok (Administrator)
7 changes: 7 additions & 0 deletions .agents/skills/adaptive-wait/references/BOARD-VS-LEDGER.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Adaptive wait + board

WAIT collects evidence on a product SHA. It does not create a new pulse PR.
Read generated lane-matrix-status. Close leftover session pulses as SUPERSEDE.
Do not comment #175 as a heartbeat.

Session 2026-09-24 12:33 PDT. Agent-Identity: Grok (Administrator)
27 changes: 27 additions & 0 deletions .agents/skills/context-relationship-graph/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,33 @@ Do not persist discussion bodies, session stores, browser profiles, credentials,

Every PR/issue is an observation candidate. Not every PR needs a Markdown receipt. Receipts are human-readable projections of notable measurements or promotions.

## Temporal evidence layer

The historical backfill now produces a second, append-only evidence layer under:

`workspace/llm_map/context_relationships/temporal/`

Each observation receives a deterministic `snapshot_id` bound to repository/ref, source SHA, observation time, and page bounds. Snapshot manifests retain:

- source SHA/ref and observation timestamp;
- history start/continuation pages;
- explicit coverage state;
- node/edge counts and content hashes;
- previous snapshot identity;
- structural delta counts.

Snapshots are immutable. Re-running the same observation may reuse the existing snapshot but must never overwrite its contents.

The temporal layer distinguishes:

`source → relationship → observation → snapshot → lineage`

A later observation may add, remove, change, or reclassify a relationship. This is a delta, not permission to rewrite the prior evidence.

Use `temporal-current.json` for the latest materialized observation and `temporal/lineage.jsonl` for the append-only observation chain. The current graph remains the L1 relationship view; temporal snapshots are the L2 evidence/history layer consumed by SHE, longitudinal analysis, and future context reconstruction.

Coverage is complete only when `history_window.next_start_page == null`. Node/edge growth alone never establishes historical completeness.

## Repository commands

Run from the repository root. Query an exact issue, a specific permalink, or a bounded file-review timeline:
Expand Down
171 changes: 144 additions & 27 deletions .agents/skills/evidence-led-monorepo-ops/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,42 +1,159 @@
---
name: evidence-led-monorepo-ops
description: Continuous evidence-led admin ops on timerloggedout-spec/termux-monorepo (and similar agentic monorepos). Triggers on priority matrix, master gates, SHE progress, Manus/provider RE, dirty PR triage, Actions hygiene, or when the operator says continue, BIUDL, maximize actions, or /continue. Use for live state pulls, dispositions, small-green extracts, adaptive WAIT, and iterative process improvement documented as skills. Load this skill in every admin session.
description: Continuous evidence-led admin operations for timerloggedout-spec/termux-monorepo. Reconstruct current state, bind actions to immutable SHAs, preserve provenance, and never confuse activity with verified outcome.
---

# Skill: evidence-led-monorepo-ops
# Evidence-Led Monorepo Operations

**Owner:** ArchW1z / Grok Administrator continuous admin on timerloggedout-spec/termux-monorepo.
Load this skill for every repository-admin session.

**Canonical paths (keep in sync):**
- `.agents/skills/evidence-led-monorepo-ops/SKILL.md` ← **agent load path**
- `docs/ops/skills/evidence-led-monorepo-ops/SKILL.md` ← human/docs mirror
- `docs/ops/SKILLS-INVENTORY.md` ← full skill table + adaptive WAIT
## Operating contract

**Primary agent entry:** `CLAUDE.md`.
RECON -> CLASSIFY -> PLAN -> ACT -> WAIT -> VALIDATE -> RE-FETCH -> RECORD -> REPEAT

## Posture
The goal is a verified repository outcome, not a green-looking activity stream.

- Evidence over anecdote. Extract-only. Dual-gate before merge.
- Extra-red ≠ dual-gate. Behind-master dual-gate green ≠ auto-merge.
- **comment-storm is a FAILURE**, not skippable noise. Mitigate with concurrency groups + `cancel-in-progress: false` on SHA-bound ledgers. Do not treat cancelled ledger runs as green.
- Identity: `Agent-Identity: Grok (Administrator)`.
- GitHub MCP write works as `timerloggedout-spec` even when local sandbox has no OPERATOR PAT / `gh`.
## 1. Reconstruct current state

## Current production anchors (2026-09-18T17:03Z UTC)
Before a consequential action, resolve:

| Item | State |
|------|-------|
| Master HEAD | `dc30bf83fc17b394510f99328f7a081b6a64f28c` (#603 squash) |
| Just landed | #603 comment-storm ledger fix. Prior: #602 catalog MD fingerprint; #600 skills SSOT. |
| Observe | #583 Grafana MCP; #584 MVT budget. Jules #597/#598. |
| Extra-red HOLD | #601 ML extract dirty/behind (`c082f533` base vs live `dc30bf83`). #549/#432 HOLD extract-later. |
| HOLD mega | #523 #527 #545 #543 #455 #485 #483 #481 |
| Draft | #578 accounting/bidding schema pilot |
- live master SHA;
- target branch/ref and immutable head SHA;
- merge-base and ahead/behind relationship;
- changed paths;
- open PR/issue context;
- current workflow runs, jobs, steps, artifacts, reviews, and comments relevant to the current SHA;
- applicable skill, governance, lane, and proposal SSOTs.

## Extract recipe
Prefer exact file, symbol, PR, issue, label, scope, or permalink roots. Keep verified relationships separate from heuristic candidates.

Create branch from current master. Do not force-update dirty branches. Do not wholesale-merge HOLD mega or #601/#549/#432.
## 2. Evidence hierarchy

CodeRabbit `queue: max` on GHA concurrency is **not a valid key** (only `group` + `cancel-in-progress`). Do not apply.
Prefer evidence in this order:

BIUDL. Agent-Identity: Grok (Administrator)
1. current-SHA repository diff and contracts;
2. current-SHA validation/test results;
3. current-SHA workflow/job/step/artifact evidence;
4. substantive current-SHA review findings;
5. provenance and task/issue lineage;
6. historical evidence from superseded SHAs;
7. size, age, comment count, or activity volume as **context only** (not promote blockers).

A workflow success proves that workflow result. It does not prove the requested task outcome.

## 3. Evidence identity

Every material observation should bind, where available, to repository/ref; immutable commit SHA; base SHA/merge-base; workflow/run/attempt/job/step IDs; artifact or receipt IDs; review/comment IDs; observed/event timestamps; agent/provider/model identity with confidence; experiment/cohort ID when applicable; status/outcome; provenance/confidence; and superseded predecessor.

Never infer missing IDs, timestamps, counts, authorship, or causal relationships.

## 4. State classification

Keep these states distinct:

PASS | FAIL | UNKNOWN | WARNING | SKIPPED | STALLED

Apply them separately to dispatch, execution, provider availability, quota/capacity, correctness, tests, integration, review, deployment, and task outcome.

A provider outage, rate limit, skipped reviewer, stale branch, and correctness failure are different observations.

## 5. Adaptive WAIT integration

During asynchronous work, use .agents/skills/adaptive-wait/SKILL.md.

- Re-fetch immediately after material commits, reruns, steering, or newly reported failures.
- Back off only when authoritative state is live and repeated observations show no material delta.
- Retry only when the next attempt differs for an evidence-backed reason.
- Continue disjoint work while useful evidence is accumulating.
- Stop on authoritative terminal state, stagnation, or a missing authority/input.
- Bind conclusions to the SHA that produced the evidence.

HOLD and OBSERVE are not idle parking states. WAIT collects evidence until promote conditions hold, then promote.

## 6. Change discipline

For repository mutations:

1. identify a change that advances the requested outcome (slice **or** mega — both valid);
2. re-read the current file/ref before writing;
3. make the change;
4. run the smallest relevant deterministic validation;
5. commit with a specific message;
6. re-fetch the resulting SHA and checks;
7. preserve failed attempts and superseded evidence.

Never force-push, reset, delete evidence, or silently overwrite another active state.

## 7. Promotion

Promotion requires current-SHA evidence for base alignment/reconciliation; relevant tests and invariants; review/finding disposition; integration/task outcome; and repository-defined dual gates.

COMMITTED, EXECUTED, VALIDATED, and PROMOTED are independent states.

Do not promote because a branch is old, a PR is green on an older SHA, a reviewer is silent, or a provider returned HTTP 200.

Repository dual-gate: hygiene/portability + agentic termux smoke. Vercel is non-gate (#772). Copilot / CodeRabbit / Devin are advisory only.

**Mega-merge policy (Operator 2026-09-24):** Mega-merge is **allowed** when dual-gate SUCCESS + mergeable on the candidate SHA. Collaborators hold large context windows. CodeRabbit’s ~100-file limit is **advisory review capacity**, not a hard promote ban. File count alone must not refuse a dual-gate-green PR. `mergeable_state=dirty` or merge conflict remains a hard block until rebased.

## 8. Historical continuity

Historical collection is bounded and resumable. Record page/window bounds, continuation state, collection timestamp, source/ref, parser/API failures, exclusions, and coverage. Never call a partial page complete history.

A failed or superseded attempt remains evidence. Correct forward with a successor change.

## 9. Write boundaries

Read-only reconnaissance may inspect repository/GitHub state. Mutating operations require the applicable explicit authorization and governance tier.

Never persist secrets, authorization headers, tokens, browser/session stores, private discussion bodies, or generated credentials in the repository. Issue #184 is names-only.

## 10. Closeout receipt

Use a compact receipt shape:

operation: <bounded operation>
repo: <owner/name>
base_sha: <sha>
head_sha: <sha>
observed_at: <UTC>
evidence:
checks: [<ids>]
runs: [<ids>]
reviews: [<ids>]
artifacts: [<ids>]
state: PASS|FAIL|UNKNOWN|WARNING|SKIPPED|STALLED
outcome: PASS|FAIL|UNKNOWN
provenance: <source/actor confidence>
decision: KEEP|RETRY|STEER|HOLD|PROMOTE|STOP
reason: <evidence-backed reason>
remaining: <unproven work>

Receipts are projections; the longitudinal GitHub/evidence corpus remains the source of historical truth.

## Related operational skills

- adaptive-wait — asynchronous control and cadence;
- adaptive-feedback-cycle — continuous feedback and historical evaluation;
- review-loop — review ingestion and repeated validation;
- context-relationship-graph — metadata-only relationship evidence;
- production-reconciliation — ref/base reconciliation;
- action-effectiveness-ledger — action-to-outcome measurement;
- evidence-envelope / evidence-provenance — normalized provenance;
- workflow-orchestration — modular Actions coordination;
- evolutionary-replay — bounded replay of realized discovery history.

This skill owns repository-admin evidence discipline; it does not replace those specialist lanes.

## Session 2026-09-28 17:15 PDT

- Live master tip: `8daeeb72d71ecdefa2f9cde6698426131117e474` (catalog/mmdc bot refresh after #904).
- Dual-gate PASS on that SHA: repo-gate 36497249095 + termux-smoke 36497249115.
- #904 squash `4efef68d` dual-gate PASS on master: 36497147812 / 36497147650.
- Candidate evidence for #904 pre-merge: repo-gate 36497057302 + termux-smoke 36497057157 on `4df79c30`.
- Tunnel scheduled fail 36496185804 / 109176191755 classified empty-URL skip, closed by #904.
- Instant-fail path-unfiltered workflows on feature branches are noise.
- #903 HOLD (empty-diff / ledger). #899 rebase in flight. Do not merge stale #892/#894.
- Do not pulse #175. #184 names-only. Vercel combined-status is #772 non-gate.

Agent-Identity: Grok (Administrator)
Loading
Loading