ultra-builder-pro-cli 0.25.1 → 0.26.0

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.
Files changed (241) hide show
  1. package/.ultra-template/contexts/TEMPLATE.md +87 -0
  2. package/.ultra-template/decisions/.gitkeep +1 -0
  3. package/.ultra-template/evidence/.gitkeep +1 -0
  4. package/.ultra-template/north-star.md +46 -0
  5. package/.ultra-template/research/.gitkeep +1 -0
  6. package/.ultra-template/specs/discovery.md +2 -2
  7. package/.ultra-template/tasks.json +3 -0
  8. package/.ultra-template/test-report.json +27 -0
  9. package/CHANGELOG.md +40 -0
  10. package/README.md +217 -579
  11. package/adapters/_shared/delegate-profiles/kimi-read-only.md +15 -0
  12. package/adapters/_shared/delegate-profiles/kimi-write.md +17 -0
  13. package/adapters/_shared/file-ops.cjs +76 -2
  14. package/adapters/_shared/host-profile.cjs +97 -0
  15. package/adapters/_shared/plugin-core.cjs +204 -0
  16. package/adapters/_shared/runtime-assets.cjs +31 -96
  17. package/adapters/claude.js +92 -291
  18. package/adapters/codex.js +309 -842
  19. package/adapters/grok.js +143 -1469
  20. package/adapters/kimi.js +124 -1053
  21. package/adapters/opencode.js +230 -742
  22. package/bin/delegate-worker.cjs +323 -0
  23. package/bin/delegate.cjs +456 -0
  24. package/bin/install.js +38 -11
  25. package/docs/ARCHITECTURE.md +122 -216
  26. package/docs/ARTIFACT-AUTHORITY.md +90 -268
  27. package/docs/DECISIONS.md +75 -87
  28. package/docs/PHILOSOPHY.md +177 -0
  29. package/docs/PLUGIN-ISOLATION-CONTRACT.md +62 -39
  30. package/docs/RUNTIME-COMPAT-MATRIX.md +99 -156
  31. package/docs/SKILL-AUTHORING.md +94 -73
  32. package/docs/WORKFLOW-LIFECYCLE.md +93 -189
  33. package/hooks/README.md +17 -37
  34. package/hooks/_common.py +113 -0
  35. package/hooks/adapters/codex.py +9 -16
  36. package/hooks/adapters/grok.py +5 -5
  37. package/hooks/adapters/kimi.py +8 -14
  38. package/hooks/block_dangerous_commands.py +95 -0
  39. package/hooks/compact_context.py +65 -0
  40. package/hooks/mid_workflow_recall.py +25 -0
  41. package/hooks/post_edit_guard.py +105 -0
  42. package/hooks/session_context.py +30 -0
  43. package/package.json +17 -52
  44. package/skills/ultra-change/SKILL.md +97 -50
  45. package/skills/ultra-change/references/change-contract.md +40 -1
  46. package/skills/ultra-delegate/SKILL.md +82 -0
  47. package/skills/ultra-delegate/references/delegation-contract.md +51 -0
  48. package/skills/ultra-delegate/scripts/delegate_wait.py +86 -0
  49. package/skills/ultra-deliver/SKILL.md +61 -42
  50. package/skills/ultra-deliver/references/baseline-reconciliation.md +39 -20
  51. package/skills/ultra-dev/SKILL.md +96 -62
  52. package/skills/ultra-dev/references/debugging.md +22 -0
  53. package/skills/ultra-domain-modeling/SKILL.md +79 -0
  54. package/skills/ultra-grilling/SKILL.md +79 -0
  55. package/skills/ultra-init/SKILL.md +94 -37
  56. package/skills/ultra-init/references/brownfield-adoption.md +33 -83
  57. package/skills/ultra-init/scripts/init_project.cjs +84 -0
  58. package/skills/ultra-plan/SKILL.md +88 -68
  59. package/skills/ultra-research/SKILL.md +62 -48
  60. package/skills/ultra-research/references/00-problem-validation.md +5 -5
  61. package/skills/ultra-research/references/01-opportunity-discovery.md +3 -3
  62. package/skills/ultra-research/references/02-market-assessment.md +5 -4
  63. package/skills/ultra-research/references/03-competitive-landscape.md +3 -3
  64. package/skills/ultra-research/references/04-product-strategy.md +3 -3
  65. package/skills/ultra-research/references/05-assumptions-validation.md +5 -5
  66. package/skills/ultra-research/references/10-user-personas.md +3 -2
  67. package/skills/ultra-research/references/11-user-scenarios.md +3 -3
  68. package/skills/ultra-research/references/20-user-stories.md +4 -3
  69. package/skills/ultra-research/references/21-features-scope.md +3 -2
  70. package/skills/ultra-research/references/22-success-metrics.md +3 -3
  71. package/skills/ultra-research/references/30-architecture-context.md +3 -3
  72. package/skills/ultra-research/references/31-solution-strategy.md +3 -3
  73. package/skills/ultra-research/references/32-building-blocks.md +3 -3
  74. package/skills/ultra-research/references/40-deployment.md +3 -3
  75. package/skills/ultra-research/references/41-quality-risks.md +3 -3
  76. package/skills/ultra-research/references/99-synthesis.md +7 -7
  77. package/skills/ultra-review/SKILL.md +59 -32
  78. package/skills/ultra-review/references/code.md +17 -0
  79. package/skills/ultra-review/references/comments.md +12 -0
  80. package/skills/ultra-review/references/design.md +12 -0
  81. package/skills/ultra-review/references/errors.md +13 -0
  82. package/skills/ultra-review/references/spec.md +13 -0
  83. package/skills/ultra-review/references/tests.md +12 -0
  84. package/skills/ultra-review/references/worker-packet.md +40 -0
  85. package/skills/ultra-review/scripts/review_wait.py +26 -15
  86. package/skills/ultra-status/SKILL.md +61 -36
  87. package/skills/ultra-tdd/SKILL.md +81 -0
  88. package/skills/ultra-tdd/references/templates/README.md +20 -0
  89. package/skills/ultra-tdd/references/templates/feature-flag-default-audit.sh +79 -0
  90. package/skills/ultra-tdd/references/templates/persistence-real.ts +78 -0
  91. package/skills/ultra-tdd/references/templates/testcontainer-postgres.py +78 -0
  92. package/skills/ultra-tdd/references/templates/testcontainer-postgres.ts +73 -0
  93. package/skills/ultra-tdd/references/templates/vertical-slice.ts +66 -0
  94. package/skills/ultra-tdd/references/test-execution.md +18 -0
  95. package/skills/ultra-test/SKILL.md +70 -30
  96. package/skills/ultra-test/references/export-syntax.md +18 -0
  97. package/skills/ultra-test/scripts/worktree_digest.cjs +54 -0
  98. package/skills/ultra-think/SKILL.md +49 -27
  99. package/skills/ultra-think/references/autonomy-boundary.md +48 -0
  100. package/skills/ultra-think/references/interaction-boundary.md +18 -33
  101. package/.ultra-template/docs/research/README.md +0 -55
  102. package/.ultra-template/reports/templates/delivery-report.json +0 -17
  103. package/.ultra-template/reports/templates/test-report.json +0 -18
  104. package/.ultra-template/tasks/tasks.json +0 -15
  105. package/.ultra-template/templates/task-context.md +0 -19
  106. package/adapters/_shared/codex-assets.cjs +0 -725
  107. package/adapters/_shared/codex-ultra-tools-entry.cjs +0 -11
  108. package/adapters/_shared/interaction-contract.cjs +0 -129
  109. package/adapters/_shared/path-rewrite.cjs +0 -79
  110. package/adapters/_shared/runtime-native.cjs +0 -132
  111. package/adapters/_shared/settings-merge.cjs +0 -76
  112. package/agents/code-reviewer.md +0 -42
  113. package/agents/debugger.md +0 -40
  114. package/agents/review-code.md +0 -49
  115. package/agents/review-comments.md +0 -38
  116. package/agents/review-coordinator.md +0 -56
  117. package/agents/review-design.md +0 -40
  118. package/agents/review-errors.md +0 -43
  119. package/agents/review-spec.md +0 -39
  120. package/agents/review-tests.md +0 -40
  121. package/agents/tdd-runner.md +0 -38
  122. package/bin/orchestrator.js +0 -383
  123. package/commands/ultra-change.md +0 -10
  124. package/commands/ultra-deliver.md +0 -10
  125. package/commands/ultra-dev.md +0 -10
  126. package/commands/ultra-doctor.md +0 -10
  127. package/commands/ultra-init.md +0 -10
  128. package/commands/ultra-plan.md +0 -10
  129. package/commands/ultra-research.md +0 -10
  130. package/commands/ultra-review.md +0 -10
  131. package/commands/ultra-status.md +0 -10
  132. package/commands/ultra-test.md +0 -10
  133. package/commands/ultra-think.md +0 -10
  134. package/docs/AGENT-CONTEXT.md +0 -191
  135. package/docs/COMMIT-HASH-BACKFILL.md +0 -51
  136. package/docs/LEGACY-CLI-CROSSWALK.md +0 -175
  137. package/docs/ROADMAP.md +0 -101
  138. package/docs/STATE-DB-ACCESS-POLICY.md +0 -161
  139. package/hooks/active_task_context.py +0 -152
  140. package/hooks/context_envelope.py +0 -100
  141. package/hooks/health_check.py +0 -196
  142. package/hooks/pre_stop_check.py +0 -66
  143. package/hooks/runtime_paths.py +0 -396
  144. package/hooks/subagent_tracker.py +0 -88
  145. package/hooks/workflow_checkpoint.py +0 -76
  146. package/hooks/workflow_context.py +0 -48
  147. package/hooks/workflow_resume.py +0 -84
  148. package/mcp-server/hook-context.cjs +0 -38
  149. package/mcp-server/hook-event.cjs +0 -34
  150. package/mcp-server/lib/archive-journal.cjs +0 -1119
  151. package/mcp-server/lib/archive-mutation-worker.py +0 -365
  152. package/mcp-server/lib/artifact-registry.cjs +0 -1232
  153. package/mcp-server/lib/baseline-workflow.cjs +0 -1193
  154. package/mcp-server/lib/canonical-json.cjs +0 -19
  155. package/mcp-server/lib/change-authority.cjs +0 -26
  156. package/mcp-server/lib/change-packet.cjs +0 -790
  157. package/mcp-server/lib/change-workflow.cjs +0 -65
  158. package/mcp-server/lib/context-envelope.cjs +0 -581
  159. package/mcp-server/lib/context-paths.cjs +0 -142
  160. package/mcp-server/lib/decision-records.cjs +0 -423
  161. package/mcp-server/lib/delivery-transaction.cjs +0 -471
  162. package/mcp-server/lib/doctor-backup-worker.cjs +0 -328
  163. package/mcp-server/lib/doctor.cjs +0 -627
  164. package/mcp-server/lib/git-bootstrap.cjs +0 -651
  165. package/mcp-server/lib/init-project.cjs +0 -1021
  166. package/mcp-server/lib/kernel-change-workflow.cjs +0 -2029
  167. package/mcp-server/lib/legacy-change-workflow.cjs +0 -3032
  168. package/mcp-server/lib/managed-file-write.cjs +0 -172
  169. package/mcp-server/lib/plan-checkpoint.cjs +0 -177
  170. package/mcp-server/lib/plan-publication-worker.cjs +0 -830
  171. package/mcp-server/lib/plan-store.cjs +0 -794
  172. package/mcp-server/lib/prd-parser.cjs +0 -83
  173. package/mcp-server/lib/pricing.cjs +0 -44
  174. package/mcp-server/lib/project-context.cjs +0 -178
  175. package/mcp-server/lib/projector.cjs +0 -386
  176. package/mcp-server/lib/provider-refs.cjs +0 -42
  177. package/mcp-server/lib/runtime-paths.cjs +0 -1714
  178. package/mcp-server/lib/runtime-state.cjs +0 -222
  179. package/mcp-server/lib/safe-project-file.cjs +0 -385
  180. package/mcp-server/lib/stage-checkpoints.cjs +0 -463
  181. package/mcp-server/lib/state-authority.cjs +0 -95
  182. package/mcp-server/lib/state-db.cjs +0 -1580
  183. package/mcp-server/lib/state-ops.cjs +0 -1428
  184. package/mcp-server/lib/task-contract.cjs +0 -404
  185. package/mcp-server/lib/task-expander.cjs +0 -105
  186. package/mcp-server/lib/task-ledger.cjs +0 -1964
  187. package/mcp-server/lib/telemetry.cjs +0 -85
  188. package/mcp-server/lib/topo.cjs +0 -131
  189. package/mcp-server/lib/ultra-facade.cjs +0 -2684
  190. package/mcp-server/lib/worker-packet.cjs +0 -358
  191. package/mcp-server/server.cjs +0 -437
  192. package/orchestrator/auto-merge.cjs +0 -128
  193. package/orchestrator/daemon.cjs +0 -264
  194. package/orchestrator/dispatch-rules.cjs +0 -78
  195. package/orchestrator/parallel-orchestrator.cjs +0 -903
  196. package/orchestrator/planner/plan-builder.cjs +0 -125
  197. package/orchestrator/recovery.cjs +0 -188
  198. package/orchestrator/session-close-journal-worker.cjs +0 -5
  199. package/orchestrator/session-close-journal.cjs +0 -1014
  200. package/orchestrator/session-runner.cjs +0 -1153
  201. package/orchestrator/worktree-manager.cjs +0 -282
  202. package/settings.json +0 -7
  203. package/skills/cc-collab/SKILL.md +0 -42
  204. package/skills/code-review-expert/SKILL.md +0 -43
  205. package/skills/code-review-expert/references/correctness-reliability.md +0 -30
  206. package/skills/code-review-expert/references/design-boundaries.md +0 -26
  207. package/skills/code-review-expert/references/removal-plan.md +0 -24
  208. package/skills/codex-collab/SKILL.md +0 -49
  209. package/skills/codex-collab/evals/evals.json +0 -35
  210. package/skills/integration-rules/SKILL.md +0 -32
  211. package/skills/security-rules/SKILL.md +0 -38
  212. package/skills/testing-rules/SKILL.md +0 -32
  213. package/skills/ultra-doctor/SKILL.md +0 -41
  214. package/skills/ultra-plan/references/semantic-preflight.md +0 -20
  215. package/skills/ultra-verify/SKILL.md +0 -46
  216. package/skills/ultra-verify/evals/evals.json +0 -46
  217. package/skills/ultra-verify/references/cross-verify-modes.md +0 -28
  218. package/skills/ultra-verify/references/evidence-status.md +0 -21
  219. package/skills/ultra-verify/scripts/verify_wait.py +0 -94
  220. package/spec/cli-protocol.md +0 -102
  221. package/spec/mcp-tools.yaml +0 -312
  222. package/spec/schemas/baseline-reconciliation.v1.schema.json +0 -73
  223. package/spec/schemas/change-delta.v1.schema.json +0 -153
  224. package/spec/schemas/command-manifest.schema.json +0 -29
  225. package/spec/schemas/context-file.v4.5.schema.json +0 -54
  226. package/spec/schemas/delivery-report.v1.schema.json +0 -66
  227. package/spec/schemas/documentation-reconciliation.v1.schema.json +0 -106
  228. package/spec/schemas/mcp-tools.schema.json +0 -136
  229. package/spec/schemas/skill-manifest.schema.json +0 -24
  230. package/spec/schemas/state-db.sql +0 -641
  231. package/spec/schemas/task-ledger.v2.schema.json +0 -296
  232. package/spec/schemas/tasks.v4.5.schema.json +0 -96
  233. package/spec/schemas/test-report.v1.schema.json +0 -225
  234. package/ultra-tools/cli.cjs +0 -129
  235. package/ultra-tools/commands/db.cjs +0 -226
  236. package/ultra-tools/commands/legacy-memory.cjs +0 -159
  237. package/ultra-tools/commands/migrate.cjs +0 -1386
  238. package/ultra-tools/commands/session.cjs +0 -213
  239. package/ultra-tools/commands/status.cjs +0 -559
  240. package/ultra-tools/commands/system.cjs +0 -498
  241. package/ultra-tools/commands/task.cjs +0 -105
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Vertical-Slice integration test (TypeScript)
3
+ *
4
+ * Why this exists: proves HTTP entry → use case → domain → DB → response works
5
+ * end-to-end. ONE such test per feature is the difference between "single tasks
6
+ * pass / project doesn't run" (the failure mode v7 was built to fix) and
7
+ * actual deliverable software.
8
+ *
9
+ * Required deps:
10
+ * pnpm add -D supertest @testcontainers/postgresql pg vitest
11
+ *
12
+ * Verify:
13
+ * pnpm vitest run src/__tests__/auth.vertical-slice.test.ts
14
+ *
15
+ * PHILOSOPHY: enables C4 (Incremental Validation) — the `vertical_slice`
16
+ * dimension in progress.json is satisfied by tests like this.
17
+ */
18
+
19
+ import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
20
+ import { Pool } from 'pg';
21
+ import request from 'supertest';
22
+ import { afterAll, beforeAll, describe, expect, test } from 'vitest';
23
+
24
+ // Replace with your real app/server factory
25
+ import { buildApp } from '../app';
26
+
27
+ let container: StartedPostgreSqlContainer;
28
+ let pool: Pool;
29
+ let app: ReturnType<typeof buildApp>;
30
+
31
+ beforeAll(async () => {
32
+ container = await new PostgreSqlContainer('postgres:16-alpine').start();
33
+ pool = new Pool({ connectionString: container.getConnectionUri() });
34
+ // Run migrations
35
+ await pool.query(`CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT UNIQUE)`);
36
+ app = buildApp({ db: pool });
37
+ }, 60_000);
38
+
39
+ afterAll(async () => {
40
+ await pool.end();
41
+ await container.stop();
42
+ });
43
+
44
+ describe('vertical slice: POST /signup', () => {
45
+ test('inserts a row, returns 201, body matches input email', async () => {
46
+ const before = await pool.query('SELECT count(*) FROM users');
47
+ const beforeCount = parseInt(before.rows[0].count, 10);
48
+
49
+ const res = await request(app)
50
+ .post('/signup')
51
+ .send({ email: 'vertical@example.com' })
52
+ .expect(201);
53
+
54
+ // 1. response shape
55
+ expect(res.body.email).toBe('vertical@example.com');
56
+ expect(res.body.id).toBeGreaterThan(0);
57
+
58
+ // 2. real DB write occurred
59
+ const after = await pool.query('SELECT count(*) FROM users');
60
+ expect(parseInt(after.rows[0].count, 10)).toBe(beforeCount + 1);
61
+
62
+ // 3. data is persistable / queryable
63
+ const row = await pool.query('SELECT email FROM users WHERE id = $1', [res.body.id]);
64
+ expect(row.rows[0].email).toBe('vertical@example.com');
65
+ });
66
+ });
@@ -0,0 +1,18 @@
1
+ # Test execution evidence
2
+
3
+ Resolve the canonical command from package scripts, CI configuration, repository
4
+ guidance, or framework files. When two commands prove different contracts, keep the
5
+ distinction visible instead of choosing the easier one.
6
+
7
+ For every baseline, red, and green run record:
8
+
9
+ - exact command and working directory;
10
+ - start time, duration, and exit code;
11
+ - runner-reported pass, fail, skip, and coverage counts when available;
12
+ - first useful failure with tight source or test location;
13
+ - whether it reproduces and whether it is product, test, environment, or flaky evidence;
14
+ - raw output path under `.ultra/evidence/<task-id>/` when the output matters.
15
+
16
+ Do not weaken flags, skip a relevant failure, edit test configuration to obtain green,
17
+ or claim success when the command did not finish with exit zero. A concise evidence
18
+ record may cite the raw log; it must not copy an entire transcript into task context.
@@ -1,42 +1,82 @@
1
1
  ---
2
2
  name: ultra-test
3
- description: Independently verify an Ultra task set or Change with an evidence-backed, risk-selected test profile. Use when implementation or current acceptance and recovery evidence needs independent verification.
3
+ description: Audit whole-system integrity after the task ledger is complete by finding anti-patterns, coverage gaps, broken wiring, E2E failures, performance risk, and security risk. Use when preparing delivery or when locally green tasks may not form a working product.
4
4
  ---
5
5
 
6
- # Verify current behavior
6
+ # NOT for running unit tests (that's `ultra-dev`). This audits whole-system integrity before delivery.
7
7
 
8
- Testing independently checks the current checkout. Implementation conclusions and
9
- generated projections are not evidence.
8
+ This is the one end-of-change sensor allowed by PHILOSOPHY C4: an export cannot be
9
+ called orphaned while a later task may still wire it. It is a terminal sensor, never a gate;
10
+ the owner decides what to fix or accept.
10
11
 
11
- ## Bind and execute
12
+ ## Before you start
12
13
 
13
- 1. Call `ultra.context { stage: test, scope: { change_id, task_id? }, detail: full }`.
14
- 2. Import a newer team checkpoint with `ultra.sync`; stop on a real conflict.
15
- 3. Bind exact acceptance, task set, HEAD, worktree, decisions, dev evidence, and public
16
- seams.
17
- 4. Select a risk-based profile from acceptance, regression, integration, static
18
- analysis, build, performance, security, and recovery. Acceptance is mandatory;
19
- explain every material exclusion.
20
- 5. Run repository-native commands and real boundaries. A bug or incident needs one
21
- deterministic red-to-green regression signal.
14
+ 1. Read `.ultra/tasks.json` and every completed task's `context_file`, especially its
15
+ Acceptance, Completion and closing `## Resume Note`.
16
+ 2. Read `CONTEXT.md` for vocabulary and the relevant `.ultra/decisions/` entries.
17
+ 3. Read the active Change intent, the task evidence directories and the current Git
18
+ `HEAD`; old output is evidence only for the commit it names.
19
+ 4. Resolve this loaded Skill's directory and run
20
+ `node <ultra-test-skill-dir>/scripts/worktree_digest.cjs --project <repository-root>`
21
+ before and after the audit. Its digest excludes
22
+ only `.ultra/test-report.json`, avoiding a self-referential report.
22
23
 
23
- When delegated, use the immutable Worker Packet supplied by the parent and echo its
24
- `packet_digest` in the report. Write an `ultra-test-report-v1` report below the owning
25
- Change. Bind exact acceptance
26
- ids, task ids, HEAD, worktree/context digests, commands, seams, failures, recovery,
27
- profile, timestamp, blockers, and evidence-derived verdict. Register it with
28
- `ultra.record` using `artifact / bind`.
24
+ ## Definition of done
29
25
 
30
- ## Checkpoint
26
+ - All six audit areas have an evidence-backed result or an explicit material omission.
27
+ - Wiring lists each changed export and its non-test consumers; zero matches are visible
28
+ as orphan findings.
29
+ - `.ultra/test-report.json` records `git_commit`, commands, findings, omissions and the
30
+ owner's disposition without rewriting a finding into a pass.
31
31
 
32
- Call `ultra.checkpoint` once with `stage: test`, exact scope, evidence, and an output
33
- for the report (`kind: test-report`). The model owns the evidence-derived verdict and
34
- material exclusions. The checkpoint compiles or reuses checking context, verifies the
35
- declared report authority and digest, and records that verdict without re-judging it.
32
+ ## Audit six areas
36
33
 
37
- If rejected, keep the same draft and repair the structural, digest, path, or
38
- concurrency fault. Never weaken an assertion, hide a skip, or turn a warning into
39
- proof.
34
+ 1. **Anti-patterns**: find tautological or empty tests and internal collaborators mocked
35
+ instead of exercising a public seam.
36
+ 2. **Coverage gaps**: map changed public behavior to tests and list behavior with no
37
+ exercising test.
38
+ 3. **Wiring Verification**: list changed exported symbols, then search each name in
39
+ non-test source. `0 matches = orphan` until a framework registration or generated
40
+ consumer is evidenced. Also trace Component→API, API→DB, Form→Handler and
41
+ State→Render where those boundaries exist.
42
+ 4. **E2E**: run the smallest real primary flow through its deployed or local boundary.
43
+ 5. **Performance**: measure the paths whose acceptance or risk makes latency, resource
44
+ use or scale material; record why anything else was omitted.
45
+ 6. **Security**: run the repository's dependency and security checks, then inspect the
46
+ trust boundaries changed by this Change.
40
47
 
41
- Return the profile, exact results, verified seams, blockers, report digest, and the
42
- model's recommended next explicit capability. Do not invoke it automatically.
48
+ Read `references/export-syntax.md` before collecting exports. The table finds
49
+ candidates; repository conventions and real consumers decide what is public.
50
+
51
+ ## Detect substantive stubs
52
+
53
+ Report an empty return with no IO, a log-only function, a handler that only prevents
54
+ default, or a component that only renders placeholder text. Pair every finding with
55
+ the smallest real boundary or implementation that would make it observable.
56
+
57
+ ## Write the report
58
+
59
+ Store the exact `git_commit`, timestamp, run count, commands and exit codes, the six
60
+ area results, findings with paths, verified seams, material omissions, residual risk,
61
+ and `passed` as the model's evidence-derived summary in the one canonical
62
+ `.ultra/test-report.json`. Each command records `command`, `exit_code`, and an
63
+ `evidence_ref`; each area records `status`, `evidence_refs`, and `omissions`. Copy the
64
+ script's `head`, `dirty`, and `diff_digest` into `git_commit` and `worktree`. A stale commit or digest is labelled stale;
65
+ it is never reused as current proof.
66
+
67
+ Present the findings by consequence and recommend the highest-leverage response. The
68
+ owner may fix all, fix selected findings, accept recorded risk, or reduce scope through
69
+ the normal REDUCTION decision. Recommend the next capability; do not invoke it.
70
+
71
+ ## When the owner decides
72
+
73
+ The owner decides disposition and risk acceptance. A failed command, orphan or stub is
74
+ an observation, not permission to auto-fix, weaken a test or silently change scope.
75
+
76
+ ## References
77
+
78
+ - `references/export-syntax.md` — read during Wiring Verification to find exported
79
+ symbol candidates in TypeScript/JavaScript, Python, Go, Rust and Java.
80
+ - `scripts/worktree_digest.cjs` — deterministic HEAD plus worktree evidence identity.
81
+ - `../ultra-think/references/autonomy-boundary.md` — read when a proposed response
82
+ would make an existing specification commitment stop holding.
@@ -0,0 +1,18 @@
1
+ # Export syntax lookup
2
+
3
+ Use this table to collect candidates, then confirm public reachability through the
4
+ repository's build system, framework registration and non-test consumers. Text matches
5
+ are observations, not semantic proof.
6
+
7
+ | Language | Candidate forms to search |
8
+ |---|---|
9
+ | TypeScript / JavaScript | `export function`, `export class`, `export const`, `export { name }`, `module.exports`, `exports.name` |
10
+ | Python | top-level `def` and `class`, names in `__all__`, public package re-exports; exclude leading-underscore names unless explicitly exported |
11
+ | Go | package-level identifiers beginning with an uppercase letter |
12
+ | Rust | `pub fn`, `pub struct`, `pub enum`, `pub trait`, `pub use`; respect module visibility such as `pub(crate)` |
13
+ | Java | `public` top-level types and public members reachable through the package's exposed API |
14
+
15
+ For every candidate changed by the current Change, search the exact symbol in non-test
16
+ source. Zero references is an orphan candidate. Before recording it, check declarative
17
+ framework entry points, reflection, dependency injection, generated code and foreign-
18
+ function bindings that may consume the symbol without a textual import.
@@ -0,0 +1,54 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ const crypto = require('node:crypto');
5
+ const fs = require('node:fs');
6
+ const path = require('node:path');
7
+ const { execFileSync } = require('node:child_process');
8
+
9
+ function git(cwd, args, encoding = 'utf8') {
10
+ return execFileSync('git', args, {
11
+ cwd,
12
+ encoding,
13
+ maxBuffer: 64 * 1024 * 1024,
14
+ stdio: ['ignore', 'pipe', 'pipe'],
15
+ });
16
+ }
17
+
18
+ function projectFromArgs(argv) {
19
+ if (argv.length === 0) return process.cwd();
20
+ if (argv.length === 2 && argv[0] === '--project' && argv[1]) return path.resolve(argv[1]);
21
+ throw new Error('usage: worktree_digest.cjs [--project <repository-root>]');
22
+ }
23
+
24
+ function main(cwd) {
25
+ const root = fs.realpathSync(git(cwd, ['rev-parse', '--show-toplevel']).trim());
26
+ const head = git(root, ['rev-parse', 'HEAD']).trim();
27
+ const diff = git(root, [
28
+ 'diff', '--binary', '--no-ext-diff', 'HEAD', '--', '.',
29
+ ':(exclude).ultra/test-report.json',
30
+ ], 'buffer');
31
+ const untracked = git(root, ['ls-files', '--others', '--exclude-standard', '-z'], 'buffer')
32
+ .toString('utf8').split('\0').filter(Boolean)
33
+ .filter((file) => file !== '.ultra/test-report.json')
34
+ .sort();
35
+ const hash = crypto.createHash('sha256');
36
+ hash.update('ultra-worktree-digest-v1\0').update(head).update('\0').update(diff);
37
+ for (const file of untracked) {
38
+ hash.update(file).update('\0').update(fs.readFileSync(path.join(root, file))).update('\0');
39
+ }
40
+ return {
41
+ $schema: 'ultra-worktree-digest-v1',
42
+ head,
43
+ dirty: diff.length > 0 || untracked.length > 0,
44
+ diff_digest: hash.digest('hex'),
45
+ untracked_files: untracked,
46
+ };
47
+ }
48
+
49
+ try {
50
+ process.stdout.write(`${JSON.stringify(main(projectFromArgs(process.argv.slice(2))), null, 2)}\n`);
51
+ } catch (error) {
52
+ process.stderr.write(`${error.message}\n`);
53
+ process.exitCode = 1;
54
+ }
@@ -1,39 +1,61 @@
1
1
  ---
2
2
  name: ultra-think
3
- description: Resolve a consequential product, architecture, or recovery question through evidence-first reasoning and adaptive user alignment. Use when a material decision cannot be derived safely from accepted intent and current evidence.
3
+ description: Stress-test one consequential product, architecture, recovery, or scope decision and preserve the accepted result when it must outlive the session. Use when another skill needs adversarial reasoning, or when fog of war is too large and unclear to decompose safely.
4
4
  ---
5
5
 
6
- # Align without suppressing judgment
6
+ # Turn one consequential uncertainty into an evidence-backed decision
7
7
 
8
- Thinking is optional. Answer self-contained questions directly. Persist only a
9
- project-bound decision that must survive interruption or control later work.
8
+ Thinking sharpens a decision; it does not perform the implementation that follows.
9
+ Persist only decisions that are hard to reverse, look surprising without context, and
10
+ arose from a real trade-off. All three criteria must hold.
10
11
 
11
- ## Reason and interact
12
+ ## Before you start
12
13
 
13
- 1. Call `ultra.context` for the relevant project or Change scope.
14
- 2. Define the real decision and the constraints that can change its answer.
15
- 3. Inspect source, runtime, tests, accepted artifacts, and primary documentation
16
- before asking the owner for facts.
17
- 4. Separate verified fact, evidence-backed inference, accepted intent, delegated
18
- implementation judgment, and unresolved owner choice.
19
- 5. Stress-test the leading answer with its strongest failure path and recovery.
14
+ 1. Read `.ultra/tasks.json` and the current task's `context_file` and `## Resume Note`.
15
+ 2. Read `CONTEXT.md`, relevant `.ultra/decisions/`, the active Change and its evidence.
16
+ 3. State the one decision and the assumptions capable of changing its answer.
20
17
 
21
- Read `references/interaction-boundary.md`. Reuse a clear decision already present in the
22
- request. Decide reversible delegated implementation details yourself. When owner
23
- authority is necessary, ask one dependent decision through the host-native question
24
- surface with a recommendation, decisive evidence, and the effect of the answer.
18
+ ## Definition of done
25
19
 
26
- ## Persist only the normalized result
20
+ - Claims are labelled Fact, Inference or Speculation and cite their evidence.
21
+ - The leading answer survived all four adversarial checks below.
22
+ - The conclusion includes Confidence %, Key Assumptions and What would change my mind.
23
+ - A qualifying durable decision is written once; a local reversible judgment is not.
27
24
 
28
- Use one `ultra.record` batch with `decision / accept` and, when required,
29
- `artifact / bind` for the owning semantic document. A revised answer carries
30
- `supersedes_id`; accepted records remain immutable history. Store normalized decisions
31
- and artifact references, never transcripts or internal reasoning.
25
+ ## Run the adversarial protocol
32
26
 
33
- A structural or authority rejection remains a mutable diagnostic. Correct the record;
34
- do not invent a new decision merely to satisfy a state machine. Semantic disagreement
35
- belongs in the recommendation and visible decision record, not a kernel error.
27
+ 1. **Steel Man**: build the strongest case for the option you expect to reject.
28
+ 2. **Pre-Mortem**: assume the choice failed six months later and name the three most
29
+ plausible causes.
30
+ 3. **Sensitivity**: identify the assumption whose failure would reverse the answer.
31
+ 4. **Second-Order**: describe the new constraints or failure modes created six to
32
+ twelve months later.
36
33
 
37
- Return the conclusion, decisive evidence, uncertainty, affected authority, and the
38
- model's recommended next explicit capability. Thinking never performs unrelated
39
- implementation or an external effect. Do not invoke the next capability automatically.
34
+ Give the owner one recommendation with the decisive evidence and what changes under
35
+ each viable answer. Reuse an answer already explicit in the request.
36
+
37
+ ## Use decision tickets for fog of war
38
+
39
+ When the work does not fit one session *and* the path itself remains unclear, map one
40
+ question instead of manufacturing implementation tasks. Write a decision ticket with
41
+ `status: open`; resolve one at a time until no unresolved ticket prevents planning.
42
+ Each answer should make the remaining fog of war smaller.
43
+
44
+ ## Write durable decisions
45
+
46
+ Use `.ultra/decisions/<id>.md`: question, status, options and real trade-offs, accepted
47
+ decision, owner, date, evidence, consequences, What would change my mind, and
48
+ `supersedes` when applicable. An accepted file is append-only history: overturn it by
49
+ writing a new decision that supersedes it.
50
+
51
+ ## When the owner decides
52
+
53
+ Only the owner accepts a durable decision or a REDUCTION. Reversible implementation
54
+ details stay with the model. If the host cannot ask, keep `status: open`, record the
55
+ missing answer and stop at that safe point.
56
+
57
+ ## References
58
+
59
+ - `references/autonomy-boundary.md` — read before changing accepted authority.
60
+ - `references/interaction-boundary.md` — read when the host-facing decision needs one
61
+ carefully framed question.
@@ -0,0 +1,48 @@
1
+ # The autonomy boundary and the specification-change verdict
2
+
3
+ Read this when an action is about to cross from "decide freely" into "surface to
4
+ the owner". It is the operational form of PHILOSOPHY C5, Bounded Autonomy; the
5
+ full constitution lives in the package's `docs/PHILOSOPHY.md`.
6
+
7
+ ## Inside the boundary — decide and proceed
8
+
9
+ Libraries, naming, file layout, internal abstractions, decomposition strategy,
10
+ evidence interpretation, prioritization, final expression.
11
+
12
+ ## Crossing the boundary — surface it
13
+
14
+ Weakening a test assertion, editing the specification to match the
15
+ implementation, shipping a feature flag that defaults off, replacing real
16
+ persistence with an in-memory stand-in, reducing scope, and any external or
17
+ irreversible effect.
18
+
19
+ ## Classifying a specification change
20
+
21
+ When the implementation and the specification disagree, classify before touching
22
+ the specification — and classify by one question that can be checked against the
23
+ file, never by intent:
24
+
25
+ > **Does every commitment the specification already made still hold after this
26
+ > change?**
27
+
28
+ | Answer | Classification | Action |
29
+ |---|---|---|
30
+ | Yes, and it now commits to more | EXPANSION | write it, log it |
31
+ | Yes, the commitment is unchanged but stated correctly | CORRECTION | write it, log it |
32
+ | **No — at least one prior commitment no longer holds** | **REDUCTION** | **stop and ask the owner** |
33
+
34
+ The classification follows from the outcome, never from the reason. A
35
+ well-argued rationale does not convert a REDUCTION into a CORRECTION; the
36
+ rationale goes into the question put to the owner.
37
+
38
+ This matters because it is the exact mechanism by which specifications shrink
39
+ silently. "The specification asked for offline mode, but the architecture makes
40
+ it unreasonable, so the specification was wrong" reads as a CORRECTION and
41
+ removes offline mode without anyone deciding to. Under the question above it is
42
+ a REDUCTION, because a commitment stopped holding.
43
+
44
+ ## Recording it
45
+
46
+ A boundary crossing produces either an owner question, an entry in the active task
47
+ context's `## Change Log`, or an accepted `.ultra/decisions/<id>.md` when the decision
48
+ outlives that task. Silence and a second drift ledger are not outcomes.
@@ -10,47 +10,32 @@ every write.
10
10
  acceptance, irreversible actions, external effects, and real-money commitments.
11
11
  - The host model investigates facts, recommends a direction, makes reversible
12
12
  implementation judgments, and explains uncertainty.
13
- - Use the host-native question surface declared by the installed interaction contract;
14
- prefer its structured form when the host exposes one.
15
- - `ultra.record` persists only the normalized result and its provenance.
16
- - MCP validates structure, identity, digests, CAS, leases, paths, and recovery. It does
17
- not decide whether a product answer is good.
13
+ - Use the host-native question surface when one exists; prefer its structured form.
14
+ - `.ultra/decisions/*.md` stores only a normalized durable result and bounded
15
+ provenance. Git supplies history and recovery.
18
16
 
19
17
  ## Interaction sequence
20
18
 
21
- 1. Read `ultra.context` for the relevant scope.
22
- 2. Inspect source, runtime, tests, accepted artifacts, and primary documentation.
19
+ 1. Read `.ultra/north-star.md`, `.ultra/tasks.json`, the active task context, relevant
20
+ specifications, Changes, decisions, and evidence.
21
+ 2. Inspect source, runtime, tests, and primary documentation for observable facts.
23
22
  3. Reuse an explicit choice already present in the current request or an accepted
24
- Decision Record.
23
+ decision file.
25
24
  4. Decide a reversible delegated detail without asking.
26
25
  5. When owner authority is still required, ask one unresolved owner choice at a time
27
- with:
28
- - the recommendation;
29
- - the discriminating evidence;
30
- - the meaningful cost or failure mode;
31
- - what changes when the answer changes.
32
- 6. Normalize the answer into a deterministic Decision Record and persist it with
33
- `ultra.record` using `kind: decision`, `action: accept`.
34
- 7. Read `ultra.context` back and verify that the accepted decision is visible before
35
- relying on it.
36
-
37
- ## Decision Record
38
-
39
- Persist only:
40
-
41
- - normalized question;
42
- - recommendation and selected answer;
43
- - effects and non-goals;
44
- - owner, source, and bounded provenance;
45
- - applied artifact references;
46
- - supersession link when revising an earlier answer.
26
+ with the recommendation, discriminating evidence, meaningful failure mode, and what
27
+ changes under each viable answer.
28
+ 6. Write a qualifying durable result to `.ultra/decisions/<id>.md` with question,
29
+ status, selected answer, effects, non-goals, owner, date, evidence, consequences,
30
+ and a supersession link when applicable.
31
+ 7. Read that file back before relying on it.
47
32
 
48
33
  Never persist raw transcripts, hidden reasoning, full prompts, UI receipts, or copied
49
- memory-provider payloads.
34
+ provider payloads.
50
35
 
51
36
  ## Revisions and interruptions
52
37
 
53
- Accepted decisions are immutable history. A changed answer creates a new Decision
54
- Record that supersedes the prior record. A cancelled question writes nothing. If a
55
- decision cannot be obtained, preserve the unresolved issue as a diagnostic or bounded
56
- event; do not invent an answer or block unrelated work.
38
+ Accepted decisions are append-only history. A changed answer creates a new file that
39
+ supersedes the prior decision. A cancelled question writes nothing. If the answer
40
+ cannot be obtained, keep the issue open in the active task context and stop only the
41
+ effect that requires that authority; unrelated work remains available.
@@ -1,55 +0,0 @@
1
- # Research Evidence
2
-
3
- Store durable research evidence here only when it is too detailed for the baseline
4
- specification. Baseline decisions and accepted behavior remain in `.ultra/specs/`.
5
-
6
- ## Initialization modes
7
-
8
- `ultra-init` creates the scaffold and records classification; it never runs research
9
- or approves a baseline. A later explicit `ultra-research` invocation handles:
10
-
11
- - greenfield baseline evidence with adaptive product and architecture coverage;
12
- - brownfield adoption of observed product, runtime, quality, operations, known
13
- failures, and documentation drift;
14
- - migrated or damaged authority only after backup-first `ultra-doctor` recovery,
15
- followed by evidence-backed brownfield adoption.
16
-
17
- Blank templates are never baseline evidence. Existing authority is preserved rather
18
- than replaced by this scaffold.
19
-
20
- ## Included-area reports
21
-
22
- Every included research area that executes, verifies, or reuses evidence writes one
23
- immutable report at `.ultra/docs/research/<workflow-id>/<step-id>.md`. The accepted
24
- coverage determines the report set; `full` and `adoption` describe baseline purpose,
25
- not a requirement to execute all seventeen catalog areas. Omitted areas create no
26
- report. The shared specifications are updated during research but do not replace these
27
- per-area evidence records.
28
-
29
- This directory is only for baseline establishment and adoption. Active Change research
30
- writes below
31
- `.ultra/changes/active/<change-id>/research/<workflow-id>/<step-id>.md`; it updates the
32
- Change overlay and never edits accepted baseline specifications.
33
-
34
- ## Report contract
35
-
36
- Record:
37
-
38
- - a Markdown title and the exact sections `Evidence`, `Specification updates`, and
39
- `Decisions and unknowns`;
40
- - scope and the decision the evidence informs;
41
- - observed facts with source references and dates;
42
- - verification commands or runtime evidence;
43
- - accepted decisions and their owner;
44
- - unresolved unknowns and whether they block the baseline;
45
- - links to the product or architecture sections updated from the evidence.
46
-
47
- Keep inference distinct from observation. Link to external provider content instead of
48
- copying memory, code-graph payloads, or large source material into Ultra.
49
-
50
- ## Completion
51
-
52
- Update the affected baseline specification, register the report through typed
53
- `ultra.record`, reference it from the Research Stage Checkpoint, and record unresolved
54
- work in the authoritative gap ledger. The final synthesis also binds the baseline
55
- specifications and research distillate. Do not create a condensed duplicate.
@@ -1,17 +0,0 @@
1
- {
2
- "$schema": "ultra-delivery-report-v1",
3
- "change_id": null,
4
- "archive_status": null,
5
- "baseline_id": null,
6
- "baseline_status": null,
7
- "git_commit": null,
8
- "worktree_digest": null,
9
- "context_digest": null,
10
- "checks": [],
11
- "release": {
12
- "authorized": false,
13
- "performed": false
14
- },
15
- "rollback": null,
16
- "timestamp": null
17
- }
@@ -1,18 +0,0 @@
1
- {
2
- "$schema": "ultra-test-report-v1",
3
- "change_id": null,
4
- "task_ids": [],
5
- "git_commit": null,
6
- "worktree_digest": null,
7
- "context_digest": null,
8
- "acceptance": [],
9
- "commands": [],
10
- "public_seams": [],
11
- "failures": [],
12
- "recovery": [],
13
- "regression_signal": null,
14
- "passed": false,
15
- "run_count": 0,
16
- "timestamp": null,
17
- "blocking_issues": ["Not yet run"]
18
- }
@@ -1,15 +0,0 @@
1
- {
2
- "kind": "ultra-team-task-ledger",
3
- "schema_version": "2.0",
4
- "generation": 0,
5
- "parent_digest": null,
6
- "ancestors": [],
7
- "state_digest": "88098433d797125bb0f87068a01205cf378494169ca93ee2a9dcf15c1c83dd63",
8
- "published_at": null,
9
- "reason": "scaffold",
10
- "baseline": null,
11
- "changes": [],
12
- "decisions": [],
13
- "checkpoints": [],
14
- "tasks": []
15
- }
@@ -1,19 +0,0 @@
1
- <!-- Runtime task views are generated under .ultra/.runtime/projections/contexts/. -->
2
-
3
- # Task Context Reference
4
-
5
- Use this file only as a structure reference. Runtime task context views are generated
6
- from SQLite authority and must not be edited by hand. Stable specification learning
7
- must follow the Change workflow.
8
-
9
- ## Implementation Notes
10
-
11
- - [Evidence-backed note with a source reference]
12
-
13
- ## Open Questions
14
-
15
- - [Question, consequence, owner, and next evidence]
16
-
17
- ## Recovery Notes
18
-
19
- - [Current safe resume point and any external prerequisite]