@apralabs/apra-fleet 0.4.4 → 0.4.5
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 +49 -4
- package/dist/agents/backlog-groomer.md +5 -0
- package/dist/agents/ci-watcher.md +5 -0
- package/dist/agents/deployer.md +20 -2
- package/dist/agents/doer.md +38 -2
- package/dist/agents/harvester.md +12 -9
- package/dist/agents/integ-test-runner.md +5 -0
- package/dist/agents/kb-reconciler.md +6 -0
- package/dist/agents/plan-reviewer.md +5 -0
- package/dist/agents/planner.md +5 -0
- package/dist/agents/regression-test-runner.md +5 -0
- package/dist/agents/reviewer.md +67 -15
- package/dist/agents/schemas/deployer-output.json +5 -0
- package/dist/agents/schemas/doer-output.json +78 -2
- package/dist/agents/schemas/reviewer-output.json +104 -2
- package/dist/cli/auth.js +5 -1
- package/dist/cli/beads-pin.js +6 -7
- package/dist/cli/claude-mod.d.ts +75 -0
- package/dist/cli/claude-mod.js +288 -0
- package/dist/cli/dolt-install.d.ts +1 -1
- package/dist/cli/dolt-install.js +5 -1
- package/dist/cli/fleet-se-guard.d.ts +8 -0
- package/dist/cli/fleet-se-guard.js +19 -3
- package/dist/cli/install-guard.d.ts +9 -0
- package/dist/cli/install-guard.js +24 -0
- package/dist/cli/install.d.ts +12 -0
- package/dist/cli/install.js +180 -20
- package/dist/cli/kb-profile.d.ts +16 -0
- package/dist/cli/kb-profile.js +81 -0
- package/dist/cli/start.js +3 -0
- package/dist/cli/uninstall.js +13 -3
- package/dist/cli/update.d.ts +4 -0
- package/dist/cli/update.js +19 -3
- package/dist/commands/kb-server.d.ts +10 -1
- package/dist/commands/kb-server.js +285 -11
- package/dist/index.js +22 -1
- package/dist/os/git-executable.d.ts +57 -0
- package/dist/os/git-executable.js +85 -0
- package/dist/os/go-concurrency.d.ts +44 -0
- package/dist/os/go-concurrency.js +53 -0
- package/dist/os/index.d.ts +1 -0
- package/dist/os/index.js +1 -0
- package/dist/os/linux.d.ts +2 -0
- package/dist/os/linux.js +10 -1
- package/dist/os/os-commands.d.ts +25 -0
- package/dist/os/os-commands.js +2 -0
- package/dist/os/windows-executable.d.ts +53 -0
- package/dist/os/windows-executable.js +185 -0
- package/dist/os/windows-gitbash.d.ts +23 -14
- package/dist/os/windows-gitbash.js +40 -16
- package/dist/os/windows.d.ts +2 -0
- package/dist/os/windows.js +37 -6
- package/dist/paths.d.ts +10 -1
- package/dist/paths.js +19 -2
- package/dist/services/agy-project.d.ts +7 -1
- package/dist/services/agy-project.js +7 -2
- package/dist/services/auth-socket.d.ts +18 -0
- package/dist/services/auth-socket.js +30 -4
- package/dist/services/credential-store.d.ts +33 -0
- package/dist/services/credential-store.js +79 -2
- package/dist/services/http-transport.d.ts +29 -0
- package/dist/services/http-transport.js +166 -37
- package/dist/services/kb-tool-profile.d.ts +36 -0
- package/dist/services/kb-tool-profile.js +88 -0
- package/dist/services/knowledge/bible-blob-id.js +10 -1
- package/dist/services/knowledge/bible-import.d.ts +108 -0
- package/dist/services/knowledge/bible-import.js +137 -4
- package/dist/services/knowledge/file-hash.js +6 -5
- package/dist/services/knowledge/http-provider.d.ts +303 -20
- package/dist/services/knowledge/http-provider.js +795 -125
- package/dist/services/knowledge/kb-config.d.ts +65 -1
- package/dist/services/knowledge/kb-config.js +143 -3
- package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
- package/dist/services/knowledge/kb-http-auth-state.js +40 -0
- package/dist/services/knowledge/kb-providers.d.ts +9 -2
- package/dist/services/knowledge/kb-providers.js +67 -37
- package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
- package/dist/services/knowledge/kb-self.d.ts +122 -9
- package/dist/services/knowledge/kb-self.js +196 -36
- package/dist/services/knowledge/member-bible-view.js +16 -3
- package/dist/services/knowledge/path-validation.d.ts +7 -0
- package/dist/services/knowledge/path-validation.js +11 -0
- package/dist/services/knowledge/project-slug.js +3 -2
- package/dist/services/knowledge/repository-header.d.ts +77 -0
- package/dist/services/knowledge/repository-header.js +233 -0
- package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
- package/dist/services/knowledge/require-sqlite-project.js +1 -1
- package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
- package/dist/services/knowledge/sqlite-provider.js +416 -4
- package/dist/services/knowledge/types.d.ts +15 -2
- package/dist/services/member-busy.d.ts +12 -0
- package/dist/services/member-busy.js +20 -0
- package/dist/services/member-config-io.d.ts +3 -2
- package/dist/services/member-config-io.js +7 -4
- package/dist/services/member-fleet-install.js +1 -0
- package/dist/services/member-tool-allowlist.d.ts +1 -1
- package/dist/services/member-tool-allowlist.js +8 -4
- package/dist/services/port-holder.js +2 -1
- package/dist/services/service-manager/types.d.ts +17 -1
- package/dist/services/service-manager/windows.d.ts +7 -2
- package/dist/services/service-manager/windows.js +28 -11
- package/dist/services/service-notice.d.ts +7 -0
- package/dist/services/service-notice.js +19 -0
- package/dist/services/session-registry.d.ts +13 -0
- package/dist/services/session-registry.js +13 -0
- package/dist/services/session-roots.d.ts +67 -0
- package/dist/services/session-roots.js +126 -0
- package/dist/services/statusline.d.ts +21 -0
- package/dist/services/statusline.js +97 -1
- package/dist/services/supervisor-service-cleanup.js +2 -1
- package/dist/services/tool-registry.js +108 -20
- package/dist/services/tool-scope.d.ts +34 -1
- package/dist/services/tool-scope.js +27 -2
- package/dist/services/vcs/azure-devops.js +10 -0
- package/dist/services/vcs/bitbucket.d.ts +22 -1
- package/dist/services/vcs/bitbucket.js +163 -17
- package/dist/services/vcs/types.d.ts +25 -2
- package/dist/services/watch/project-resolver.js +2 -1
- package/dist/skills/pm/cost.md +5 -1
- package/dist/skills/pm/index.md +9 -9
- package/dist/skills/pm/sprint.md +2 -1
- package/dist/tools/check-status.d.ts +51 -0
- package/dist/tools/check-status.js +124 -12
- package/dist/tools/code-intelligence-freshness.js +1 -1
- package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
- package/dist/tools/code-intelligence-gitnexus.js +166 -9
- package/dist/tools/code-intelligence-readiness.d.ts +58 -1
- package/dist/tools/code-intelligence-readiness.js +93 -8
- package/dist/tools/code-intelligence-reindex.d.ts +25 -1
- package/dist/tools/code-intelligence-reindex.js +76 -4
- package/dist/tools/code-intelligence.d.ts +1 -1
- package/dist/tools/code-intelligence.js +1 -1
- package/dist/tools/execute-command.js +14 -8
- package/dist/tools/execute-prompt.js +6 -2
- package/dist/tools/fleet-snapshot.d.ts +21 -0
- package/dist/tools/fleet-snapshot.js +78 -0
- package/dist/tools/kb-bible-commit.d.ts +25 -11
- package/dist/tools/kb-bible-commit.js +142 -33
- package/dist/tools/kb-capture.d.ts +2 -2
- package/dist/tools/kb-context.js +47 -27
- package/dist/tools/kb-demote.d.ts +27 -0
- package/dist/tools/kb-demote.js +37 -0
- package/dist/tools/kb-export.d.ts +35 -3
- package/dist/tools/kb-export.js +56 -13
- package/dist/tools/kb-feedback.d.ts +2 -0
- package/dist/tools/kb-feedback.js +17 -7
- package/dist/tools/kb-harvest.js +28 -9
- package/dist/tools/kb-import.d.ts +18 -2
- package/dist/tools/kb-import.js +24 -9
- package/dist/tools/kb-invalidate.d.ts +11 -3
- package/dist/tools/kb-invalidate.js +80 -7
- package/dist/tools/kb-list.js +38 -10
- package/dist/tools/kb-promote.js +6 -4
- package/dist/tools/kb-query.d.ts +3 -0
- package/dist/tools/kb-query.js +181 -37
- package/dist/tools/kb-session-prime.d.ts +4 -4
- package/dist/tools/kb-session-prime.js +89 -9
- package/dist/tools/kb-setup.d.ts +20 -0
- package/dist/tools/kb-setup.js +149 -11
- package/dist/tools/list-members.js +1 -1
- package/dist/tools/member-detail.js +7 -3
- package/dist/tools/provision-vcs-auth.d.ts +28 -3
- package/dist/tools/provision-vcs-auth.js +53 -7
- package/dist/tools/receive-files.js +7 -4
- package/dist/tools/send-files.js +5 -4
- package/dist/tools/send-message.d.ts +3 -0
- package/dist/tools/send-message.js +15 -2
- package/dist/tools/stop-prompt.js +3 -1
- package/dist/tools/vcs-credential-exec.d.ts +45 -3
- package/dist/tools/vcs-credential-exec.js +90 -11
- package/dist/utils/process-utils.js +5 -1
- package/dist/utils/redact-known-secrets.d.ts +17 -0
- package/dist/utils/redact-known-secrets.js +70 -0
- package/dist/utils/skill-matrix.js +1 -1
- package/dist/utils/vcs-provider-detect.js +2 -2
- package/dist/workflows/auto-sprint.js +245 -9
- package/package.json +10 -7
- package/packages/apra-fleet-client/package.json +1 -1
- package/packages/apra-fleet-client/src/client/api.mjs +172 -19
- package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
- package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
- package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
- package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
- package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
- package/packages/apra-fleet-se/bin/cli.mjs +104 -31
- package/packages/apra-fleet-se/bin/serve.mjs +46 -8
- package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
- package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
- package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
- package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
- package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
- package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
- package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
- package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
- package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
- package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
- package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
- package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
- package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
- package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
- package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
- package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
- package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
- package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
- package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
- package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
- package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
- package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
- package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
- package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
- package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
- package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
- package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
- package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
- package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
- package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
- package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
- package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
- package/packages/apra-fleet-workflow/package.json +2 -1
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
- package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
- package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
- package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
- package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
- package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
- package/skills/fleet/auth-bitbucket.md +47 -20
- package/skills/fleet/onboarding.md +1 -1
- package/skills/fleet/skill-matrix.md +3 -3
- package/version.json +1 -1
|
@@ -21,6 +21,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
21
21
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
22
22
|
your tool-loading tool first, before concluding they are unavailable.
|
|
23
23
|
|
|
24
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
25
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
26
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
27
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
28
|
+
|
|
24
29
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
25
30
|
subsystems `regression-test-playbook.md` exercises.
|
|
26
31
|
2. Known-flaky tests and known environment setup/teardown gotchas are the point here -- they
|
|
@@ -44,6 +44,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
44
44
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
45
45
|
your tool-loading tool first, before concluding they are unavailable.
|
|
46
46
|
|
|
47
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
48
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
49
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
50
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
51
|
+
|
|
47
52
|
The `code_impact` and `kb_query` calls below are EXPECTED, not optional, whenever the
|
|
48
53
|
tools are present. If a tool is genuinely not present (or the KB or code index is not set
|
|
49
54
|
up for this repo), record that in `toolUse` (Output schema) and continue -- never skip
|
|
@@ -58,7 +63,9 @@ silently.
|
|
|
58
63
|
exempt -- and `code_context`/`code_graph`/`code_query` to trace callers before
|
|
59
64
|
accepting a signature or behaviour change -- prefer them over grep for structural
|
|
60
65
|
questions. If they are absent, fail, or report the repo is not indexed, fall back to
|
|
61
|
-
reading the diff and grep and record it in `toolUse`; do not build an index.
|
|
66
|
+
reading the diff and grep and record it in `toolUse`; do not build an index. On
|
|
67
|
+
`E-CODE-INDEX-NOT-READY`, wait once for its `retry_after_ms`, retry once, then fall
|
|
68
|
+
back -- never poll `code_status` in a loop.
|
|
62
69
|
3. Call `kb_query` at least once per review, on the changed files' topics, to check the
|
|
63
70
|
doer's claims and the diff against what the KB already records, and to dedupe your
|
|
64
71
|
captures (item 4). This is for verification only; promotion candidates still come
|
|
@@ -96,6 +103,10 @@ search also matches value text, so apply only entries whose KEY contains `+all+`
|
|
|
96
103
|
|
|
97
104
|
## Step 1 -- Context recovery
|
|
98
105
|
|
|
106
|
+
If your dispatch prompt gives a diff range (`<commit-sha>..<branch>`), use exactly that
|
|
107
|
+
range wherever `<base-branch>..<branch>` appears below, for every `git diff` and
|
|
108
|
+
`git log`. Never diff against a local base branch in that case: it may be stale.
|
|
109
|
+
|
|
99
110
|
```bash
|
|
100
111
|
git log --oneline <base-branch>..<branch>
|
|
101
112
|
git diff <base-branch>..<branch> --stat
|
|
@@ -170,13 +181,17 @@ foreground command, treat it as if you backgrounded it yourself; do not chain sh
|
|
|
170
181
|
sleeps to route around the sleep-block. Do not return a verdict while the suite is
|
|
171
182
|
still running -- a backgrounded run with no reported outcome is not a completed step.
|
|
172
183
|
|
|
173
|
-
## Step 5 -- Promote or
|
|
184
|
+
## Step 5 -- Promote, discard, or demote knowledge you verified
|
|
174
185
|
|
|
175
|
-
This step covers judgements on existing
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
186
|
+
This step covers judgements on existing candidates: promote an INFERRED one to
|
|
187
|
+
CONFIRMED, discard an INFERRED one you showed to be wrong, or demote a CONFIRMED one
|
|
188
|
+
back to INFERRED. Fresh findings go in `kb_captures` (Step 0, item 4) -- the fields are
|
|
189
|
+
independent and can all be returned. You are the only role permitted to mint CONFIRMED
|
|
190
|
+
or to demote it. **You do not call any `kb_*` tool for any of promotion, discard or
|
|
191
|
+
demotion** -- for all three, you RETURN your judgement in the named field of your
|
|
192
|
+
structured output (`kb_promotions`, `kb_discards`, `kb_demotions`), and the orchestrator
|
|
193
|
+
reads that output and executes your judgement on your behalf; you never touch the KB
|
|
194
|
+
directly.
|
|
180
195
|
|
|
181
196
|
1. Read the **KNOWLEDGE BANK -- promotion candidates** block in your dispatch prompt. It
|
|
182
197
|
lists every INFERRED entry for the repo under review as `{id, title, summary,
|
|
@@ -197,6 +212,26 @@ orchestrator hands you the candidates and executes your decisions.
|
|
|
197
212
|
confirm is not wrong: leave it INFERRED. Never list the same id in both
|
|
198
213
|
`kb_promotions` and `kb_discards` -- the orchestrator refuses both.
|
|
199
214
|
`kb_discards: []` is a valid, common answer.
|
|
215
|
+
6. **Demote** a CONFIRMED entry when re-checking it during THIS review shows the claim
|
|
216
|
+
does not hold -- whether you are now less certain of it or have shown it wrong, it is
|
|
217
|
+
one judgement and one route. Read the **KNOWLEDGE BANK -- demotion candidates** block
|
|
218
|
+
in your dispatch prompt (if absent, there is nothing to demote: return
|
|
219
|
+
`kb_demotions: []`). A drifted or removed basis (the cited code changed or vanished)
|
|
220
|
+
is NOT a demote case -- the freshness sweep and the bible basis predicate already
|
|
221
|
+
handle that without you. Discarding an unconfirmed (INFERRED) capture you showed wrong
|
|
222
|
+
is `kb_discards` above, never a demotion, since demotion only ever applies to an
|
|
223
|
+
already-CONFIRMED entry. Return demotions in the `kb_demotions` field as
|
|
224
|
+
`[{id, reason, evidence_files}]`: the same reason bar (minimum 20 characters, stating
|
|
225
|
+
what you re-checked this review that the claim does not hold up against), and
|
|
226
|
+
`evidence_files` naming the files you re-checked -- at least one, each a real file in
|
|
227
|
+
the repo. A demotion without one is refused. Demoting nothing is a valid, common answer: `kb_demotions: []`.
|
|
228
|
+
Never list the same id in more than one of `kb_promotions`, `kb_discards` and
|
|
229
|
+
`kb_demotions` -- the orchestrator refuses it in every list it appears in.
|
|
230
|
+
A team can turn the demotion loop off (a sprint launch setting); then no
|
|
231
|
+
demotion candidates block appears and any `kb_demotions` you return are dropped.
|
|
232
|
+
Re-promotion limit: a demoted entry returns to INFERRED, but the promotion window is
|
|
233
|
+
entries whose `created_at` falls inside the current sprint, so an entry created in an
|
|
234
|
+
earlier sprint that gets demoted is never re-offered for promotion by the engine.
|
|
200
235
|
|
|
201
236
|
Hard limits:
|
|
202
237
|
|
|
@@ -210,13 +245,13 @@ Hard limits:
|
|
|
210
245
|
- **User-directives are off limits.** Activation is human-only; the orchestrator filters
|
|
211
246
|
them from your candidate list. If one appears anyway, leave it alone.
|
|
212
247
|
- **Never invent an id.** Only ids from the candidate block in THIS dispatch are
|
|
213
|
-
promotable or
|
|
214
|
-
anywhere else -- including one you remember from an earlier round -- is dropped
|
|
248
|
+
promotable, discardable or demotable. The orchestrator refuses any other id, so an id
|
|
249
|
+
from anywhere else -- including one you remember from an earlier round -- is dropped
|
|
215
250
|
and logged, never applied.
|
|
216
251
|
|
|
217
|
-
Promotion and
|
|
218
|
-
the "never mutate beads" rule below. Report what you promoted
|
|
219
|
-
well.
|
|
252
|
+
Promotion, discard and demotion are KB decisions, not beads mutations -- they do not
|
|
253
|
+
conflict with the "never mutate beads" rule below. Report what you promoted, discarded
|
|
254
|
+
or demoted in `notes` as well.
|
|
220
255
|
|
|
221
256
|
## Step 6 -- Verdict
|
|
222
257
|
|
|
@@ -233,7 +268,7 @@ judgement.
|
|
|
233
268
|
Return your structured output ONLY. You never call `bd update`, `bd close`, `bd create`,
|
|
234
269
|
or any other beads mutation yourself -- the orchestrator reads your structured output and
|
|
235
270
|
applies the reopen/create transitions:
|
|
236
|
-
- `verdict`: "APPROVED" or "
|
|
271
|
+
- `verdict`: "APPROVED", "CHANGES_NEEDED" or "NEEDS-DECISION"
|
|
237
272
|
- `notes`: specific findings with file and line references where possible
|
|
238
273
|
- `reopenIds`: array of beads task IDs that need rework (empty array if none)
|
|
239
274
|
- `replanIds`: optional array of ids among `reopenIds` whose ACCEPTANCE CRITERIA are
|
|
@@ -261,6 +296,19 @@ applies the reopen/create transitions:
|
|
|
261
296
|
yourself. The orchestrator runs `bd update <id> --status=open` for each ID in `reopenIds`.
|
|
262
297
|
Notes must be specific: "auth_test.ts line 42: no test for expired token path".
|
|
263
298
|
|
|
299
|
+
**NEEDS-DECISION**: when a bead under review can be neither approved nor sent back for
|
|
300
|
+
rework until a human chooses between real alternatives (for example two acceptable
|
|
301
|
+
designs with different costs, or criteria that can only be met by an option the bead
|
|
302
|
+
does not authorize), return `verdict: "NEEDS-DECISION"` with a `decision` object:
|
|
303
|
+
`beadId` (the one bead the decision is about, from the beads you were asked to review),
|
|
304
|
+
`question` (self-contained: what you found and what must be decided), `options` (at
|
|
305
|
+
least two, each `{ "id": "a", "text": "..." }`) and `recommendation` (the option id you
|
|
306
|
+
recommend, and why). The orchestrator reopens that bead if needed, files the question
|
|
307
|
+
for an operator verbatim and sets the bead aside for the rest of the run; any other
|
|
308
|
+
`reopenIds` and `newTasks` on the same verdict are still applied. Do not use it for
|
|
309
|
+
ordinary rework (CHANGES_NEEDED) or for defective criteria a planner can rewrite
|
|
310
|
+
(`replanIds`).
|
|
311
|
+
|
|
264
312
|
## Output schema
|
|
265
313
|
|
|
266
314
|
The canonical machine-readable contract for this output lives in the sibling file
|
|
@@ -281,6 +329,9 @@ placeholder):
|
|
|
281
329
|
"kb_discards": [
|
|
282
330
|
{ "id": "kb-0051", "reason": "src/auth/session.ts:40 refreshes eagerly; the entry's lazy-refresh claim is wrong" }
|
|
283
331
|
],
|
|
332
|
+
"kb_demotions": [
|
|
333
|
+
{ "id": "kb-0033", "reason": "re-ran the reopen test this entry cites and it now fails", "evidence_files": ["test/reopen.test.mjs"] }
|
|
334
|
+
],
|
|
284
335
|
"kb_captures": [
|
|
285
336
|
{
|
|
286
337
|
"type": "knowledge",
|
|
@@ -294,8 +345,9 @@ placeholder):
|
|
|
294
345
|
}
|
|
295
346
|
```
|
|
296
347
|
|
|
297
|
-
`kb_promotions`, `kb_discards` and `kb_captures` are all optional --
|
|
298
|
-
`[]`, when you have nothing to promote, discard or capture
|
|
348
|
+
`kb_promotions`, `kb_discards`, `kb_demotions` and `kb_captures` are all optional --
|
|
349
|
+
omit them, or send `[]`, when you have nothing to promote, discard, demote or capture
|
|
350
|
+
this round. `toolUse` is
|
|
299
351
|
optional in the schema but expected: see Step 0.
|
|
300
352
|
|
|
301
353
|
**Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
|
|
@@ -12,6 +12,11 @@
|
|
|
12
12
|
},
|
|
13
13
|
"notes": {
|
|
14
14
|
"type": "string"
|
|
15
|
+
},
|
|
16
|
+
"failedStep": {
|
|
17
|
+
"type": "string",
|
|
18
|
+
"enum": ["permissions"],
|
|
19
|
+
"description": "Set to \"permissions\" ONLY when you returned deployed: false because you stopped at Step 0a (the deploy.md Permissions check) before running any deploy command. The orchestrator then does not dispatch the deploy again this run. Omit it for every other outcome, including any failure after a deploy command ran."
|
|
15
20
|
}
|
|
16
21
|
}
|
|
17
22
|
}
|
|
@@ -15,7 +15,8 @@
|
|
|
15
15
|
"type": "string",
|
|
16
16
|
"enum": [
|
|
17
17
|
"VERIFY",
|
|
18
|
-
"BLOCKED"
|
|
18
|
+
"BLOCKED",
|
|
19
|
+
"NEEDS-DECISION"
|
|
19
20
|
]
|
|
20
21
|
},
|
|
21
22
|
"closedIds": {
|
|
@@ -27,6 +28,62 @@
|
|
|
27
28
|
"notes": {
|
|
28
29
|
"type": "string"
|
|
29
30
|
},
|
|
31
|
+
"decision": {
|
|
32
|
+
"type": "object",
|
|
33
|
+
"description": "REQUIRED when status is \"NEEDS-DECISION\", otherwise omit. The decision only a human operator can make before the named bead can go on. The orchestrator files it for an operator verbatim (never truncated), sets the bead aside for the rest of the run without re-dispatching it, and keeps working other ready beads. Use it only for a real choice between alternatives you cannot settle from the bead, its parent or the code -- not for a missing secret or an unmet prerequisite (BLOCKED), and not for an ordinary failure.",
|
|
34
|
+
"required": [
|
|
35
|
+
"beadId",
|
|
36
|
+
"question",
|
|
37
|
+
"options",
|
|
38
|
+
"recommendation"
|
|
39
|
+
],
|
|
40
|
+
"properties": {
|
|
41
|
+
"beadId": {
|
|
42
|
+
"type": "string",
|
|
43
|
+
"minLength": 1,
|
|
44
|
+
"description": "The one open bead id that cannot go on until the decision is made."
|
|
45
|
+
},
|
|
46
|
+
"question": {
|
|
47
|
+
"type": "string",
|
|
48
|
+
"minLength": 1,
|
|
49
|
+
"description": "The full question, self-contained: what was found, why it blocks the bead, and what must be decided. An operator reads only this and the options."
|
|
50
|
+
},
|
|
51
|
+
"options": {
|
|
52
|
+
"type": "array",
|
|
53
|
+
"minItems": 2,
|
|
54
|
+
"description": "At least two concrete alternatives, each with a short stable id (for example \"a\", \"b\") and its full text: what it means and what it costs.",
|
|
55
|
+
"items": {
|
|
56
|
+
"type": "object",
|
|
57
|
+
"required": [
|
|
58
|
+
"id",
|
|
59
|
+
"text"
|
|
60
|
+
],
|
|
61
|
+
"properties": {
|
|
62
|
+
"id": {
|
|
63
|
+
"type": "string",
|
|
64
|
+
"minLength": 1
|
|
65
|
+
},
|
|
66
|
+
"text": {
|
|
67
|
+
"type": "string",
|
|
68
|
+
"minLength": 1
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
},
|
|
73
|
+
"recommendation": {
|
|
74
|
+
"type": "string",
|
|
75
|
+
"minLength": 1,
|
|
76
|
+
"description": "The option id you recommend, followed by why."
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
},
|
|
80
|
+
"blockedIds": {
|
|
81
|
+
"type": "array",
|
|
82
|
+
"description": "With status BLOCKED: the assigned bead ids you left open BECAUSE of the block -- not ids you merely did not reach (e.g. same-lane stop rule). The engine sets these beads, and every open bead depending on them, aside for the rest of the run. Optional -- omitted on a single-bead assignment it means that bead; omit or send [] with status VERIFY.",
|
|
83
|
+
"items": {
|
|
84
|
+
"type": "string"
|
|
85
|
+
}
|
|
86
|
+
},
|
|
30
87
|
"kb_captures": {
|
|
31
88
|
"type": "array",
|
|
32
89
|
"description": "Durable knowledge this role verified during its run. The engine makes the kb_capture calls; the role only decides. Optional -- omit or send [] to capture nothing.",
|
|
@@ -110,5 +167,24 @@
|
|
|
110
167
|
}
|
|
111
168
|
}
|
|
112
169
|
}
|
|
113
|
-
}
|
|
170
|
+
},
|
|
171
|
+
"allOf": [
|
|
172
|
+
{
|
|
173
|
+
"if": {
|
|
174
|
+
"properties": {
|
|
175
|
+
"status": {
|
|
176
|
+
"const": "NEEDS-DECISION"
|
|
177
|
+
}
|
|
178
|
+
},
|
|
179
|
+
"required": [
|
|
180
|
+
"status"
|
|
181
|
+
]
|
|
182
|
+
},
|
|
183
|
+
"then": {
|
|
184
|
+
"required": [
|
|
185
|
+
"decision"
|
|
186
|
+
]
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
]
|
|
114
190
|
}
|
|
@@ -16,12 +16,62 @@
|
|
|
16
16
|
"type": "string",
|
|
17
17
|
"enum": [
|
|
18
18
|
"APPROVED",
|
|
19
|
-
"CHANGES_NEEDED"
|
|
19
|
+
"CHANGES_NEEDED",
|
|
20
|
+
"NEEDS-DECISION"
|
|
20
21
|
]
|
|
21
22
|
},
|
|
22
23
|
"notes": {
|
|
23
24
|
"type": "string"
|
|
24
25
|
},
|
|
26
|
+
"decision": {
|
|
27
|
+
"type": "object",
|
|
28
|
+
"description": "REQUIRED when verdict is \"NEEDS-DECISION\", otherwise omit. The decision only a human operator can make before the named bead can go on. The orchestrator files it for an operator verbatim (never truncated), sets the bead aside for the rest of the run without re-dispatching it, and keeps working other ready beads. Use it only for a real choice between alternatives you cannot settle from the bead, its parent or the code -- not for a missing secret or an unmet prerequisite (BLOCKED), and not for an ordinary failure.",
|
|
29
|
+
"required": [
|
|
30
|
+
"beadId",
|
|
31
|
+
"question",
|
|
32
|
+
"options",
|
|
33
|
+
"recommendation"
|
|
34
|
+
],
|
|
35
|
+
"properties": {
|
|
36
|
+
"beadId": {
|
|
37
|
+
"type": "string",
|
|
38
|
+
"minLength": 1,
|
|
39
|
+
"description": "The one bead under review that cannot be approved or sent back for rework until the decision is made. The orchestrator reopens it if it is closed and sets it aside."
|
|
40
|
+
},
|
|
41
|
+
"question": {
|
|
42
|
+
"type": "string",
|
|
43
|
+
"minLength": 1,
|
|
44
|
+
"description": "The full question, self-contained: what was found, why it blocks the bead, and what must be decided. An operator reads only this and the options."
|
|
45
|
+
},
|
|
46
|
+
"options": {
|
|
47
|
+
"type": "array",
|
|
48
|
+
"minItems": 2,
|
|
49
|
+
"description": "At least two concrete alternatives, each with a short stable id (for example \"a\", \"b\") and its full text: what it means and what it costs.",
|
|
50
|
+
"items": {
|
|
51
|
+
"type": "object",
|
|
52
|
+
"required": [
|
|
53
|
+
"id",
|
|
54
|
+
"text"
|
|
55
|
+
],
|
|
56
|
+
"properties": {
|
|
57
|
+
"id": {
|
|
58
|
+
"type": "string",
|
|
59
|
+
"minLength": 1
|
|
60
|
+
},
|
|
61
|
+
"text": {
|
|
62
|
+
"type": "string",
|
|
63
|
+
"minLength": 1
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
},
|
|
68
|
+
"recommendation": {
|
|
69
|
+
"type": "string",
|
|
70
|
+
"minLength": 1,
|
|
71
|
+
"description": "The option id you recommend, followed by why."
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
},
|
|
25
75
|
"reopenIds": {
|
|
26
76
|
"type": "array",
|
|
27
77
|
"items": {
|
|
@@ -107,6 +157,39 @@
|
|
|
107
157
|
}
|
|
108
158
|
}
|
|
109
159
|
},
|
|
160
|
+
"kb_demotions": {
|
|
161
|
+
"type": "array",
|
|
162
|
+
"description": "CONFIRMED entries a re-check during this review shows do not hold -- whether you are now less certain of the claim or have shown it wrong -- demoted back to INFERRED. Not for a drifted or removed basis. Reviewer-only, with the same evidence bar as kb_promotions and kb_discards. An id may appear in only one of kb_promotions, kb_discards and kb_demotions -- the engine refuses it in all lists it appears in. The engine makes the demotion calls.",
|
|
163
|
+
"items": {
|
|
164
|
+
"type": "object",
|
|
165
|
+
"required": [
|
|
166
|
+
"id",
|
|
167
|
+
"reason",
|
|
168
|
+
"evidence_files"
|
|
169
|
+
],
|
|
170
|
+
"properties": {
|
|
171
|
+
"id": {
|
|
172
|
+
"type": "string",
|
|
173
|
+
"description": "The entry id, copied verbatim from the 'KNOWLEDGE BANK -- demotion candidates' block in your dispatch prompt. That block is the ONLY source of demotable ids -- do not call a kb_* tool to find one, and never invent one.",
|
|
174
|
+
"minLength": 1
|
|
175
|
+
},
|
|
176
|
+
"reason": {
|
|
177
|
+
"type": "string",
|
|
178
|
+
"description": "What you re-checked this review that the claim does not hold up against.",
|
|
179
|
+
"minLength": 20
|
|
180
|
+
},
|
|
181
|
+
"evidence_files": {
|
|
182
|
+
"type": "array",
|
|
183
|
+
"description": "The repo-relative files you re-checked -- at least one, each a real file in the repo.",
|
|
184
|
+
"minItems": 1,
|
|
185
|
+
"items": {
|
|
186
|
+
"type": "string",
|
|
187
|
+
"minLength": 1
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
},
|
|
110
193
|
"kb_captures": {
|
|
111
194
|
"type": "array",
|
|
112
195
|
"description": "Durable knowledge this role verified during its run. The engine makes the kb_capture calls; the role only decides. Optional -- omit or send [] to capture nothing.",
|
|
@@ -190,5 +273,24 @@
|
|
|
190
273
|
}
|
|
191
274
|
}
|
|
192
275
|
}
|
|
193
|
-
}
|
|
276
|
+
},
|
|
277
|
+
"allOf": [
|
|
278
|
+
{
|
|
279
|
+
"if": {
|
|
280
|
+
"properties": {
|
|
281
|
+
"verdict": {
|
|
282
|
+
"const": "NEEDS-DECISION"
|
|
283
|
+
}
|
|
284
|
+
},
|
|
285
|
+
"required": [
|
|
286
|
+
"verdict"
|
|
287
|
+
]
|
|
288
|
+
},
|
|
289
|
+
"then": {
|
|
290
|
+
"required": [
|
|
291
|
+
"decision"
|
|
292
|
+
]
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
]
|
|
194
296
|
}
|
|
@@ -111,7 +111,11 @@ At sprint close, after the harvester runs:
|
|
|
111
111
|
2. **Build summary**: run `buildSprintSummary(analysis, quote, calibration, opts)`
|
|
112
112
|
where `opts = { branch, goal, goalMet, cycleCount, tasksCompleted, tasksOpen,
|
|
113
113
|
startedAt }`. Write the returned `summaryText` to
|
|
114
|
-
`sprint-logs/<branch>-<startedAt>.analysis.md`
|
|
114
|
+
`sprint-logs/<branch>-<startedAt>.analysis.md`. Do NOT `git add` or commit it: it is a
|
|
115
|
+
local record. Before writing it, make sure the line `sprint-logs/*.analysis.md` is in
|
|
116
|
+
the repo's local git exclude file (the path `git rev-parse --git-path info/exclude`
|
|
117
|
+
prints; add the line only if it is not already there) so no later `git add -A` or
|
|
118
|
+
`git add sprint-logs/` stages it.
|
|
115
119
|
3. **Update calibration**: run `computeUpdatedCalibration(calibration, analysis,
|
|
116
120
|
startedAt, taskAssignments, logEntries)` and write the result back to
|
|
117
121
|
`sprint-logs/calibration.json`. Commit it. This blends the actual token counts
|
|
@@ -11,12 +11,14 @@ code_graph, code_impact, code_query, and code_context tools.
|
|
|
11
11
|
the repo path.
|
|
12
12
|
3. Run via `execute_command` (wrap in background Agent per fleet rules):
|
|
13
13
|
```
|
|
14
|
-
npx gitnexus analyze --index-only --embeddings
|
|
14
|
+
npx gitnexus analyze --index-only --force --embeddings
|
|
15
15
|
```
|
|
16
16
|
- `run_from`: project repo root
|
|
17
|
-
- `timeout_s`:
|
|
17
|
+
- `timeout_s`: 900 (a full build of a large repo can take several minutes)
|
|
18
18
|
- `--index-only` keeps the repo work tree clean: without it gitnexus
|
|
19
19
|
writes an AGENTS.md/CLAUDE.md block and skills folders into the repo.
|
|
20
|
+
- `--force` is required: an incremental analyze can corrupt the index, so
|
|
21
|
+
symbols that exist answer "not found".
|
|
20
22
|
4. Report the result: nodes indexed, edges, flows (gitnexus prints this on
|
|
21
23
|
completion). If gitnexus is not installed, it will be fetched automatically
|
|
22
24
|
via npx.
|
|
@@ -31,9 +33,8 @@ code_graph, code_impact, code_query, and code_context tools.
|
|
|
31
33
|
- One-time cost: the first `--embeddings` run on a machine downloads the
|
|
32
34
|
model (~87 MB) from HuggingFace and caches it at `~/.cache/huggingface`;
|
|
33
35
|
every run after that is offline.
|
|
34
|
-
- Embeddings are OFF by default and
|
|
35
|
-
|
|
36
|
-
additive and safe to run repeatedly.
|
|
36
|
+
- Embeddings are OFF by default, and passing `--embeddings` here is safe to
|
|
37
|
+
run repeatedly.
|
|
37
38
|
- win32 caveat: on Windows, LadybugDB's VECTOR index is unavailable, so
|
|
38
39
|
semantic search falls back to an exact scan (capped at 10000 chunks) --
|
|
39
40
|
this still works, it is just brute-force rather than an ANN index. Not a
|
|
@@ -44,15 +45,14 @@ code_graph, code_impact, code_query, and code_context tools.
|
|
|
44
45
|
|
|
45
46
|
- **Automatically inside `/pm init`** -- runs as the final step of project initialization.
|
|
46
47
|
The worktree must exist before indexing (gitnexus needs files on disk to analyze).
|
|
47
|
-
- **Automatically at VERIFY checkpoints** -- checkpoints re-run npx gitnexus analyze --index-only to keep
|
|
48
|
-
mid-sprint symbols visible to later phases (
|
|
49
|
-
takes seconds).
|
|
48
|
+
- **Automatically at VERIFY checkpoints** -- checkpoints re-run npx gitnexus analyze --index-only --force to keep
|
|
49
|
+
mid-sprint symbols visible to later phases (a full rebuild, minutes on a large repo).
|
|
50
50
|
- After a large merge or rebase that changes many files
|
|
51
51
|
- When `kb_session_prime` returns many stale entries
|
|
52
52
|
- Any time the user asks to re-index (run `/pm index` explicitly)
|
|
53
53
|
|
|
54
54
|
## Notes
|
|
55
55
|
|
|
56
|
-
- Indexing is per-repo and persists on disk
|
|
56
|
+
- Indexing is per-repo and persists on disk. Always pass `--force`: never run an incremental analyze.
|
|
57
57
|
- The index is used by the gitnexus provider behind code_graph/impact/query/context.
|
|
58
58
|
- Fleet members never call gitnexus directly -- they use the fleet tools.
|
|
@@ -211,7 +211,8 @@ MANDATORY CHECKLIST -- verify each before exiting:
|
|
|
211
211
|
from `<skillDir>/cost.js` (the extracted module installed alongside this skill on
|
|
212
212
|
every provider -- see `cost.md`) to produce `sprint-logs/<branch>-<startedAt>.analysis.md` and
|
|
213
213
|
update `sprint-logs/calibration.json` with actual token data from this sprint.
|
|
214
|
-
Commit
|
|
214
|
+
Commit `calibration.json` only; the `.analysis.md` stays local and git-excluded,
|
|
215
|
+
never committed. See `cost.md` Harvest.
|
|
215
216
|
5. **Close the sprint root and the delivered issues** -- `bd close <sprint-id>`; also close
|
|
216
217
|
any source beads issues this sprint implemented -- the ready backlog items the
|
|
217
218
|
requirement was drawn from -- with `bd close <issue-id> ...`. Closing the sprint root
|