axstack 0.20.13 → 0.20.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -6
- package/docs/installation.md +4 -6
- package/docs/workflows.md +20 -23
- package/package.json +1 -1
- package/skills/axstack/references/automations.md +22 -46
- package/skills/axstack/references/candidate-publication.md +0 -14
- package/skills/axstack/references/lifecycle.md +8 -8
- package/skills/axstack/references/simplify-diff.md +51 -0
- package/skills/axstack-audit/SKILL.md +4 -0
- package/skills/axstack-implement/SKILL.md +10 -0
- package/skills/axstack-review/SKILL.md +22 -12
- package/skills/axstack-watch/SKILL.md +12 -37
- package/skills/axstack-watch/references/repair-publication.md +13 -17
- package/skills/axstack-watch/references/watch-runtime.md +0 -29
- package/skills/axstack/references/watch-manager-prompt.md +0 -12
package/README.md
CHANGED
|
@@ -107,11 +107,10 @@ model is unavailable. See [workflow and routing details](docs/workflows.md).
|
|
|
107
107
|
## Optional PR automation
|
|
108
108
|
|
|
109
109
|
Manual review and watch work independently of scheduled automation.
|
|
110
|
-
For recurring
|
|
111
|
-
|
|
112
|
-
authorized repair events.
|
|
110
|
+
For recurring peer review, Axstack defines one optional native Orca review manager.
|
|
111
|
+
Own-PR observation and authorized repair remain user-driven through `axstack-watch`.
|
|
113
112
|
|
|
114
|
-
The
|
|
113
|
+
The review manager uses a 15-minute schedule. Each pass uses a fresh finite
|
|
115
114
|
session in an isolated workspace and admits eligible actionable PR events within
|
|
116
115
|
measured host capacity. Waiting PRs remain tracked without consuming
|
|
117
116
|
execution slots, so a large open-PR backlog does not require an idle agent per PR.
|
|
@@ -121,8 +120,7 @@ release capacity only after native descendant settlement. Uncertain execution
|
|
|
121
120
|
teardown pauses the lane; settled evidence cleanup does not occupy a slot.
|
|
122
121
|
|
|
123
122
|
Scheduling is opt-in and requires host-specific runtime validation before
|
|
124
|
-
activation. Installing Axstack does not turn it on.
|
|
125
|
-
explicitly allowed repositories; automation never merges for you.
|
|
123
|
+
activation. Installing Axstack does not turn it on. The review automation never merges for you.
|
|
126
124
|
See [PR-manager setup and safety](skills/axstack/references/automations.md).
|
|
127
125
|
|
|
128
126
|
## Documentation
|
package/docs/installation.md
CHANGED
|
@@ -228,14 +228,12 @@ not prove that a running harness reloaded them.
|
|
|
228
228
|
|
|
229
229
|
The installed Axstack bundle does not own or copy Orca's guides. At an action
|
|
230
230
|
boundary, the skill resolves one Orca executable and loads that binary's
|
|
231
|
-
version-matched `orchestration` and `orca-cli` guides.
|
|
232
|
-
loaded only for the watch branch. Missing discovery is a setup gap, not a reason
|
|
231
|
+
version-matched `orchestration` and `orca-cli` guides. Review automation guidance is loaded only for the scheduled review branch. Missing discovery is a setup gap, not a reason
|
|
233
232
|
to fall back or invent commands.
|
|
234
233
|
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
custom scheduler.
|
|
234
|
+
Installation creates no production schedule and adds no custom scheduler.
|
|
235
|
+
The optional review manager requires a separate native canary before activation;
|
|
236
|
+
installed guidance does not prove live behavior.
|
|
239
237
|
|
|
240
238
|
## Historical migration
|
|
241
239
|
|
package/docs/workflows.md
CHANGED
|
@@ -140,12 +140,10 @@ session and evidence remain valid.
|
|
|
140
140
|
never publishes; authorized submission binds the exact commit.
|
|
141
141
|
- `axstack-watch` adopts an existing PR under observation-only, peer, or
|
|
142
142
|
authorized-maintenance scope. A changed head or comment is an event, not
|
|
143
|
-
repair authority.
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
SHA receives the actual-author-provenance review, and the exact candidate
|
|
148
|
-
lands by fast-forward `git push` after final readback.
|
|
143
|
+
repair authority. Within an implementation run, fixes return to the original
|
|
144
|
+
author and follow its publish-before-review loop. Manual adopted-PR repair
|
|
145
|
+
reviews the exact local SHA and reply bodies before `gh stack` publication
|
|
146
|
+
and remote readback.
|
|
149
147
|
- `axstack-audit` separates execution outcome, procedure, and measurement
|
|
150
148
|
coverage with evidenced denominators; it proposes but never self-edits.
|
|
151
149
|
- `axstack-cleanup` distinguishes settled-Dispatch release, exact unused-shell
|
|
@@ -187,15 +185,14 @@ authority. Delivery failure never clears the underlying hold.
|
|
|
187
185
|
Healthy watch observations remain quiet. The optional `axstack-monitor` is a
|
|
188
186
|
read-only observer for standalone watches and never sends.
|
|
189
187
|
|
|
190
|
-
##
|
|
188
|
+
## Optional native peer-review automation
|
|
191
189
|
|
|
192
|
-
The
|
|
193
|
-
|
|
194
|
-
fresh finite session in a new isolated workspace, scans complete
|
|
190
|
+
The optional native review manager runs at minutes `0,15,30,45`. Each
|
|
191
|
+
scheduled pass uses a fresh finite session in a new isolated workspace, scans complete
|
|
195
192
|
discovery pages, and admits eligible actionable PR events within measured host
|
|
196
|
-
capacity
|
|
197
|
-
owned descendants settle. Each job uses one repository-parented worktree;
|
|
198
|
-
PR branches in
|
|
193
|
+
capacity. Waiting PRs stay covered and consume no slot after
|
|
194
|
+
owned descendants settle. Each job uses one repository-parented worktree; the
|
|
195
|
+
manager never checks out PR branches in its own workspace.
|
|
199
196
|
|
|
200
197
|
Every pass reconciles saved, GitHub, and native Orca state across all same-lane
|
|
201
198
|
workspaces before admission. A
|
|
@@ -203,9 +200,10 @@ confirmed same-lane manager makes the new duplicate do no work or shared-record
|
|
|
203
200
|
write and close only itself. Normal teardown settles descendants, saves durable
|
|
204
201
|
continuity and decisions outside disposable workspaces, then retires its own
|
|
205
202
|
verified isolated pass workspace as the final action. It never bulk-closes a
|
|
206
|
-
shared manager workspace or a PR-job worktree, or cleans preserved
|
|
203
|
+
shared manager workspace or a PR-job worktree, or cleans preserved
|
|
207
204
|
evidence, user sessions, unknown liveness, `user_takeover`, or ambiguous
|
|
208
|
-
publication state. Manual review
|
|
205
|
+
publication state. Manual review and user-driven `axstack-watch` remain outside
|
|
206
|
+
this scheduled lifecycle.
|
|
209
207
|
|
|
210
208
|
One natively ordered successor may recover an exact positively completed
|
|
211
209
|
predecessor whose terminal survived, but only after matching its automation,
|
|
@@ -229,18 +227,17 @@ teardown pauses the lane; retained evidence or cleanup metadata does not consume
|
|
|
229
227
|
a slot after positive full-tree settlement. Once settled, an unchanged held
|
|
230
228
|
event remains deduplicated while unrelated eligible PRs continue.
|
|
231
229
|
|
|
232
|
-
Requested reviews cover any accessible repository
|
|
233
|
-
their `defi-com/monorepo` and `defi-com/mobile` scope. Orca owns schedules,
|
|
230
|
+
Requested peer reviews cover any accessible repository. Orca owns schedules,
|
|
234
231
|
sessions, Tasks, and Dispatches. Axstack adds no custom scheduler, queue engine,
|
|
235
232
|
cursor files, polling loop, or historical runtime fallback.
|
|
236
233
|
|
|
237
|
-
##
|
|
234
|
+
## Review automation
|
|
238
235
|
|
|
239
|
-
The review
|
|
240
|
-
relative contract and
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
decisions remain actionable in GitHub or a durable user-owned conversation
|
|
236
|
+
The review manager uses one short packaged prompt that loads the current
|
|
237
|
+
relative contract and invokes `axstack-review`. Bounded jobs publish ordinary
|
|
238
|
+
exact-head review verdicts; the human merges. Manual adopted-PR maintenance
|
|
239
|
+
uses `axstack-watch` with local-SHA review before authorized publication.
|
|
240
|
+
Exceptional security, permanent-on-chain, or architectural decisions remain actionable in GitHub or a durable user-owned conversation
|
|
244
241
|
after manager self-close, with an authorized deduplicated Telegram notification.
|
|
245
242
|
The current operational contract is
|
|
246
243
|
`skills/axstack/references/automations.md`.
|
package/package.json
CHANGED
|
@@ -1,17 +1,12 @@
|
|
|
1
|
-
# Native
|
|
1
|
+
# Native peer-review manager
|
|
2
2
|
|
|
3
|
-
Read this
|
|
3
|
+
Read this for the optional native Orca peer-review automation. The historical
|
|
4
4
|
automation specs and plans describe retired designs and are not instructions.
|
|
5
5
|
|
|
6
6
|
## Topology and schedules
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
- **Review manager:** runs at minutes `0,15,30,45` and invokes
|
|
11
|
-
[axstack-review](../../axstack-review/SKILL.md) for eligible peer reviews.
|
|
12
|
-
- **Watch manager:** runs at minutes `7,22,37,52` and invokes
|
|
13
|
-
[axstack-watch](../../axstack-watch/SKILL.md) for eligible own-PR watch or
|
|
14
|
-
repair events.
|
|
8
|
+
The review manager runs at minutes `0,15,30,45` and invokes
|
|
9
|
+
[axstack-review](../../axstack-review/SKILL.md) for eligible peer reviews.
|
|
15
10
|
|
|
16
11
|
Use a new isolated workspace for every scheduled pass, with one fresh finite
|
|
17
12
|
manager session. Configure native repo-created worktree mode against the
|
|
@@ -21,8 +16,8 @@ launch; the manager must not move itself from a shared launch workspace.
|
|
|
21
16
|
Keep lane continuity and evidence outside disposable manager workspaces at
|
|
22
17
|
the configured durable absolute paths. A manager never checks out a PR branch
|
|
23
18
|
in its pass workspace. Missed slots do not replay a backlog; the next ordinary pass
|
|
24
|
-
discovers current state. The
|
|
25
|
-
and
|
|
19
|
+
discovers current state. The short packaged review prompt sits beside this file
|
|
20
|
+
and discovers these rules by relative link instead of copying them.
|
|
26
21
|
|
|
27
22
|
Provision one explicit absolute continuity path per automation ID in the
|
|
28
23
|
scheduled prompt. Follow [Run record](run-record.md) for its contents; the
|
|
@@ -136,32 +131,26 @@ only when its body ends with
|
|
|
136
131
|
or a retained legacy receipt proves that provenance; otherwise never replace
|
|
137
132
|
it automatically.
|
|
138
133
|
|
|
139
|
-
The watch manager covers every open non-draft PR authored by self. It may
|
|
140
|
-
repair only `defi-com/monorepo` and `defi-com/mobile`; PRs elsewhere remain
|
|
141
|
-
observed but read-only. Preserve deploy-on-push exclusions, lowest-first stack
|
|
142
|
-
dependencies, and existing ownership boundaries. Peer code is always
|
|
143
|
-
read-only.
|
|
144
|
-
|
|
145
134
|
Coverage is not execution. Waiting for CI, a reviewer, a user decision, or a
|
|
146
135
|
merge occupies no execution slot after owned work and descendants settle.
|
|
147
|
-
|
|
136
|
+
Review waiting state never reserves a slot and no job stays active merely until a
|
|
148
137
|
PR merges or closes. Thirty open PRs, including ten settled waiting PRs, are
|
|
149
138
|
all scanned; those ten occupy zero slots.
|
|
150
139
|
|
|
151
140
|
## Admission and fairness
|
|
152
141
|
|
|
153
|
-
The review manager
|
|
142
|
+
The review manager admits all eligible actionable PR events
|
|
154
143
|
that measured host capacity can support across ticks. Before each admission,
|
|
155
|
-
inspect available memory, CPU load, and active worker trees across
|
|
144
|
+
inspect available memory, CPU load, and active worker trees across the host;
|
|
156
145
|
account for the whole proposed worker tree, dependencies, spending limits, and
|
|
157
146
|
exclusive ownership. Report unavailable metrics as unknown; use the remaining
|
|
158
147
|
host evidence rather than treating a missing metric alone as a blocker. Defer
|
|
159
148
|
an event when observed pressure or uncertain headroom cannot support its whole
|
|
160
149
|
tree, record the reason, and remeasure on the next pass. Do not use a fixed
|
|
161
|
-
PR-job count or reserve
|
|
150
|
+
PR-job count or reserve a fixed slot.
|
|
162
151
|
|
|
163
|
-
A slot covers one bounded PR event and remains occupied while its
|
|
164
|
-
|
|
152
|
+
A slot covers one bounded PR event and remains occupied while its reviewers
|
|
153
|
+
or other owned descendants are active or unsettled. Leaf workers do
|
|
165
154
|
not create recursive teams. Settlement of the PR job and every descendant
|
|
166
155
|
frees the slot even while the PR stays open.
|
|
167
156
|
|
|
@@ -180,7 +169,7 @@ writer for the same PR. Reuse an existing valid per-PR worktree, owner, and
|
|
|
180
169
|
unchanged receipts before creating anything. Otherwise create one separate
|
|
181
170
|
Orca worktree per PR job, parented to that repository's primary worktree, and
|
|
182
171
|
pin the observed head and base. The bounded PR coordinator loads the
|
|
183
|
-
|
|
172
|
+
review skill, launches only the reviewers that skill owns,
|
|
184
173
|
handles the current actionable event, returns exact receipts, then settles.
|
|
185
174
|
Settlement returns continuity to the manager rather than retaining an idle PR
|
|
186
175
|
coordinator. Reviewers retain the isolation required by `axstack-review`.
|
|
@@ -194,12 +183,12 @@ containment is uncertain.
|
|
|
194
183
|
|
|
195
184
|
An unchanged exact head and unchanged event identity creates no job; an
|
|
196
185
|
unchanged exact head with a new event identity remains actionable. Event
|
|
197
|
-
identity includes the applicable review ID and body digest,
|
|
198
|
-
|
|
186
|
+
identity includes the applicable review ID and body digest, request identity, or other current GitHub event
|
|
187
|
+
receipt. Dedupe from current GitHub state,
|
|
199
188
|
native Orca Task and Dispatch state, and the existing compact run record; do
|
|
200
189
|
not create machine cursor files or a queue engine. Record enough to resume: PR,
|
|
201
|
-
head, base, event identity, mode, owner and worker receipts,
|
|
202
|
-
|
|
190
|
+
head, base, event identity, mode, owner and worker receipts, verdict,
|
|
191
|
+
submission receipt, hold, and next action. GitHub remains authoritative for
|
|
203
192
|
open state, revisions, reviews, checks, and merge state.
|
|
204
193
|
|
|
205
194
|
## Held job settlement
|
|
@@ -236,10 +225,10 @@ lane before another pass can admit work rather than accumulating active passes
|
|
|
236
225
|
or claiming capacity from an uncertain process tree.
|
|
237
226
|
|
|
238
227
|
When the current event is handled, settle and release owned native resources.
|
|
239
|
-
Preserve dirty worktrees,
|
|
228
|
+
Preserve dirty worktrees, unarchived review evidence, pending
|
|
240
229
|
external results, and user-owned work until durability and ownership are
|
|
241
230
|
proven. Unknown liveness, `user_takeover`, and ambiguous publication likewise
|
|
242
|
-
forbid cleanup. Here a pending external result means an unconfirmed
|
|
231
|
+
forbid cleanup. Here a pending external result means an unconfirmed review submission
|
|
243
232
|
or send outcome, not pending CI. Waiting state belongs in GitHub and the compact
|
|
244
233
|
record, never in an idle model, per-PR timer, or polling loop.
|
|
245
234
|
Follow the [private evidence archive](evidence-archive.md) when evidence is the
|
|
@@ -251,7 +240,7 @@ read back the archive and compact receipt, then follow
|
|
|
251
240
|
the reviewer checkout before merge. This does not release active jobs or manager
|
|
252
241
|
pass workspaces.
|
|
253
242
|
|
|
254
|
-
## Review
|
|
243
|
+
## Review authority
|
|
255
244
|
|
|
256
245
|
Peer review follows `axstack-review` peer mode: two isolated configured
|
|
257
246
|
reviewers inspect the exact head and base. Complete review may publish the
|
|
@@ -269,21 +258,8 @@ private or local artifacts. Write the local HTML copy under the established
|
|
|
269
258
|
`review-PR-<num>.html` reserved for `defi-com/monorepo`. Never publish a
|
|
270
259
|
`COMMENT` review. An ambiguous submission is looked up before retry.
|
|
271
260
|
|
|
272
|
-
An own PR becomes actionable for repair only when a failing check has a base
|
|
273
|
-
check-run with the same name and producing app identity observed passing (or a
|
|
274
|
-
legacy status has the same context), or when a new current-head
|
|
275
|
-
`CHANGES_REQUESTED` review has both an unhandled review ID and an unhandled body
|
|
276
|
-
digest. Missing, pending, or same-name/different-app base evidence holds repair.
|
|
277
|
-
A new head or generic event grants no repair authority by itself.
|
|
278
|
-
|
|
279
|
-
Authorized own-PR repair follows `axstack-watch`: produce the smallest repair
|
|
280
|
-
in the per-PR worktree, obtain the actual-author-provenance reviewer pairing,
|
|
281
|
-
and publish only a reviewed fast-forward repair push after exact-current
|
|
282
|
-
candidate, head, base, event, allowlist, deploy, and remote readback receipts.
|
|
283
|
-
Reconcile an ambiguous review or push result before any retry.
|
|
284
|
-
|
|
285
261
|
No manager, coordinator, or worker may merge, close, force-push, rebase,
|
|
286
|
-
restack, broaden scope, or
|
|
262
|
+
restack, broaden scope, or mutate a PR branch. Human merge remains the
|
|
287
263
|
boundary.
|
|
288
264
|
|
|
289
265
|
## Exceptional decisions and notifications
|
|
@@ -314,7 +290,7 @@ self-close. Waiting PRs still occupy zero slots once their owned trees settle.
|
|
|
314
290
|
|
|
315
291
|
Cleanup of PR-job setup shells stays scoped to positively identified owned unused
|
|
316
292
|
setup shells: use the native exact-terminal close operation for each only.
|
|
317
|
-
Preserve dirty worktrees,
|
|
293
|
+
Preserve dirty worktrees, unarchived review evidence, user-owned
|
|
318
294
|
terminals, unknown liveness, `user_takeover`, and ambiguous publication state.
|
|
319
295
|
Never classify all dirt as evidence. If explicitly classified evidence is the
|
|
320
296
|
last retention reason, apply and verify the [private evidence archive](evidence-archive.md),
|
|
@@ -29,17 +29,3 @@ its required checks complete. Review may run in parallel with CI only after the
|
|
|
29
29
|
remote confirmation. Reviewers inspect a detached immutable checkout of the
|
|
30
30
|
confirmed candidate SHA and pinned base, never only the movable branch name.
|
|
31
31
|
Any author repair creates a new revision and repeats this boundary.
|
|
32
|
-
|
|
33
|
-
## Automation repair exception
|
|
34
|
-
|
|
35
|
-
For a manager PR repair under
|
|
36
|
-
[Native PR managers](automations.md), the candidate is a local immutable
|
|
37
|
-
commit SHA in the per-PR child worktree, not a published remote ref. The
|
|
38
|
-
reviewer confirms that exact local SHA with `git rev-parse` in the worktree
|
|
39
|
-
instead of remote equality, and inspects a detached checkout of it with the
|
|
40
|
-
pinned base. The remote ref is expected to still be the pre-repair head; record
|
|
41
|
-
it as the expected-old remote SHA rather than requiring it to equal the
|
|
42
|
-
candidate. Remote equality is re-checked at the publication readback of the
|
|
43
|
-
watch skill's repair-publication reference immediately before the fast-forward
|
|
44
|
-
push. Ordinary workflows keep the remote confirmation above; the
|
|
45
|
-
exception never applies outside a manager PR job.
|
|
@@ -17,8 +17,8 @@ binding state and receipts to exact revisions.
|
|
|
17
17
|
`axstack-reviewer-secondary` sessions with identical brief and isolated first
|
|
18
18
|
pass; authored = one eligible configured reviewer from actual author
|
|
19
19
|
provenance. Owner and author never review.
|
|
20
|
-
- Automation review
|
|
21
|
-
[
|
|
20
|
+
- Automation review manager and optional standalone monitor: see
|
|
21
|
+
[Review automation health](#review-automation-health).
|
|
22
22
|
- Auditor (`axstack-auditor`): report-only; never edits, merges, activates, or
|
|
23
23
|
audits itself.
|
|
24
24
|
|
|
@@ -99,21 +99,21 @@ On `consumer_fenced`, reconcile the active coordinator rather than borrowing an
|
|
|
99
99
|
identity. Respect settlement protection including `user_takeover`.
|
|
100
100
|
|
|
101
101
|
No execution heartbeat or substitute scheduler is created by Axstack. Native
|
|
102
|
-
|
|
102
|
+
review automation follows [Review automation health](#review-automation-health).
|
|
103
103
|
Tracking grants no merge, release, model-substitution, or scope authority.
|
|
104
104
|
|
|
105
105
|
## Deadline (one rule for every owned timer)
|
|
106
106
|
|
|
107
107
|
The default 24-hour deadline covers standalone task-owned timers. Stop them at
|
|
108
|
-
deadline and preserve remaining work;
|
|
109
|
-
|
|
108
|
+
deadline and preserve remaining work; the review automation has no task-owned
|
|
109
|
+
deadline. A PR is merge-ready only with the applicable review receipt(s) at
|
|
110
110
|
its exact head; green CI or tests alone never make it merge-ready. Merge-ready
|
|
111
111
|
differs from merged; human merges.
|
|
112
112
|
|
|
113
|
-
##
|
|
113
|
+
## Review automation health
|
|
114
114
|
|
|
115
|
-
|
|
116
|
-
workspaces on
|
|
115
|
+
The native review manager uses fresh finite sessions in isolated per-pass
|
|
116
|
+
workspaces on a 15-minute schedule. It admits eligible actionable PR
|
|
117
117
|
events within measured host capacity; waiting PRs remain covered without
|
|
118
118
|
reserving slots. Bounded PR jobs own their
|
|
119
119
|
events, use per-PR worktrees, and settle after descendants settle. Build no
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Simplify the diff
|
|
2
|
+
|
|
3
|
+
Load this reference only after the relevant checks are green and the candidate
|
|
4
|
+
contains code diffs or agent instructions. It does not apply to
|
|
5
|
+
general human-facing or marketing prose.
|
|
6
|
+
|
|
7
|
+
## Preserve behavior first
|
|
8
|
+
|
|
9
|
+
Simplify only when the same checked behavior and accepted scope remain intact.
|
|
10
|
+
Read the changed lines with their callers and local conventions; do not optimize
|
|
11
|
+
an isolated snippet while making the surrounding system harder to understand.
|
|
12
|
+
Re-run the check that established green after an applied simplification.
|
|
13
|
+
|
|
14
|
+
Look for complexity introduced or retained by the diff:
|
|
15
|
+
|
|
16
|
+
- speculative abstractions without a current second use;
|
|
17
|
+
- redundant narration that repeats what names or structure already say;
|
|
18
|
+
- unjustified defensive branches, fallback logic, or casts;
|
|
19
|
+
- needless wrappers or indirection;
|
|
20
|
+
- deep nesting that a guard clause or smaller direct operation can flatten; and
|
|
21
|
+
- convention mismatch where the repository already has a simpler pattern.
|
|
22
|
+
|
|
23
|
+
Prefer the smallest behavior-preserving change. Do not expand into nearby
|
|
24
|
+
cleanup, redesign stable interfaces, or trade explicit behavior for brevity.
|
|
25
|
+
|
|
26
|
+
## Keep necessary safeguards
|
|
27
|
+
|
|
28
|
+
Never remove complexity merely because it looks verbose. Preserve:
|
|
29
|
+
|
|
30
|
+
- trust-boundary validation and failure handling;
|
|
31
|
+
- accessibility text and interaction semantics;
|
|
32
|
+
- meaningful why-comments that capture a non-obvious constraint;
|
|
33
|
+
- explicit uncertainty instead of turning an unknown into a claim; and
|
|
34
|
+
- authority instructions, approval boundaries, and mutation limits.
|
|
35
|
+
|
|
36
|
+
When evidence cannot show that a change preserves behavior, retain it and name
|
|
37
|
+
the uncertainty. A justified `not-applicable` result is valid; there is no
|
|
38
|
+
deletion quota and no quality score.
|
|
39
|
+
|
|
40
|
+
## Receipt
|
|
41
|
+
|
|
42
|
+
Record one line for the exact candidate:
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
Simplification: <applied | not-applicable> — evidence: <diff locations and checks>; retained complexity: <necessary complexity and why>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
For `applied`, name the simplified locations and the green check rerun. For
|
|
49
|
+
`not-applicable`, name what was inspected and why no behavior-preserving
|
|
50
|
+
simplification was justified. The receipt is review evidence, not proof of live
|
|
51
|
+
model effectiveness and not an automatic gate.
|
|
@@ -79,6 +79,10 @@ counts with denominators plus the evidence behind the count:
|
|
|
79
79
|
evidence path is absent, or `UNKNOWN` with the reason when its records are
|
|
80
80
|
unavailable.
|
|
81
81
|
- Independent exact-revision review status and unresolved findings.
|
|
82
|
+
- Simplification applicability determinations evidenced / total candidate diffs,
|
|
83
|
+
and complete simplification receipts / total candidates, broken down as
|
|
84
|
+
`applied`, `not-applicable`, or `UNKNOWN` with the reason. This measures
|
|
85
|
+
applicability and completeness; it is not a quality score.
|
|
82
86
|
- Rework cycles with causes.
|
|
83
87
|
- Avoidable user interventions where records support the call, and no call where they do not.
|
|
84
88
|
- Parallelizable tasks identified versus dispatched, judged with dependency and writer isolation.
|
|
@@ -121,6 +121,15 @@ green evidence. For structure-preserving work, make only the accepted
|
|
|
121
121
|
structural edits and keep the unchanged baseline and equivalence evidence
|
|
122
122
|
green.
|
|
123
123
|
|
|
124
|
+
At this post-green refactor step, inspect the changed paths. When the candidate
|
|
125
|
+
contains a code diff or agent-instruction changes, load and follow
|
|
126
|
+
[Simplify the diff](../axstack/references/simplify-diff.md), then rerun affected
|
|
127
|
+
green checks after any edit. Do not load it for general human-facing or
|
|
128
|
+
marketing prose. Record the required evidence line whether simplification was
|
|
129
|
+
applied or found not applicable in the `Simplification:` line of the
|
|
130
|
+
[section 5 implementation receipt](#5-verify-and-return-the-candidate),
|
|
131
|
+
including evidence and retained complexity.
|
|
132
|
+
|
|
124
133
|
## 5. Verify and return the candidate
|
|
125
134
|
|
|
126
135
|
Run the acceptance checks and affected integration boundaries. Record commands,
|
|
@@ -138,6 +147,7 @@ Owner: <profile + session ID + worktree>
|
|
|
138
147
|
Scope: <approved spec + capability | small-change intent | maintenance snapshot>
|
|
139
148
|
Shape: <total> lines vs base <sha>; bulk: <buckets>; theme: <one line>
|
|
140
149
|
TDD: <normal red/green | structure-preserving old-green/same-check-new-green evidence>
|
|
150
|
+
Simplification: <applied | not-applicable> — evidence: <diff locations and checks>; retained complexity: <necessary complexity and why>
|
|
141
151
|
Acceptance: <checks + observed results>
|
|
142
152
|
Dependencies: <parent revisions or none>
|
|
143
153
|
Unverified: <boundaries + reasons>
|
|
@@ -5,7 +5,7 @@ description: When a candidate PR needs final review, use axstack-review for conf
|
|
|
5
5
|
|
|
6
6
|
# Review
|
|
7
7
|
|
|
8
|
-
Manual
|
|
8
|
+
Manual review keeps the user’s chat and workspace open.
|
|
9
9
|
|
|
10
10
|
Produce one evidence-bound verdict for an exact candidate revision using the
|
|
11
11
|
review count and model routing required by its mode. Report within the
|
|
@@ -21,7 +21,7 @@ Before reviewing, load [Standing contracts](../axstack/references/contracts.md),
|
|
|
21
21
|
then [Lifecycle and receipts](../axstack/references/lifecycle.md) so its required
|
|
22
22
|
audit edge remains active. Load [Shared routing](../axstack/references/routing.md)
|
|
23
23
|
to select the mode and scope identity, and apply the shared
|
|
24
|
-
[PR-shape policy](../axstack/references/pr-shape.md). For an owned candidate,
|
|
24
|
+
[PR-shape policy](../axstack/references/pr-shape.md). For an owned implementation candidate,
|
|
25
25
|
load and verify the
|
|
26
26
|
[candidate-publication boundary](../axstack/references/candidate-publication.md).
|
|
27
27
|
When the caller is a bounded review-manager PR job, load
|
|
@@ -89,17 +89,17 @@ owns the event and settles after its skill-owned reviewers settle.
|
|
|
89
89
|
|
|
90
90
|
## Review the candidate
|
|
91
91
|
|
|
92
|
-
1. **Pin the brief.** For an
|
|
93
|
-
candidate SHA before reviewer dispatch
|
|
94
|
-
instead the local immutable candidate SHA with `git rev-parse` in the
|
|
95
|
-
per-PR child worktree and pin the remote pre-repair head as the
|
|
96
|
-
expected-old remote SHA; remote equality is re-checked at the publication
|
|
97
|
-
readback, per the automation repair exception of the
|
|
92
|
+
1. **Pin the brief.** For an implementation candidate, verify remote confirmation
|
|
93
|
+
of the candidate SHA before reviewer dispatch under the
|
|
98
94
|
[candidate-publication boundary](../axstack/references/candidate-publication.md).
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
95
|
+
For manual adopted-PR maintenance under
|
|
96
|
+
[Repair and publication](../axstack-watch/references/repair-publication.md),
|
|
97
|
+
confirm the exact local candidate SHA with `git rev-parse` in the owned
|
|
98
|
+
worktree, pin the remote pre-repair head and current base, and review code and
|
|
99
|
+
reply bodies before publication. Record the PR URL, exact candidate SHA,
|
|
100
|
+
current base, applicable intent or spec/ticket identity and acceptance,
|
|
101
|
+
exclusions, authority, actual author provenance for authored mode, and all
|
|
102
|
+
six angles.
|
|
103
103
|
2. **Materialize the mode-required review.** Immediately before dispatch, read
|
|
104
104
|
[Orca runtime](../axstack/references/orca-runtime.md), then apply exactly one
|
|
105
105
|
branch below. For every reviewer, apply
|
|
@@ -174,6 +174,16 @@ owns the event and settles after its skill-owned reviewers settle.
|
|
|
174
174
|
existing material-scope, security, downtime,
|
|
175
175
|
data-loss, major-design-risk, or unavailable-model hold.
|
|
176
176
|
|
|
177
|
+
Also under angle 6, independently classify the pinned diff. When it contains
|
|
178
|
+
code or agent-instruction changes, load
|
|
179
|
+
[Simplify the diff](../axstack/references/simplify-diff.md) and independently
|
|
180
|
+
verify both the simplification receipt and the relevant diff; for excluded
|
|
181
|
+
prose, verify the receipt's `not-applicable` evidence without loading the
|
|
182
|
+
reference. A simplification finding names the concrete location, consequence,
|
|
183
|
+
and simpler behavior-preserving alternative. Preserve trust boundaries,
|
|
184
|
+
accessibility, meaningful why-comments, uncertainty, and authority; do not
|
|
185
|
+
turn this judgment into a deletion quota or score.
|
|
186
|
+
|
|
177
187
|
Verify the applicable spec, ticket, or intent acceptance, executable
|
|
178
188
|
evidence, exact candidate SHA, current base, and affected integration
|
|
179
189
|
boundary, plus rendered interaction evidence for relevant UI work. A
|
|
@@ -5,7 +5,7 @@ description: When babysitting an existing PR, use axstack-watch to monitor or ma
|
|
|
5
5
|
|
|
6
6
|
# Watch
|
|
7
7
|
|
|
8
|
-
Manual
|
|
8
|
+
Manual watch keeps the user’s chat and workspace open.
|
|
9
9
|
|
|
10
10
|
Leave each adopted PR with one accountable owner, current readiness evidence,
|
|
11
11
|
and user-facing updates that name its current milestone and next wake or
|
|
@@ -16,13 +16,6 @@ Its required edge loads [Shared lifecycle](../axstack/references/lifecycle.md),
|
|
|
16
16
|
including the end-of-run audit hook. Reach other references only at the steps
|
|
17
17
|
that name them.
|
|
18
18
|
|
|
19
|
-
When the current session is a fresh watch-manager session, load
|
|
20
|
-
[Native PR managers](../axstack/references/automations.md) and follow only its
|
|
21
|
-
discovery, admission, recovery, and settlement branch. Do not adopt or repair a
|
|
22
|
-
PR, materialize `axstack-owner`, or check out a PR branch in the manager
|
|
23
|
-
workspace. Each admitted bounded PR coordinator re-enters this skill in its
|
|
24
|
-
recorded mode.
|
|
25
|
-
|
|
26
19
|
Preserve any explicitly named PR, repository, or peer scope. For broad
|
|
27
20
|
discovery of the user's own PRs (such as “my” or “our” PRs), run
|
|
28
21
|
`gh api user --jq .login` on the execution host, then select open PRs authored
|
|
@@ -30,10 +23,6 @@ by that login in the named or current repository. Never hardcode or guess the
|
|
|
30
23
|
username; a missing or failed authenticated-login lookup is a concrete blocker.
|
|
31
24
|
The authenticated human login selects PRs. Runtime session IDs coordinate work
|
|
32
25
|
only and establish neither human identity nor write, reply, or merge authority.
|
|
33
|
-
When the session is a bounded watch-manager PR job, also load
|
|
34
|
-
[Native PR managers](../axstack/references/automations.md): the bounded PR
|
|
35
|
-
coordinator owns that event and its allowlist bounds every mutation.
|
|
36
|
-
|
|
37
26
|
## 1. Adopt and reconcile
|
|
38
27
|
|
|
39
28
|
Start from actual state. Reconcile the PR's remote head and base, ownership,
|
|
@@ -73,13 +62,9 @@ Read-only checks and updates to the already-owned local record need no runtime
|
|
|
73
62
|
load. When the watch needs a new owner or automated observation, first read
|
|
74
63
|
[Watch runtime](references/watch-runtime.md) and then
|
|
75
64
|
[Orca runtime](../axstack/references/orca-runtime.md). Reconcile before creating
|
|
76
|
-
anything.
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
there is no watch deadline for manager automation. `axstack-monitor` stays an
|
|
80
|
-
optional read-only observer that never sends. One read-only PR observation
|
|
81
|
-
needs neither. The bounded PR coordinator is the live owner for its event;
|
|
82
|
-
materialize no `axstack-owner` and start no automation for a read-only check.
|
|
65
|
+
anything. Task-owned observations use their recorded wakes and expiry.
|
|
66
|
+
`axstack-monitor` stays an optional read-only observer that never sends. One read-only PR observation
|
|
67
|
+
needs neither. Start no automation for a read-only check.
|
|
83
68
|
|
|
84
69
|
For standalone adoption, materialize `axstack-owner` only when no live owner
|
|
85
70
|
exists. Once it exists, the current chat is not a competing coordinator. Only
|
|
@@ -102,9 +87,7 @@ A healthy unchanged observation produces no user-facing message.
|
|
|
102
87
|
|
|
103
88
|
Observation-only and peer wakes produce a read-only report and stop. For an
|
|
104
89
|
authorized maintenance wake that may require a repair or public reply, read and
|
|
105
|
-
follow [Repair and publication](references/repair-publication.md).
|
|
106
|
-
job repairs in its per-PR child worktree created through `orca-cli`;
|
|
107
|
-
the manager workspace never checks out a PR branch.
|
|
90
|
+
follow [Repair and publication](references/repair-publication.md).
|
|
108
91
|
|
|
109
92
|
### Feedback routing
|
|
110
93
|
|
|
@@ -115,11 +98,9 @@ snapshot. Missing, stale, or materially changed identity holds repair routing
|
|
|
115
98
|
while monitoring continues. Accepted fixes return to the same original author
|
|
116
99
|
session only when the run itself launched that session and evidence allows,
|
|
117
100
|
then receive refreshed review under the authored mode rule before publication.
|
|
118
|
-
For an adopted own PR
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
pairing follows the recorded actual provenance of that repair, not the PR's
|
|
122
|
-
historical author. Unknown, mixed, or unsupported author provenance
|
|
101
|
+
For an adopted own PR, the authored-review pairing follows the recorded
|
|
102
|
+
actual provenance of its repair author, not the PR's historical author.
|
|
103
|
+
Unknown, mixed, or unsupported author provenance
|
|
123
104
|
that cannot establish the eligible configured reviewer is an exact gap to
|
|
124
105
|
report to the user, not permission to invent a pairing or model fallback.
|
|
125
106
|
|
|
@@ -128,9 +109,8 @@ the current revision, and a recorded hold or next owner where work remains.
|
|
|
128
109
|
|
|
129
110
|
When a new actionable event is eligible under a recorded `Notification policy`,
|
|
130
111
|
the owner may use the optional [axstack-relay](../axstack-relay/SKILL.md).
|
|
131
|
-
The monitor never sends.
|
|
132
|
-
|
|
133
|
-
conversation and leaves every existing hold open.
|
|
112
|
+
The monitor never sends. Deduplicate authorized notifications; absent policy
|
|
113
|
+
or failed relay uses the current Orca conversation and leaves the existing hold open.
|
|
134
114
|
|
|
135
115
|
## 5. State readiness precisely
|
|
136
116
|
|
|
@@ -141,14 +121,9 @@ observed state distinct from merged, and the human merges by default.
|
|
|
141
121
|
|
|
142
122
|
## 6. End and preserve continuity
|
|
143
123
|
|
|
144
|
-
A bounded manager PR job ends as soon as its current event and every owned
|
|
145
|
-
descendant settle. It returns exact receipts and remaining state to the logical
|
|
146
|
-
manager lane's durable continuity, releases proven resources, and never waits
|
|
147
|
-
for merge or stops the manager's recurring schedule.
|
|
148
|
-
|
|
149
124
|
End a standalone watch early when all required PRs merge, at cancellation, or
|
|
150
|
-
at its shared default 24 h deadline.
|
|
151
|
-
|
|
125
|
+
at its shared default 24 h deadline. In every case, stop all owned
|
|
126
|
+
registrations and verify their receipts.
|
|
152
127
|
|
|
153
128
|
At every end condition, leave the compact state below in the private run record
|
|
154
129
|
and report it in the current chat, even when work remains. Expiry grants neither
|
|
@@ -8,9 +8,7 @@ and peer modes stop with a report before this branch.
|
|
|
8
8
|
Re-read the accepted maintenance snapshot, writable ownership, publication
|
|
9
9
|
authority, remote head and base, and current feedback. Route an accepted fix to
|
|
10
10
|
the original author session only when the run itself launched that session and
|
|
11
|
-
evidence permits.
|
|
12
|
-
the manager PR coordinator or a dispatched `axstack-author`; record that
|
|
13
|
-
repair's actual provenance before
|
|
11
|
+
evidence permits. Record the repair author's actual provenance before
|
|
14
12
|
selecting the reviewer, because the authored-review pairing follows the actual
|
|
15
13
|
provenance of the repair, never the PR's historical author. A missing,
|
|
16
14
|
stale, or materially changed boundary holds the repair while read-only
|
|
@@ -25,20 +23,22 @@ the importing owner or orchestrator.
|
|
|
25
23
|
## 2. Produce a reviewable candidate
|
|
26
24
|
|
|
27
25
|
The author prepares the smallest in-scope repair and the exact public reply
|
|
28
|
-
bodies, each keyed to its feedback ID and bound to the candidate revision.
|
|
29
|
-
candidate is committed locally in the
|
|
30
|
-
|
|
26
|
+
bodies, each keyed to its feedback ID and bound to the candidate revision.
|
|
27
|
+
The candidate is committed locally in the owned worktree. Obtain an
|
|
28
|
+
independent review of the exact local candidate SHA in an isolated detached
|
|
29
|
+
checkout against the pinned base, including the exact reply bodies, before
|
|
30
|
+
publication; nothing is pushed for review. Both code and
|
|
31
31
|
reply bodies receive the one complete eligible non-author/non-owner review
|
|
32
32
|
required by the authored review rule in `axstack-review`.
|
|
33
33
|
|
|
34
34
|
Publication stays held until the current authored review receipt covers the
|
|
35
35
|
exact new revision and base, all six angles, applicable acceptance, the reply
|
|
36
36
|
body identities, and every affected boundary, with no unresolved material
|
|
37
|
-
finding or urgent hold.
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
37
|
+
finding or urgent hold. A serious-risk escalation preserves the local candidate
|
|
38
|
+
and exact context, records the hold in the run record and a durable GitHub or
|
|
39
|
+
user-owned conversation, and sends only an authorized deduplicated notification.
|
|
40
|
+
Publication remains held until the user decides at that durable location and
|
|
41
|
+
all exact inputs are revalidated.
|
|
42
42
|
|
|
43
43
|
## 3. Revalidate immediately before publication
|
|
44
44
|
|
|
@@ -51,15 +51,11 @@ readback.
|
|
|
51
51
|
|
|
52
52
|
## 4. Publish idempotently
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
After the local review and final remote revalidation, publish through `gh stack`
|
|
55
|
+
for the adopted PR only, preserving unrelated stack entries.
|
|
55
56
|
Bind the operation to the exact reviewed revision, then verify the submission
|
|
56
57
|
receipt and remote state.
|
|
57
58
|
|
|
58
|
-
Manager automation pushes fast-forward only: run the section 3 publication
|
|
59
|
-
readback immediately before the push, then `git push` to the PR branch with no
|
|
60
|
-
lease or force, and no `gh stack` sync or restack from a manager. A
|
|
61
|
-
non-fast-forward remote is a recorded hold, never a rewrite.
|
|
62
|
-
|
|
63
59
|
If the send outcome is unknown, inspect remote IDs, bodies, and actor before any
|
|
64
60
|
retry. Remain blocked while the outcome is ambiguous; retry only after
|
|
65
61
|
confirming the intended operation is absent.
|
|
@@ -10,32 +10,3 @@ current GitHub state, persists event IDs, wakes the owner only for a new
|
|
|
10
10
|
actionable event, and never sends or mutates. Healthy observations update
|
|
11
11
|
quietly. Reuse prior watch identity rather than registering a duplicate, and
|
|
12
12
|
stop task-owned registrations at completion, cancellation, or expiry.
|
|
13
|
-
|
|
14
|
-
## Native watch manager
|
|
15
|
-
|
|
16
|
-
The separate native watch manager lane follows the
|
|
17
|
-
[native PR-manager contract](../../axstack/references/automations.md). Each pass
|
|
18
|
-
uses a new isolated workspace and fresh finite session at minutes `7,22,37,52`.
|
|
19
|
-
Continuity survives outside disposable workspaces; admission reconciles the
|
|
20
|
-
whole lane across workspaces. It scans every eligible own PR and
|
|
21
|
-
admits bounded actionable-event jobs within measured host capacity. Waiting PRs
|
|
22
|
-
stay covered without reserving slots. Each job uses its own repository-parented worktree and
|
|
23
|
-
settles with all descendants; no model, per-PR timer, or polling loop waits for
|
|
24
|
-
CI, review, a user decision, or merge.
|
|
25
|
-
|
|
26
|
-
Load the version-matched Orca automation and orchestration guidance through the
|
|
27
|
-
shared [runtime boundary](../../axstack/references/orca-runtime.md). Requested
|
|
28
|
-
settings or source configuration are not runtime evidence. Preserve quiet
|
|
29
|
-
unchanged behavior, exact-head event dedupe, ownership, complete discovery,
|
|
30
|
-
and current authority.
|
|
31
|
-
|
|
32
|
-
Before activation, canary fresh-session launch, an overlapping scheduled pass,
|
|
33
|
-
session loss and recovery, nested dispatch depth for coordinator-launched leaves, and
|
|
34
|
-
total process and memory behavior. Until observed, those remain unverified; do
|
|
35
|
-
not replace them with a precheck, watchdog, custom scheduler, state engine, or
|
|
36
|
-
legacy fallback.
|
|
37
|
-
|
|
38
|
-
On recovery reconcile actual native workers, GitHub, and the compact run record
|
|
39
|
-
before admitting work. Unknown state blocks only the affected PR. At every job
|
|
40
|
-
end, settle owned workers, preserve unsafe or user-owned state, release proven
|
|
41
|
-
resources, and leave exact resumable receipts.
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
# Watch manager prompt
|
|
2
|
-
|
|
3
|
-
You are a fresh finite watch-manager session in its isolated per-pass Orca workspace. Enter
|
|
4
|
-
through the installed `axstack-watch` skill; that skill loads its packaged
|
|
5
|
-
`../axstack/references/automations.md` contract by relative reference. Discover
|
|
6
|
-
every eligible own-PR event and invoke the skill through Orca for each admitted
|
|
7
|
-
bounded PR job. Keep complete coverage and admit actionable events within
|
|
8
|
-
measured host capacity, preserve exact ownership, candidates, holds, and receipts,
|
|
9
|
-
settle completed trees, and stay quiet when nothing changed. Reconcile before
|
|
10
|
-
admission, save durable continuity outside this workspace, then retire only this
|
|
11
|
-
pass workspace as the final action under the contract's ownership guards.
|
|
12
|
-
Reconcile the whole lane, not just this workspace. Never check out a PR branch here.
|