ultra-builder-pro-cli 0.17.1 → 0.19.1

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 (42) hide show
  1. package/CHANGELOG.md +77 -6
  2. package/README.md +380 -261
  3. package/adapters/_shared/codex-assets.cjs +24 -16
  4. package/adapters/_shared/file-ops.cjs +40 -3
  5. package/adapters/_shared/provenance.cjs +90 -6
  6. package/adapters/_shared/runtime-assets.cjs +0 -11
  7. package/adapters/claude.js +3 -1
  8. package/adapters/kimi.js +4 -30
  9. package/adapters/opencode.js +50 -14
  10. package/docs/AGENT-CONTEXT.md +11 -14
  11. package/docs/ARCHITECTURE.md +23 -15
  12. package/docs/DECISIONS.md +75 -0
  13. package/docs/LEGACY-CLI-CROSSWALK.md +3 -3
  14. package/docs/PLUGIN-ISOLATION-CONTRACT.md +54 -0
  15. package/docs/ROADMAP.md +13 -13
  16. package/docs/RUNTIME-COMPAT-MATRIX.md +24 -21
  17. package/docs/STATE-DB-ACCESS-POLICY.md +2 -2
  18. package/docs/WORKFLOW-LIFECYCLE.md +12 -10
  19. package/hooks/active_task_context.py +1 -1
  20. package/hooks/context_spine.py +1 -1
  21. package/hooks/health_check.py +19 -0
  22. package/hooks/pre_stop_check.py +1 -1
  23. package/hooks/workflow_checkpoint.py +1 -1
  24. package/hooks/workflow_context.py +1 -1
  25. package/hooks/workflow_resume.py +1 -1
  26. package/mcp-server/lib/workflow-state.cjs +67 -54
  27. package/mcp-server/server.cjs +19 -7
  28. package/orchestrator/dispatch-rules.cjs +1 -1
  29. package/package.json +4 -5
  30. package/skills/ultra-change/SKILL.md +4 -3
  31. package/skills/ultra-init/SKILL.md +2 -1
  32. package/skills/ultra-research/SKILL.md +7 -4
  33. package/spec/cli-protocol.md +4 -4
  34. package/spec/mcp-tools.yaml +6 -6
  35. package/spec/schemas/context-file.v4.5.schema.json +1 -1
  36. package/spec/schemas/mcp-tools.schema.json +3 -3
  37. package/spec/schemas/state-db.sql +3 -3
  38. package/spec/schemas/tasks.v4.5.schema.json +1 -1
  39. package/adapters/_shared/handbook.cjs +0 -156
  40. package/bin/handbook.js +0 -54
  41. package/docs/PLAN.zh-CN.md +0 -1696
  42. package/docs/USER-HANDBOOK-CONTRACT.md +0 -81
package/docs/USER-HANDBOOK-CONTRACT.md DELETED
@@ -1,81 +0,0 @@
1
- # Ultra Builder Pro — User Handbook Contract
2
-
3
- Ultra Builder Pro does not own a user's complete `CLAUDE.md` or `AGENTS.md`.
4
- Those files contain durable engineering doctrine for the host. The plugin owns
5
- only one small managed section describing its runtime boundary.
6
-
7
- ## Source and render targets
8
-
9
- `adapters/_shared/handbook.cjs` is the canonical source. It renders the common
10
- authority, baseline adoption, decision dialogue, Context Spine, specification-learning,
11
- memory, hook, agent, and package boundaries with host-native command syntax:
12
-
13
- | Runtime | Default target | Main invocation form |
14
- |---|---|---|
15
- | Claude Code | `~/.claude/CLAUDE.md` | `/ultra-plan` |
16
- | Codex | `~/.codex/AGENTS.md` | `$ultra-builder-pro:ultra-plan` |
17
- | OpenCode | `~/.config/opencode/AGENTS.md` | `/ultra-plan` |
18
- | Kimi Code | `~/.kimi-code/AGENTS.md` | `/ultra-builder-pro:ultra-plan` |
19
-
20
- The renderer never copies Claude Code-only APIs into Codex, OpenCode, or Kimi. Each
21
- host receives only its native invocation and collaboration names.
22
-
23
- The managed block deliberately stays short. It says that `.ultra/state.db` is
24
- authoritative; `change.context` compiles role/gate readiness, bounded references,
25
- fresh-context budget, public seam, and exact verification; size budgets are advisory,
26
- new ordinary work requires a healthy baseline, existing active work may continue with
27
- warnings, and only an approved incident break-glass may start without baseline
28
- readiness; ordinary archive restores baseline health while break-glass archive records
29
- a blocking reconciliation gap; hooks inject only the DB-derived
30
- `change.breadcrumb`; and unresolved specification learning or either failed review
31
- axis blocks convergence. Detailed procedures remain in the plugin skills so user
32
- handbooks do not accumulate duplicated prompt sediment.
33
-
34
- The decision boundary is intentionally short but normative: project-bound owner
35
- choices use one resumable DB-backed thread; the host resolves observable facts first,
36
- presents only one current decision with evidence and a recommendation, and stores the
37
- normalized result rather than conversation text. Matching workflows remain gated until
38
- blocking choices are resolved and the owner-approved artifact checkpoint is current.
39
-
40
- ## Managed-block contract
41
-
42
- The owned content is bounded by:
43
-
44
- ```markdown
45
- <!-- ultra-builder-pro:handbook:start -->
46
- ...
47
- <!-- ultra-builder-pro:handbook:end -->
48
- ```
49
-
50
- Rules outside those markers remain byte-for-byte user-owned. A malformed or
51
- duplicated marker pair is an error, not an invitation to guess. For Codex only,
52
- the first apply can migrate the old unmarked
53
- `## Ultra Builder Pro Runtime Contract` section up to the next level-two heading.
54
-
55
- ## Safe workflow
56
-
57
- Preview the full merged result before applying:
58
-
59
- ```bash
60
- ubp-handbook preview --runtime claude
61
- ubp-handbook preview --runtime codex
62
- ubp-handbook preview --runtime opencode
63
- ubp-handbook preview --runtime kimi
64
- ```
65
-
66
- Apply when the preview is correct:
67
-
68
- ```bash
69
- ubp-handbook apply --runtime claude
70
- ubp-handbook apply --runtime codex
71
- ubp-handbook apply --runtime opencode
72
- ubp-handbook apply --runtime kimi
73
- ```
74
-
75
- An existing target is copied to
76
- `<file>.ubp-backup-<timestamp>` before the atomic replacement. Re-running apply
77
- with the same rendered content is a no-op and creates no additional backup.
78
-
79
- The plugin installer intentionally does not apply this section implicitly. A
80
- plugin update and a durable user-handbook change have different rollback and
81
- review requirements, so handbook mutation stays explicit.