agent-steward 0.0.4 → 0.0.6
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/CHANGELOG.md +309 -2
- package/CROSS_PLATFORM.md +19 -0
- package/README.md +55 -8
- package/ROADMAP-STRATEGY.md +22 -19
- package/ROADMAP.md +230 -159
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +356 -0
- package/dist/core/analytics.d.ts +6 -0
- package/dist/core/analytics.d.ts.map +1 -1
- package/dist/core/analytics.js +20 -3
- package/dist/core/audit.d.ts +6 -0
- package/dist/core/audit.d.ts.map +1 -1
- package/dist/core/audit.js +24 -0
- package/dist/core/budget.d.ts +118 -0
- package/dist/core/budget.d.ts.map +1 -0
- package/dist/core/budget.js +206 -0
- package/dist/core/cron-to-schtasks.d.ts.map +1 -1
- package/dist/core/cron-to-schtasks.js +38 -0
- package/dist/core/dry-run.d.ts +26 -1
- package/dist/core/dry-run.d.ts.map +1 -1
- package/dist/core/dry-run.js +199 -8
- package/dist/core/execution.d.ts +203 -0
- package/dist/core/execution.d.ts.map +1 -0
- package/dist/core/execution.js +309 -0
- package/dist/core/feedback.d.ts +192 -0
- package/dist/core/feedback.d.ts.map +1 -0
- package/dist/core/feedback.js +426 -0
- package/dist/core/gate-integrity.d.ts +71 -0
- package/dist/core/gate-integrity.d.ts.map +1 -0
- package/dist/core/gate-integrity.js +275 -0
- package/dist/core/git-trigger.d.ts.map +1 -1
- package/dist/core/git-trigger.js +14 -2
- package/dist/core/guard-run.d.ts +4 -0
- package/dist/core/guard-run.d.ts.map +1 -0
- package/dist/core/guard-run.js +101 -0
- package/dist/core/guard.d.ts +52 -0
- package/dist/core/guard.d.ts.map +1 -0
- package/dist/core/guard.js +362 -0
- package/dist/core/local-ai.d.ts.map +1 -1
- package/dist/core/local-ai.js +7 -3
- package/dist/core/lock.d.ts +41 -0
- package/dist/core/lock.d.ts.map +1 -1
- package/dist/core/lock.js +141 -29
- package/dist/core/matrix.d.ts +8 -0
- package/dist/core/matrix.d.ts.map +1 -1
- package/dist/core/matrix.js +132 -17
- package/dist/core/mission.d.ts +103 -0
- package/dist/core/mission.d.ts.map +1 -0
- package/dist/core/mission.js +374 -0
- package/dist/core/opencode-models.d.ts +2 -2
- package/dist/core/opencode-models.d.ts.map +1 -1
- package/dist/core/opencode-models.js +28 -21
- package/dist/core/opencode-usage.d.ts +35 -0
- package/dist/core/opencode-usage.d.ts.map +1 -0
- package/dist/core/opencode-usage.js +132 -0
- package/dist/core/pipeline-apply.d.ts +38 -0
- package/dist/core/pipeline-apply.d.ts.map +1 -0
- package/dist/core/pipeline-apply.js +117 -0
- package/dist/core/pipeline-io.d.ts +13 -0
- package/dist/core/pipeline-io.d.ts.map +1 -0
- package/dist/core/pipeline-io.js +78 -0
- package/dist/core/pipeline-map.d.ts +52 -0
- package/dist/core/pipeline-map.d.ts.map +1 -0
- package/dist/core/pipeline-map.js +208 -0
- package/dist/core/pipeline-spec.d.ts +109 -0
- package/dist/core/pipeline-spec.d.ts.map +1 -0
- package/dist/core/pipeline-spec.js +554 -0
- package/dist/core/ps-wrapper.d.ts +27 -2
- package/dist/core/ps-wrapper.d.ts.map +1 -1
- package/dist/core/ps-wrapper.js +424 -65
- package/dist/core/record-history.d.ts.map +1 -1
- package/dist/core/record-history.js +206 -33
- package/dist/core/router/rules.d.ts.map +1 -1
- package/dist/core/router/rules.js +6 -0
- package/dist/core/run-mode.d.ts +12 -0
- package/dist/core/run-mode.d.ts.map +1 -0
- package/dist/core/run-mode.js +17 -0
- package/dist/core/scheduler/linux.d.ts +8 -1
- package/dist/core/scheduler/linux.d.ts.map +1 -1
- package/dist/core/scheduler/linux.js +34 -9
- package/dist/core/scheduler/logs.d.ts +4 -0
- package/dist/core/scheduler/logs.d.ts.map +1 -1
- package/dist/core/scheduler/logs.js +25 -1
- package/dist/core/scheduler/mac.d.ts +44 -2
- package/dist/core/scheduler/mac.d.ts.map +1 -1
- package/dist/core/scheduler/mac.js +126 -15
- package/dist/core/scheduler/windows.d.ts.map +1 -1
- package/dist/core/scheduler/windows.js +15 -12
- package/dist/core/secrets.d.ts.map +1 -1
- package/dist/core/secrets.js +18 -8
- package/dist/core/self-analysis.d.ts +32 -2
- package/dist/core/self-analysis.d.ts.map +1 -1
- package/dist/core/self-analysis.js +38 -27
- package/dist/core/shutdown.d.ts +33 -2
- package/dist/core/shutdown.d.ts.map +1 -1
- package/dist/core/shutdown.js +58 -2
- package/dist/core/structured-log.d.ts +37 -1
- package/dist/core/structured-log.d.ts.map +1 -1
- package/dist/core/structured-log.js +37 -0
- package/dist/core/usage-surface.d.ts +25 -0
- package/dist/core/usage-surface.d.ts.map +1 -0
- package/dist/core/usage-surface.js +41 -0
- package/dist/core/worktree-run.d.ts +4 -0
- package/dist/core/worktree-run.d.ts.map +1 -0
- package/dist/core/worktree-run.js +164 -0
- package/dist/core/worktree.d.ts +115 -0
- package/dist/core/worktree.d.ts.map +1 -0
- package/dist/core/worktree.js +462 -0
- package/dist/core/wrappers/bash.d.ts +19 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -1
- package/dist/core/wrappers/bash.js +230 -27
- package/dist/db/capability-repo.d.ts +43 -2
- package/dist/db/capability-repo.d.ts.map +1 -1
- package/dist/db/capability-repo.js +96 -11
- package/dist/db/history-repo.d.ts +70 -5
- package/dist/db/history-repo.d.ts.map +1 -1
- package/dist/db/history-repo.js +170 -29
- package/dist/db/metrics-repo.d.ts +20 -2
- package/dist/db/metrics-repo.d.ts.map +1 -1
- package/dist/db/metrics-repo.js +35 -13
- package/dist/db/migrate.d.ts.map +1 -1
- package/dist/db/migrate.js +37 -17
- package/dist/db/recovery.d.ts +3 -1
- package/dist/db/recovery.d.ts.map +1 -1
- package/dist/db/recovery.js +11 -5
- package/dist/db/run-journal.d.ts +33 -5
- package/dist/db/run-journal.d.ts.map +1 -1
- package/dist/db/run-journal.js +78 -14
- package/dist/db/run-resume.d.ts +5 -0
- package/dist/db/run-resume.d.ts.map +1 -1
- package/dist/db/run-resume.js +9 -2
- package/dist/db/runs-repo.d.ts +19 -2
- package/dist/db/runs-repo.d.ts.map +1 -1
- package/dist/db/runs-repo.js +91 -60
- package/dist/db/schema.d.ts +2 -2
- package/dist/db/schema.d.ts.map +1 -1
- package/dist/db/schema.js +132 -2
- package/dist/db/templates-repo.d.ts +2 -2
- package/dist/db/templates-repo.d.ts.map +1 -1
- package/dist/db/templates-repo.js +5 -3
- package/dist/history.d.ts +7 -2
- package/dist/history.d.ts.map +1 -1
- package/dist/history.js +4 -2
- package/dist/hook-output.d.ts +2 -0
- package/dist/hook-output.d.ts.map +1 -0
- package/dist/hook-output.js +31 -0
- package/dist/i18n.d.ts +5 -0
- package/dist/i18n.d.ts.map +1 -1
- package/dist/i18n.js +11 -4
- package/dist/index.d.ts +375 -47
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1344 -192
- package/dist/notifications.d.ts +53 -2
- package/dist/notifications.d.ts.map +1 -1
- package/dist/notifications.js +168 -21
- package/dist/profiles.d.ts.map +1 -1
- package/dist/profiles.js +82 -10
- package/dist/rpc.d.ts +354 -0
- package/dist/rpc.d.ts.map +1 -1
- package/dist/rpc.js +145 -0
- package/dist/server.d.ts +32 -2
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +154 -30
- package/dist/settings.d.ts +44 -2
- package/dist/settings.d.ts.map +1 -1
- package/dist/settings.js +85 -3
- package/dist/shared/jobs-view.d.ts +1 -1
- package/dist/shared/jobs-view.d.ts.map +1 -1
- package/dist/shared/jobs-view.js +2 -0
- package/dist/task-transfer.d.ts +21 -0
- package/dist/task-transfer.d.ts.map +1 -1
- package/dist/task-transfer.js +64 -3
- package/dist/templates.d.ts +2 -2
- package/dist/templates.d.ts.map +1 -1
- package/dist/templates.js +3 -3
- package/dist/types.d.ts +22 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/workspaces.d.ts.map +1 -1
- package/dist/workspaces.js +34 -11
- package/docs/ARCHITECTURE.md +319 -66
- package/docs/COMPATIBILITY.md +2 -2
- package/docs/CONCEPT.md +18 -4
- package/docs/CROSS_PLATFORM.ru.md +20 -0
- package/docs/CROSS_PLATFORM.zh.md +18 -0
- package/docs/EXECUTION-LOOP.md +28 -10
- package/docs/FEATURES.md +129 -7
- package/docs/FEATURES.zh.md +97 -6
- package/docs/MIGRATION.md +2 -2
- package/docs/PIPELINE.md +293 -0
- package/docs/QA-A2-GUI-TUI.md +205 -0
- package/docs/README.ru.md +43 -4
- package/docs/README.zh.md +44 -4
- package/docs/SAFETY.md +23 -3
- package/gui-experimental.cjs +9 -8
- package/locales/en.json +58 -3
- package/locales/ru.json +58 -3
- package/locales/zh.json +58 -3
- package/opencode.pipeline.yaml +35 -0
- package/package.json +36 -4
- package/scripts/check-eslint-baseline.mjs +139 -0
- package/scripts/gen-test-plan-counters.mjs +117 -0
- package/scripts/github-ci-fetch.ps1 +37 -0
- package/scripts/pl-commit.ps1 +112 -0
- package/scripts/qa-a2-commit.ps1 +104 -0
- package/scripts/test-home.mjs +107 -0
- package/skills/scheduled-job-best-practices/SKILL.md +95 -1
- package/skills/scheduled-job-best-practices/references/recipes.md +139 -0
- package/src/cli.ts +417 -0
- package/src/core/analytics.ts +27 -4
- package/src/core/audit.ts +25 -0
- package/src/core/budget.ts +340 -0
- package/src/core/cron-to-schtasks.ts +42 -0
- package/src/core/dry-run.ts +235 -12
- package/src/core/execution.ts +538 -0
- package/src/core/feedback.ts +582 -0
- package/src/core/file-watcher.ts +2 -2
- package/src/core/gate-integrity.ts +330 -0
- package/src/core/git-trigger.ts +18 -5
- package/src/core/guard-run.ts +119 -0
- package/src/core/guard.ts +431 -0
- package/src/core/local-ai.ts +7 -3
- package/src/core/lock.ts +178 -37
- package/src/core/matrix.ts +158 -52
- package/src/core/mission.ts +531 -0
- package/src/core/native-notify.ts +1 -1
- package/src/core/opencode-models.ts +30 -21
- package/src/core/opencode-usage.ts +182 -0
- package/src/core/pipeline-apply.ts +158 -0
- package/src/core/pipeline-io.ts +96 -0
- package/src/core/pipeline-map.ts +283 -0
- package/src/core/pipeline-spec.ts +775 -0
- package/src/core/ps-wrapper.ts +435 -66
- package/src/core/record-history.ts +258 -81
- package/src/core/router/rules.ts +6 -0
- package/src/core/run-mode.ts +19 -0
- package/src/core/schedule-gate.ts +1 -1
- package/src/core/scheduler/at-fallback.ts +1 -1
- package/src/core/scheduler/linux.ts +40 -11
- package/src/core/scheduler/logs.ts +34 -3
- package/src/core/scheduler/mac.ts +174 -14
- package/src/core/scheduler/registry.ts +2 -2
- package/src/core/scheduler/windows.ts +19 -15
- package/src/core/secrets.ts +26 -19
- package/src/core/self-analysis.ts +75 -29
- package/src/core/shutdown.ts +90 -4
- package/src/core/structured-log.ts +89 -5
- package/src/core/telegram.ts +2 -2
- package/src/core/triage-worker.ts +7 -7
- package/src/core/triage.ts +2 -2
- package/src/core/usage-surface.ts +70 -0
- package/src/core/worktree-run.ts +199 -0
- package/src/core/worktree.ts +600 -0
- package/src/core/wrappers/bash.ts +248 -26
- package/src/db/capability-repo.ts +127 -10
- package/src/db/history-repo.ts +281 -40
- package/src/db/metrics-repo.ts +40 -13
- package/src/db/migrate.ts +57 -32
- package/src/db/recovery.ts +12 -5
- package/src/db/run-journal.ts +100 -13
- package/src/db/run-resume.ts +17 -1
- package/src/db/runs-repo.ts +147 -65
- package/src/db/schema.ts +134 -2
- package/src/db/templates-repo.ts +5 -3
- package/src/gui.tsx +438 -18
- package/src/history.ts +11 -4
- package/src/hook-output.ts +39 -0
- package/src/i18n.ts +12 -4
- package/src/index.ts +1902 -320
- package/src/notifications.ts +227 -47
- package/src/profiles.ts +88 -10
- package/src/rpc.ts +158 -0
- package/src/server.ts +201 -41
- package/src/settings.ts +125 -5
- package/src/shared/jobs-view.ts +3 -1
- package/src/task-transfer.ts +90 -6
- package/src/templates.ts +3 -3
- package/src/types.ts +23 -2
- package/src/workspaces.ts +37 -14
|
@@ -30,10 +30,40 @@ summary, last run.
|
|
|
30
30
|
| "Same work in N repositories" | `matrix.workspaceIds` | One definition, isolated clones, aggregated status |
|
|
31
31
|
| "A then B then C" | `dependsOn` + `nextTaskOnSuccess` / `nextTaskOnError` | Explicit DAG, failures stop the line |
|
|
32
32
|
| "Try again if it fails" | `retryCount` + `retryDelay` | Handles flaky networks and rate limits |
|
|
33
|
+
| "Once a month / once a year" | `schedule_task` with `M H D M *` | Native `MONTHLY` (with `/m` for a fixed month), no minute polling |
|
|
34
|
+
|
|
35
|
+
**Cron-to-OS limitation (QV-10).** Windows Task Scheduler expresses `MINUTE`,
|
|
36
|
+
`HOURLY`, `DAILY`, `WEEKLY` and `MONTHLY`. Expressions outside this subset (lists,
|
|
37
|
+
ranges, `*/N` on day-of-month/weekday, a foreign IANA timezone) fall back to a
|
|
38
|
+
one-minute OS poll with a schedule gate in the wrapper. A yearly cron such as
|
|
39
|
+
`0 4 1 1 *` is now converted natively to `MONTHLY /d 1 /m JANUARY /st 04:00`,
|
|
40
|
+
so the OS does not tick every minute for a task that runs once a year.
|
|
41
|
+
|
|
42
|
+
`triggerType: "mcp-event"` (as well as `file`/`git`) is event-driven, but it **still
|
|
43
|
+
registers an enabled OS placeholder entry**: `ONCE 31.12.2099 00:00`, Status `Ready`
|
|
44
|
+
(`src/core/scheduler/windows.ts`, the non-cron branch). The OS never fires it on its own;
|
|
45
|
+
the entry exists only so manual start (`schtasks /run`), DAG dependencies and `runMatrix`
|
|
46
|
+
have an OS object to run, and it is removed together with the task by `delete_task`.
|
|
47
|
+
A fresh task `QV1-live-mcp-os-probe` with `mcpEvent:{server:'qv1probe',event:'qv1.live.probe'}`
|
|
48
|
+
was verified in `schtasks` on 20.11.2026 (QV-1) — the `31.12.2099` date is intentional,
|
|
49
|
+
not an artifact of a paused task.
|
|
50
|
+
|
|
51
|
+
**Child run surface (QV-8).** The task wrapper exports `AGENT_STEWARD_CHILD_RUN=1`
|
|
52
|
+
before `opencode run` (PowerShell restores the previous value in `finally`). When the
|
|
53
|
+
plugin is loaded with that marker it skips V2/V1 registration: no scheduler tools, RPC,
|
|
54
|
+
skill or dashboard in the child process. A controlled check measured the tool registry at
|
|
55
|
+
30 tools in the parent vs 0 in child mode. This prevents a scheduled agent from seeing
|
|
56
|
+
the same 30 tools recursively and racing the parent for the dashboard port.
|
|
33
57
|
|
|
34
58
|
Do not use a 5-field cron for a one-off reminder. Do not build a pipeline with chained
|
|
35
59
|
prompts inside a single task when `dependsOn` exists: a failed step would be invisible.
|
|
36
60
|
|
|
61
|
+
**Task names (PL-9.1).** `schedule_task` validates the name: letters (including Cyrillic),
|
|
62
|
+
digits, space, dot, underscore and an **ASCII hyphen `-`** are allowed. The em dash `—`
|
|
63
|
+
and round brackets `()` are **rejected**. Rewrite the title with words and `-` before
|
|
64
|
+
creating the task so the original name is not silently replaced:
|
|
65
|
+
`QA-A2 - Full plugin typing epic`, not `Задача QA-A2 — Полная типизация (эпик)`.
|
|
66
|
+
|
|
37
67
|
## 3. Write prompts that survive without context
|
|
38
68
|
|
|
39
69
|
Every run starts from a clean slate: no chat history, no memory of the previous run, nobody
|
|
@@ -53,6 +83,35 @@ reports/nightly-api.md with the failing test names and the commit you started fr
|
|
|
53
83
|
Never ask the agent to "ask the user" in a scheduled prompt — nobody is there. If a decision
|
|
54
84
|
is genuinely ambiguous, tell it to stop and write the question into the report.
|
|
55
85
|
|
|
86
|
+
### Prompt template for planning-document updates (PL-3.1)
|
|
87
|
+
|
|
88
|
+
When a prompt asks the agent to close tasks in `ROADMAP.md`, keep `TEST-PLAN.md` or
|
|
89
|
+
write a CHANGELOG entry, put the exact line format and the artifact checklist into
|
|
90
|
+
the prompt itself — do not rely on the agent to guess them:
|
|
91
|
+
|
|
92
|
+
````text
|
|
93
|
+
Roadmap line format (copy verbatim, one line per closed subtask):
|
|
94
|
+
- [x] <ID> <title>: <files> — <P0|P1|P2|P3>. Действие: <what to do>
|
|
95
|
+
|
|
96
|
+
Rule: wrap every EXISTING file path in backticks, e.g.
|
|
97
|
+
- [x] TP-6 test plan gate: `test-test-plan.mjs`, `scripts/gen-test-plan-counters.mjs` — P3. Действие: ...
|
|
98
|
+
Never invent a file: a path that does not exist must not appear as an artifact and must
|
|
99
|
+
not be given backticks. Verify each path before writing the line.
|
|
100
|
+
|
|
101
|
+
Artifact checklist (copy into the prompt and tick before reporting done):
|
|
102
|
+
- [ ] ROADMAP.md: closed lines removed (or [x] only if the doc explicitly keeps them),
|
|
103
|
+
no duplicate of a closed ID remains.
|
|
104
|
+
- [ ] CHANGELOG.md: one entry per closed detail/subtask with the ID and the result.
|
|
105
|
+
- [ ] TEST-PLAN.md: §5 row for each existing `test-*.mjs`, filename in backticks;
|
|
106
|
+
no row for a missing file; counters match the code.
|
|
107
|
+
- [ ] reports/<name>.md: report written with statuses, verification commands and results.
|
|
108
|
+
- [ ] Verification commands actually run (build / target test / lint baseline).
|
|
109
|
+
````
|
|
110
|
+
|
|
111
|
+
This is the concrete form of items 4–5 above: "Verification" and "Output" must be
|
|
112
|
+
machine-checkable, not a wish. A line for a non-existent `test-feedback.mjs` is worse
|
|
113
|
+
than a missing line, because the gate then checks a file that will never appear.
|
|
114
|
+
|
|
56
115
|
## 4. Safety defaults
|
|
57
116
|
|
|
58
117
|
- **Least privilege**: the default `hybrid` policy already denies `shell` and `question`; keep it
|
|
@@ -60,6 +119,12 @@ is genuinely ambiguous, tell it to stop and write the question into the report.
|
|
|
60
119
|
for `shell` just to run `git commit`, a build or tests — put those in `qualityGate`/`afterScript`,
|
|
61
120
|
which the wrapper runs outside the agent. If a job truly needs shell, list `shell` in
|
|
62
121
|
`allowedTools` (or set `legacyShell: true` for a migrated task) and explain why.
|
|
122
|
+
- **Self-check prompts (PL-2.1/PL-2.2)**: decide the tool policy at creation time. If the prompt
|
|
123
|
+
says "run `node`", "`npm test`", "`pytest`" or otherwise verifies its own work, then either put
|
|
124
|
+
`shell` into `allowedTools` immediately, or move every such check into `qualityGate`/`afterScript`
|
|
125
|
+
so the wrapper runs it. Leaving shell denied while demanding a self-check produces
|
|
126
|
+
`tool.blocked` in the audit log and a "verified" report that verified nothing. `dry_run` warns
|
|
127
|
+
about this combination.
|
|
63
128
|
- **Timeout**: always set `timeoutSeconds` for jobs that call networks or models. Default
|
|
64
129
|
timeouts are a safety net, not a plan.
|
|
65
130
|
- **Quality Gate**: pass `qualityGate` whenever a machine-checkable success criterion exists
|
|
@@ -102,6 +167,24 @@ Rules of thumb:
|
|
|
102
167
|
starts.
|
|
103
168
|
- `nextTaskOnSuccess` / `nextTaskOnError` chain a single follow-up run; use them for
|
|
104
169
|
notifications and rollbacks.
|
|
170
|
+
- **One transition, one mechanism (PL-5.1/PL-5.2).** For a linear `A → B` step use
|
|
171
|
+
**either** `A.nextTaskOnSuccess = "B"` **or** `B.dependsOn = ["A"]`, never both.
|
|
172
|
+
If both describe the same transition, `B` is triggered twice when `A` finishes — once
|
|
173
|
+
as the chain target and once as a DAG dependent — producing duplicate runs. `dry_run`
|
|
174
|
+
warns about this overlap, and the recorder now de-duplicates targets by name, but the
|
|
175
|
+
configuration itself should be fixed.
|
|
176
|
+
- **A dependency completion is an event, not a one-shot latch (PL-40).** A task with two
|
|
177
|
+
parents (`dependsOn: [A, B]`) is started whenever either parent finishes while all
|
|
178
|
+
parents' latest records are successful — so two completions can mean two runs. A stale
|
|
179
|
+
success also satisfies the gate. The dependent's own `startedAt` only suppresses a
|
|
180
|
+
re-trigger when it is newer than the newest dependency `finishedAt`. If you need
|
|
181
|
+
exactly one follow-up run, use `nextTaskOnSuccess` (a single-parent chain) instead of
|
|
182
|
+
a multi-parent `dependsOn`.
|
|
183
|
+
- **Worktree snapshot for Quality Gate (PL-25).** When a task has a machine-checkable gate,
|
|
184
|
+
the wrapper snapshots `HEAD` plus guarded-path status at task start into a sibling
|
|
185
|
+
`*.worktree.json` and verifies it immediately before the gate. Foreign uncommitted edits
|
|
186
|
+
in `src/` during the run fail closed: the gate is skipped and the run is marked as an
|
|
187
|
+
error. Override guarded paths with `AGENT_STEWARD_GATE_GUARD_PATHS` (`|`/`;` separated).
|
|
105
188
|
- Keep chains short and named by intent (`deploy` → `smoke-tests` → `notify-release`).
|
|
106
189
|
- Cycles and self-dependencies are rejected; if a chain grows past 4–5 nodes, consider one
|
|
107
190
|
task with an explicit internal checklist instead.
|
|
@@ -122,6 +205,11 @@ Rules of thumb:
|
|
|
122
205
|
`timeout`, `partial`.
|
|
123
206
|
- `get_task_logs` with `lines` — tail of the wrapper log; use it to distinguish model failure,
|
|
124
207
|
Quality Gate failure, timeout and lock-skip.
|
|
208
|
+
- Structured journal (`logs/runs.jsonl`, `hook.output` events, PL-7.2): post-flight stdout
|
|
209
|
+
and stderr are stored in **separate** fields with the real `postFlightExitCode`. Git writes
|
|
210
|
+
progress/diagnostics to stderr even on success, so compare the exit code and stdout — do
|
|
211
|
+
not treat a non-empty stderr as a failed push. See `references/recipes.md` §11 for the
|
|
212
|
+
commit/push wrapper that makes this reliable.
|
|
125
213
|
- Matrix problems: `matrix_control` with `action: "results"` for counters, `action: "cancel"`
|
|
126
214
|
to stop pending clones, `action: "cleanup"` to remove clones whose parent is gone.
|
|
127
215
|
- A timeout usually means the prompt is too broad. Split it or raise `timeoutSeconds`
|
|
@@ -136,6 +224,9 @@ Rules of thumb:
|
|
|
136
224
|
| `* * * * *` with a heavy prompt | Runs overlap, lock-skips, cost spikes | Realistic interval + timeout |
|
|
137
225
|
| Prompt depending on chat context | Nonsense output at 03:00 | Self-contained prompt with paths |
|
|
138
226
|
| No Quality Gate on a "fixer" job | Broken code reported as success | `qualityGate: "npm test"` |
|
|
227
|
+
| `nextTaskOnSuccess` and `dependsOn` for one transition | Duplicate runs of the same step | Keep one mechanism only (PL-5.1/PL-5.2) |
|
|
228
|
+
| Prompt demands `node`/tests but shell is denied | `tool.blocked`, fake "verified" report | `shell` in `allowedTools` or checks in `qualityGate`/`afterScript` |
|
|
229
|
+
| Closed task left in `ROADMAP.md` with a missing/incorrect file name | Gate checks a file that does not exist | Exact line format + artifact checklist in the prompt (PL-3.1) |
|
|
139
230
|
| Matrix with 20 workspaces, no concurrency cap | Machine and API saturation | `matrix.concurrency: 2–4` |
|
|
140
231
|
| Secrets inside the prompt | Leak into DB, logs and dashboard | Env vars or files |
|
|
141
232
|
| Deleting a matrix parent's clone by hand | Orphaned history, broken aggregate | `update_task` on the parent |
|
|
@@ -147,9 +238,12 @@ Before saying the job is done, confirm:
|
|
|
147
238
|
|
|
148
239
|
- [ ] `list_tasks` checked; no duplicate exists.
|
|
149
240
|
- [ ] Trigger type matches the need (cron / file / MCP event).
|
|
150
|
-
- [ ] Prompt states goal, scope, constraints, verification and output
|
|
241
|
+
- [ ] Prompt states goal, scope, constraints, verification and output; for doc updates it
|
|
242
|
+
includes the exact line format and the artifact checklist from §3 (PL-3.1).
|
|
151
243
|
- [ ] `timeoutSeconds` set; `qualityGate` set when checkable.
|
|
152
244
|
- [ ] `allowedTools` / `deniedTools` follow least privilege; shell is absent unless justified.
|
|
245
|
+
If the prompt demands a self-check, shell is in `allowedTools` or the check lives in
|
|
246
|
+
`qualityGate`/`afterScript` — never both "no shell" and "verify with node/tests" (PL-2.1).
|
|
153
247
|
- [ ] Matrix: workspaces correct, concurrency capped, failure mode justified.
|
|
154
248
|
- [ ] `dry_run` reviewed.
|
|
155
249
|
- [ ] One successful `run_task_now` with clean `get_history`.
|
|
@@ -161,3 +161,142 @@ fail-open, and shadow mode makes false skips visible. Only disable shadow mode
|
|
|
161
161
|
after the shadow report shows no false positives. See `docs/LOCAL-AI.md` for
|
|
162
162
|
model tiers by RAM, `OLLAMA_CONTEXT_LENGTH` troubleshooting and the full JSON
|
|
163
163
|
report format.
|
|
164
|
+
|
|
165
|
+
## 9. Restarting a `once` task after a plugin reload (PL-1.2)
|
|
166
|
+
|
|
167
|
+
While the plugin is unloading, `run_task_now` refuses new launches with the structured
|
|
168
|
+
error `PLUGIN_SHUTTING_DOWN` (`message` + `hint`: retry after restart, or use a force
|
|
169
|
+
marker / delayed start). For a `once` task already registered in Windows Task Scheduler,
|
|
170
|
+
the OS can start it without the MCP gate:
|
|
171
|
+
|
|
172
|
+
```powershell
|
|
173
|
+
# 1. Plain OS trigger (no force marker needed if the schedule gate is not involved):
|
|
174
|
+
schtasks /run /tn "<task name>"
|
|
175
|
+
# Equivalent modern cmdlet:
|
|
176
|
+
Start-ScheduledTask -TaskName "<task name>"
|
|
177
|
+
|
|
178
|
+
# 2. If the wrapper might be skipped by its cron/window gate, put the force marker
|
|
179
|
+
# in the task locks directory first (slug = task name lowercased, spaces -> '-'):
|
|
180
|
+
New-Item -ItemType File -Force -Path "locks/<slug>.lock.force" | Out-Null
|
|
181
|
+
Start-ScheduledTask -TaskName "<task name>"
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Notes and warnings:
|
|
185
|
+
|
|
186
|
+
- The wrapper removes `locks/<slug>.lock.force` after the run **and** on failure. If the
|
|
187
|
+
OS refuses to start, delete the marker yourself — a stale marker can allow a later
|
|
188
|
+
scheduled tick out of turn.
|
|
189
|
+
- **Never combine both paths in one recovery.** `schtasks /run` plus a manual
|
|
190
|
+
`run_task_now` (or two `Start-ScheduledTask` calls) creates duplicate runs: locks are
|
|
191
|
+
per task name, so the second start can be accepted for the next tick.
|
|
192
|
+
- Verify exactly one run: `get_history({ taskName: "<task name>" })` must show a single
|
|
193
|
+
new `running`/`success` record, and `get_task_logs` must not contain a lock-skip for the
|
|
194
|
+
same interval. Check again after the plugin restarts — a reload must not leave a second run.
|
|
195
|
+
- Check `nextTaskOnSuccess` / `nextTaskOnError` chains explicitly. They are recorded by a
|
|
196
|
+
separate process, so the follow-up task can fire after the OS-started run. Look for the
|
|
197
|
+
chained task in `get_history`; do **not** re-run the parent to "make the chain happen" —
|
|
198
|
+
that is the classic way to get a duplicate chain entry.
|
|
199
|
+
|
|
200
|
+
Why: the OS trigger is the documented escape hatch for the shutdown gate; the force marker
|
|
201
|
+
only bypasses the schedule gate, and both need a duplicate check plus a chain check.
|
|
202
|
+
|
|
203
|
+
## 10. Safe cleanup in `beforeScript` (PL-6.1)
|
|
204
|
+
|
|
205
|
+
`Remove-Item -ErrorAction SilentlyContinue` returns exit code **1** when the file is already
|
|
206
|
+
absent. A non-zero pre-flight code cancels the run with `Pre-flight script failed` and fires
|
|
207
|
+
a false compensator. Guard the existence check and finish with an explicit `exit 0`:
|
|
208
|
+
|
|
209
|
+
```powershell
|
|
210
|
+
if (Test-Path -LiteralPath '<path>') { Remove-Item -LiteralPath '<path>' -Force }; exit 0
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Rules:
|
|
214
|
+
|
|
215
|
+
- Use `-LiteralPath`, not `-Path`, so brackets and wildcards in the path are literal.
|
|
216
|
+
- Keep the guard and `exit 0` in the same script; for several paths repeat the guard for each
|
|
217
|
+
and put a single `exit 0` at the end.
|
|
218
|
+
- In a Bash pre-flight the equivalent is `rm -f "<path>"` followed by `exit 0`.
|
|
219
|
+
- The wrapper only sees the process exit code — it cannot tell "cleanup skipped, nothing to
|
|
220
|
+
do" from "cleanup failed". Make the script say `0` for the first case explicitly.
|
|
221
|
+
|
|
222
|
+
## 11. Reliable commit + push from `afterScript` (PL-7.1)
|
|
223
|
+
|
|
224
|
+
Proven pattern from `scripts/qa-a2-commit.ps1`. Native Git writes progress and diagnostics
|
|
225
|
+
to **stderr**; under PowerShell 7 with `$ErrorActionPreference = 'Stop'` that becomes a
|
|
226
|
+
terminating error even when the push succeeded. Relax the preference only around Git calls,
|
|
227
|
+
capture `$LASTEXITCODE`, retry, and verify the remote before declaring failure.
|
|
228
|
+
|
|
229
|
+
```powershell
|
|
230
|
+
$ErrorActionPreference = 'Stop'
|
|
231
|
+
Set-Location -LiteralPath $root
|
|
232
|
+
|
|
233
|
+
function Invoke-Git([string]$what, [string[]]$gitArgs) {
|
|
234
|
+
$old = $ErrorActionPreference
|
|
235
|
+
$ErrorActionPreference = 'Continue' # stderr diagnostics are not terminating errors
|
|
236
|
+
try {
|
|
237
|
+
$output = & git @gitArgs 2>&1 # capture/suppress stderr
|
|
238
|
+
$code = $LASTEXITCODE # the REAL exit code
|
|
239
|
+
foreach ($line in $output) { Write-Output ("[{0}] {1}" -f $what, [string]$line) }
|
|
240
|
+
return $code
|
|
241
|
+
} finally { $ErrorActionPreference = $old }
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
if ((Invoke-Git 'add' (@('add', '--') + $fileList)) -ne 0) { exit 1 }
|
|
245
|
+
|
|
246
|
+
# "nothing to commit" = success, not an error
|
|
247
|
+
$old = $ErrorActionPreference
|
|
248
|
+
$ErrorActionPreference = 'Continue'
|
|
249
|
+
try { $nothing = git diff --cached --quiet; $clean = $LASTEXITCODE }
|
|
250
|
+
finally { $ErrorActionPreference = $old }
|
|
251
|
+
if ($clean -eq 0) { exit 0 }
|
|
252
|
+
|
|
253
|
+
if ((Invoke-Git 'commit' @('commit', '-m', $Message)) -ne 0) { exit 1 }
|
|
254
|
+
|
|
255
|
+
$pushed = $false
|
|
256
|
+
for ($attempt = 1; $attempt -le 3; $attempt++) { # 3 retries
|
|
257
|
+
if ((Invoke-Git "push#$attempt" @('push', 'origin', 'dev')) -eq 0) { $pushed = $true; break }
|
|
258
|
+
Start-Sleep -Seconds 3
|
|
259
|
+
}
|
|
260
|
+
if (-not $pushed) {
|
|
261
|
+
# A parallel task may already have pushed our commit: verify before failing.
|
|
262
|
+
$null = Invoke-Git 'fetch' @('fetch', 'origin', 'dev')
|
|
263
|
+
$old = $ErrorActionPreference
|
|
264
|
+
$ErrorActionPreference = 'Continue'
|
|
265
|
+
try {
|
|
266
|
+
$local = (& git rev-parse HEAD 2>$null).Trim()
|
|
267
|
+
$remote = (& git rev-parse origin/dev 2>$null).Trim()
|
|
268
|
+
} finally { $ErrorActionPreference = $old }
|
|
269
|
+
if ($local -and $local -eq $remote) { $pushed = $true } # HEAD/origin/dev agree
|
|
270
|
+
}
|
|
271
|
+
exit $(if ($pushed) { 0 } else { 1 })
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Notes:
|
|
275
|
+
|
|
276
|
+
- Gate the commit on a real Quality Gate success marker before `git add` (see the source
|
|
277
|
+
script); never commit untested files just because the afterScript ran.
|
|
278
|
+
- Commit **only** the files owned by the task, never `git add -A`.
|
|
279
|
+
- With the structured journal, read `postFlightExitCode` and the separate
|
|
280
|
+
`postFlightStdout` / `postFlightStderr` fields (`hook.output` events) instead of treating a
|
|
281
|
+
non-empty stderr as a failure (PL-7.2).
|
|
282
|
+
|
|
283
|
+
## 13. Which lint command is a real gate? (PL-22)
|
|
284
|
+
|
|
285
|
+
`npm run lint` runs plain ESLint and exits 0 even with hundreds of warnings — it is
|
|
286
|
+
**informational** (colored diagnostics in the editor). The real CI gate is
|
|
287
|
+
`npm run lint:baseline`, which fails when the warning count exceeds the committed baseline.
|
|
288
|
+
`npm run lint:strict` (`eslint src --max-warnings=0`) is an opt-in target for a fully cleaned
|
|
289
|
+
tree; do not put it in a required gate while the baseline is non-zero.
|
|
290
|
+
|
|
291
|
+
## 12. Pin the commit your Quality Gate trusts (PL-8.1)
|
|
292
|
+
|
|
293
|
+
During a multi-hour DAG a parallel task can commit to the same branch. `npm test` in the gate
|
|
294
|
+
then fails on counter drift (`test-docs.mjs`) although this task's code is correct. `dry_run`
|
|
295
|
+
warns when the working directory's HEAD is newer than the task's `createdAt`. Before running
|
|
296
|
+
such a job:
|
|
297
|
+
|
|
298
|
+
- Record the starting HEAD and require it in the gate, e.g.
|
|
299
|
+
`qualityGate: "git diff --quiet <sha> && npm test"` (adapt quoting to your shell), so a
|
|
300
|
+
foreign commit fails the gate deterministically instead of mid-run.
|
|
301
|
+
- Or run the job in an isolated worktree / serialize writers to `src/`.
|
|
302
|
+
- Re-check `git status` and `dry_run` immediately before the gate on a shared branch.
|