@webpresso/agent-kit 0.21.4 → 0.21.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.
Files changed (94) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/README.md +105 -41
  3. package/catalog/agent/skills/plan-refine/SKILL.md +5 -4
  4. package/catalog/base-kit/commitlint.config.ts.tmpl +1 -3
  5. package/catalog/base-kit/e2e/fixtures/smoke.html.tmpl +13 -0
  6. package/catalog/base-kit/e2e/smoke.spec.ts.tmpl +13 -0
  7. package/catalog/base-kit/oxlint.config.ts.tmpl +26 -0
  8. package/catalog/base-kit/playwright.config.ts.tmpl +10 -0
  9. package/catalog/base-kit/src/quality-sample.test.ts.tmpl +19 -0
  10. package/catalog/base-kit/src/quality-sample.ts.tmpl +11 -0
  11. package/catalog/base-kit/stryker.config.ts.tmpl +14 -0
  12. package/catalog/base-kit/tsconfig.json.tmpl +9 -0
  13. package/catalog/base-kit/vitest.config.ts.tmpl +10 -0
  14. package/catalog/docs/templates/adr.md +1 -1
  15. package/catalog/docs/templates/blueprint.md +1 -0
  16. package/catalog/docs/templates/blueprint.yaml +6 -3
  17. package/catalog/docs/templates/guide.md +1 -1
  18. package/catalog/docs/templates/postmortem.md +1 -1
  19. package/catalog/docs/templates/research.md +1 -1
  20. package/catalog/docs/templates/runbook.md +1 -1
  21. package/catalog/docs/templates/system.md +12 -3
  22. package/catalog/docs/templates/tech-debt.md +1 -0
  23. package/commands/blueprint.md +37 -4
  24. package/dist/esm/audit/resolve-audit-script.d.ts +24 -0
  25. package/dist/esm/audit/resolve-audit-script.js +27 -0
  26. package/dist/esm/blueprint/index.d.ts +0 -1
  27. package/dist/esm/blueprint/index.js +0 -2
  28. package/dist/esm/blueprint/local.d.ts +0 -3
  29. package/dist/esm/blueprint/local.js +0 -2
  30. package/dist/esm/blueprint/service/BlueprintCreationService.js +5 -2
  31. package/dist/esm/blueprint/utils/package-assets.d.ts +11 -0
  32. package/dist/esm/blueprint/utils/package-assets.js +33 -4
  33. package/dist/esm/build/sync-catalog-doc-templates.d.ts +23 -0
  34. package/dist/esm/build/sync-catalog-doc-templates.js +93 -0
  35. package/dist/esm/cli/commands/audit.js +2 -7
  36. package/dist/esm/cli/commands/blueprint/router.js +5 -2
  37. package/dist/esm/cli/commands/blueprint/template-resolver.js +8 -4
  38. package/dist/esm/cli/commands/init/host-visibility.js +4 -2
  39. package/dist/esm/cli/commands/init/index.js +46 -7
  40. package/dist/esm/cli/commands/init/scaffold-base-kit.d.ts +12 -0
  41. package/dist/esm/cli/commands/init/scaffold-base-kit.js +141 -6
  42. package/dist/esm/cli/commands/typecheck.js +10 -4
  43. package/dist/esm/e2e/command-builder.js +26 -7
  44. package/dist/esm/e2e/execution.js +4 -0
  45. package/dist/esm/e2e/run-planner.js +1 -0
  46. package/dist/esm/e2e/types.d.ts +1 -0
  47. package/dist/esm/format/index.js +7 -1
  48. package/dist/esm/lint/index.js +3 -1
  49. package/dist/esm/mcp/blueprint-server.js +361 -66
  50. package/dist/esm/mcp/tools/audit.js +2 -8
  51. package/dist/esm/mcp/tools/e2e.d.ts +1 -1
  52. package/dist/esm/package.json +3 -0
  53. package/dist/esm/test/command-builder.d.ts +1 -0
  54. package/dist/esm/test/command-builder.js +8 -2
  55. package/dist/esm/test-helpers/hermetic-env.d.ts +25 -0
  56. package/dist/esm/test-helpers/hermetic-env.js +31 -0
  57. package/dist/esm/tool-runtime/index.d.ts +5 -0
  58. package/dist/esm/tool-runtime/index.js +23 -0
  59. package/dist/esm/tool-runtime/resolve-runner.d.ts +13 -0
  60. package/dist/esm/tool-runtime/resolve-runner.js +40 -0
  61. package/package.json +12 -19
  62. package/skills/plan-refine/SKILL.md +5 -4
  63. package/dist/esm/blueprint/dag/cycle-detector.d.ts +0 -12
  64. package/dist/esm/blueprint/dag/cycle-detector.js +0 -46
  65. package/dist/esm/blueprint/dag/executor.d.ts +0 -140
  66. package/dist/esm/blueprint/dag/executor.js +0 -292
  67. package/dist/esm/blueprint/dag/index.d.ts +0 -20
  68. package/dist/esm/blueprint/dag/index.js +0 -17
  69. package/dist/esm/blueprint/dag/interfaces.d.ts +0 -56
  70. package/dist/esm/blueprint/dag/interfaces.js +0 -13
  71. package/dist/esm/blueprint/dag/local/independence.d.ts +0 -107
  72. package/dist/esm/blueprint/dag/local/independence.js +0 -231
  73. package/dist/esm/blueprint/dag/local/index.d.ts +0 -14
  74. package/dist/esm/blueprint/dag/local/index.js +0 -14
  75. package/dist/esm/blueprint/dag/local/package-graph.d.ts +0 -66
  76. package/dist/esm/blueprint/dag/local/package-graph.js +0 -148
  77. package/dist/esm/blueprint/dag/plan-parser.d.ts +0 -54
  78. package/dist/esm/blueprint/dag/plan-parser.js +0 -236
  79. package/dist/esm/blueprint/dag/task-graph-algorithms.d.ts +0 -13
  80. package/dist/esm/blueprint/dag/task-graph-algorithms.js +0 -236
  81. package/dist/esm/blueprint/dag/task-graph.d.ts +0 -171
  82. package/dist/esm/blueprint/dag/task-graph.js +0 -370
  83. package/dist/esm/blueprint/dag/types.d.ts +0 -17
  84. package/dist/esm/blueprint/dag/types.js +0 -2
  85. package/dist/esm/blueprint/graph/index.d.ts +0 -5
  86. package/dist/esm/blueprint/graph/index.js +0 -5
  87. package/dist/esm/blueprint/graph/mermaid-parser.d.ts +0 -3
  88. package/dist/esm/blueprint/graph/mermaid-parser.js +0 -93
  89. package/dist/esm/blueprint/graph/mermaid-serializer.d.ts +0 -3
  90. package/dist/esm/blueprint/graph/mermaid-serializer.js +0 -20
  91. package/dist/esm/blueprint/graph/schema.d.ts +0 -89
  92. package/dist/esm/blueprint/graph/schema.js +0 -104
  93. package/dist/esm/blueprint/graph/task-graph-adapter.d.ts +0 -6
  94. package/dist/esm/blueprint/graph/task-graph-adapter.js +0 -30
@@ -6,7 +6,7 @@
6
6
  },
7
7
  "metadata": {
8
8
  "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
9
- "version": "0.21.4"
9
+ "version": "0.21.5"
10
10
  },
11
11
  "plugins": [
12
12
  {
@@ -23,5 +23,5 @@
23
23
  ]
24
24
  }
25
25
  ],
26
- "version": "0.21.4"
26
+ "version": "0.21.5"
27
27
  }
package/README.md CHANGED
@@ -1,8 +1,9 @@
1
1
  # @webpresso/agent-kit
2
2
 
3
- > Plug-and-play setup for AI coding agents. Run one command and every agent in
4
- > the repo gets the same instructions, skills, hooks, planning files, and quality
5
- > gates. MIT. Experimental v0.x.
3
+ > TypeScript infrastructure for AI-agent-driven development. One `wp` runtime
4
+ > gives agents planning, tests, mutation, e2e, CI, docs, and debt tracking —
5
+ > all summary-first so they keep context, and enforced as contracts so docs,
6
+ > intent, and code can't drift. MIT. Experimental v0.x.
6
7
 
7
8
  ## Install
8
9
 
@@ -25,58 +26,120 @@ If you do not want a global install, run it one-shot instead:
25
26
  npm exec --yes --package @webpresso/agent-kit@latest -- wp setup
26
27
  ```
27
28
 
28
- `wp setup` is safe to run again. It refreshes the webpresso-owned pieces and
29
+ `wp setup` is safe to run again. It refreshes the webpresso-owned pieces,
30
+ creates the default `base-kit` quality scaffold when files are absent, and
29
31
  preserves consumer-owned files.
30
32
 
31
- ## What it gives you
33
+ The guarantee is **zero hand-wiring**, not zero local dependencies. Fresh repos
34
+ get starter `tsconfig`, Vitest, Oxlint, Stryker, Playwright, unit-test, and
35
+ file-based e2e smoke assets. Repos still keep authoring-time dependencies that
36
+ their configs and tests import directly.
32
37
 
33
- - **One repo brain** major coding agents read the same operating contract.
34
- - **Skills that travel** repo skills show up across supported agent surfaces.
35
- - **Hooks that help** generated hooks steer common work through repo quality gates.
36
- - **Blueprints by default** planning files and templates are ready when the task needs them, and Blueprint markdown stays the canonical plan while OMX handoff files remain derived metadata.
37
- - **Agent-friendly checks** — tests, lint, typecheck, E2E, and audits are easy to run and cite.
38
- - **Context-efficient evidence by default** — `wp_*` MCP wrappers return
39
- compact test/lint/typecheck/audit summaries, and `wp setup` includes `rtk`
40
- in its default workstation preset set.
38
+ Default workstation presets are separate from repo bootstrap. `omx`, `omc`,
39
+ `gstack`, `vision`, `rtk`, and `context-mode` are requested by default and
40
+ degrade with explicit skipped/warning output when the matching host or auth is
41
+ unavailable. The repo bootstrap is `base-kit`.
41
42
 
42
- ## Why it exists
43
+ ### Execution-owned vs authoring-owned dependencies
44
+
45
+ `wp` now owns **execution** for the generic tool lanes it manages:
46
+
47
+ - test / mutation
48
+ - e2e
49
+ - lint
50
+ - format
51
+ - typecheck
43
52
 
44
- AI-agent repos usually grow six copies of the same thing:
53
+ That does **not** mean every local devDependency should disappear.
45
54
 
46
- - one instruction file for Claude,
47
- - another for Codex,
48
- - another for Cursor,
49
- - separate hooks,
50
- - separate skills,
51
- - separate planning conventions.
55
+ - Keep local dependencies that your repo **imports directly** from tests,
56
+ config files, or tsconfig types — for example `vitest`,
57
+ `@playwright/test`, `@testing-library/jest-dom`, or `typescript`.
58
+ - Review execution-only binaries for removal **only if** they were installed
59
+ just to invoke them locally and nothing imports them directly — for example
60
+ `oxlint`, `oxfmt`, or `markdownlint-cli2`.
52
61
 
53
- Those copies drift. webpresso makes the repo feel like one product again:
62
+ `wp setup` prints this migration guidance after scaffolding so consumers do not
63
+ accidentally strip authoring-time dependencies just because `wp` can execute
64
+ the tool.
65
+
66
+ Public install claims are checked against the packed artifact with:
54
67
 
55
68
  ```bash
56
- wp setup
69
+ vp run public:consumer-smoke -- --setup-only
57
70
  ```
58
71
 
59
- ## Why agents keep more useful context
72
+ Use the full smoke without `--setup-only` when you want to install the generated
73
+ starter dependencies and run the generated quality commands.
74
+
75
+ ## What it does
76
+
77
+ `wp` is the toolkit agents use to do real work in a repo. Every piece is built
78
+ on two properties that make it *agent-grade* rather than yet-another-bundle:
79
+ its output is **summary-first** (agents keep context) and it is **enforced**
80
+ (pre-commit + CI gates, not just available).
81
+
82
+ ### The toolkit
83
+
84
+ - **Planning** — blueprints: markdown plans with a lifecycle
85
+ (`wp audit blueprint-lifecycle`) and a dependency-aware task graph.
86
+ `wp_blueprint_depgraph` returns its dependency graph (nodes + edges), and
87
+ optional runtime adapters (OMX `/pll`) use those dependencies to run
88
+ independent tasks in parallel.
89
+ Authoring now has a structured control plane: `wp_blueprint_put` writes the
90
+ blueprint from typed input and `wp_blueprint_transition` advances lifecycle
91
+ state with revision-aware optimistic concurrency. A future MCP Apps editor is
92
+ explicitly a follow-on enhancement layered on top of those tools, not a
93
+ separate required write surface. See [`docs/lifecycle.md`](docs/lifecycle.md).
94
+ - **Tests, types, lint** — `wp_test`, `wp_typecheck`, `wp_lint` over your
95
+ vitest/oxlint setup.
96
+ - **Mutation testing** — `wp audit mutation` (Stryker) catches tests that pass
97
+ without actually asserting.
98
+ - **End-to-end** — `wp_e2e` runs suite-aware Playwright flows.
99
+ - **CI, locally** — `wp_ci_act` runs your GitHub Actions through `act` behind
100
+ the repo secret contract.
101
+ - **Docs** — `wp docs lint` and `wp audit docs-frontmatter` keep docs
102
+ structured and current.
103
+ - **Tech-debt** — `wp tech-debt` tracks debt through a status lifecycle
104
+ (accepted → needs-remediation → monitoring → resolved), auto-filed from
105
+ failing audits.
106
+
107
+ ### What makes it agent-grade
108
+
109
+ - **Summary-first output** — the `wp_*` MCP wrappers return summary-first JSON
110
+ with clipped raw output and budget metadata (`bytes`, `tokensSaved`), and
111
+ `wp setup` wires the `rtk` and `context-mode` output-filtering lanes by
112
+ default (skipped in CI and via `WP_SKIP_RTK=1` / `WP_SKIP_CONTEXT_MODE=1`;
113
+ never bundled in the package). Agents reason over the failure set, not the
114
+ thousand-line log. See [`docs/qa-output.md`](docs/qa-output.md).
115
+ - **Enforced as contracts** — `wp audit vision` keeps `VISION.md` current,
116
+ `wp audit architecture-drift` keeps architecture docs aligned with the
117
+ implementation they describe, `wp audit bundle-budget` caps client output,
118
+ and the Lore commit protocol (`wp audit commit-message --require-lore`)
119
+ records the *why* behind each change. Every audit runs as a `wp_audit` MCP
120
+ tool **and** as a pre-commit and CI gate — so intent, docs, and code can't
121
+ silently diverge.
122
+ - **One operating contract, managed for you** — `wp` generates and keeps your
123
+ `AGENTS.md`, `CLAUDE.md`, and each agent's command, skill, and hook surfaces
124
+ in sync, emitted through rulesync across every supported runtime (see
125
+ [`catalog/agent/rules/supported-agent-clis.md`](catalog/agent/rules/supported-agent-clis.md)).
126
+ `AGENTS.md` is the standard; `wp` keeps everything around it coherent.
60
127
 
61
- Coding agents waste context in two predictable ways: duplicated repo guidance and
62
- verbose tool output. Agent Kit attacks both:
128
+ ## Why it exists
129
+
130
+ Sharing instructions across agents is largely solved: `AGENTS.md` is the
131
+ standard, and emitters like rulesync fan one source out to every runtime. `wp`
132
+ manages that layer for you — but the hard part of agent-driven development isn't
133
+ a missing instruction file. It is keeping agents **effective** (they burn the
134
+ context window on verbose tool output) and keeping the repo **correct** (docs,
135
+ plans, and code drift apart as agents move fast).
63
136
 
64
- - **Default compact quality evidence:** `wp_test`, `wp_lint`, `wp_typecheck`, `wp_qa`,
65
- `wp_e2e`, and `wp_audit` are MCP-first wrappers that return summary-first
66
- JSON, clipped raw output, and budget metadata such as `bytes` and
67
- `tokensSaved`. See [`docs/qa-output.md`](docs/qa-output.md).
68
- - **Default RTK shell filtering lane:** `wp setup` includes `rtk` in its
69
- default preset set. The setup command skips RTK in CI and when
70
- `WP_SKIP_RTK=1` is set. See [`docs/add-ons.md`](docs/add-ons.md).
71
- - **Default context-mode lane:** `wp setup` includes `context-mode` in its
72
- default preset set. The setup command skips context-mode in CI and when
73
- `WP_SKIP_CONTEXT_MODE=1` is set, and the published package still does not
74
- bundle the external tool. See
75
- [`docs/migration/context-mode-default.md`](docs/migration/context-mode-default.md).
137
+ `wp` is the TypeScript layer for both: summary-first tooling so the window goes
138
+ to code, and enforced contracts so the work stays coherent.
76
139
 
77
- The result: agents spend more of the window on code, plans, decisions, and
78
- errors that matter, and less on repeated instructions or thousand-line command
79
- logs.
140
+ ```bash
141
+ wp setup
142
+ ```
80
143
 
81
144
  ## Add-ons
82
145
 
@@ -92,6 +155,7 @@ If you need config subpaths or dependency references, use the appendix:
92
155
 
93
156
  - [Getting started](docs/getting-started.md)
94
157
  - [Is webpresso for me?](docs/is-agent-kit-for-me.md)
158
+ - [Blueprint lifecycle](docs/lifecycle.md)
95
159
  - [Add-ons](docs/add-ons.md)
96
160
  - [Blueprint format](docs/blueprint-format.md)
97
161
  - [Skills catalog](docs/skills-catalog.md)
@@ -16,10 +16,11 @@ description: Methodology for refining, fact-checking, and hardening implementati
16
16
  >
17
17
  > Blueprint hardening and lifecycle infrastructure are production-ready:
18
18
  >
19
- > - Kahn's Algorithm DAG analysis (fully tested)
20
- > - `ParallelExecutor` concurrency engine with abort, timeout, per-type limits
21
- > - Blueprint dependency format and validation
22
- > - Failed tasks block dependents automatically
19
+ > - Blueprint dependency parsing, format validation, and the lifecycle state
20
+ > machine with evidence-gated task completion (fully tested, in-package)
21
+ > - Parallel execution is delegated to the `/pll` runtime adapter (OMX), which
22
+ > batches independent tasks by dependency order and blocks dependents of
23
+ > failed tasks
23
24
  >
24
25
  > **Remaining gaps:** execution docs and wrappers must stay aligned with the currently shipped runtime and CLI surface.
25
26
 
@@ -1,6 +1,4 @@
1
- import type { UserConfig } from '@commitlint/types'
2
-
3
- const config: UserConfig = {
1
+ const config = {
4
2
  extends: ['@commitlint/config-conventional'],
5
3
  }
6
4
 
@@ -0,0 +1,13 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <title>Agent Kit smoke page</title>
6
+ </head>
7
+ <body>
8
+ <main>
9
+ <h1>Agent Kit quality scaffold</h1>
10
+ <p data-testid="status">ready</p>
11
+ </main>
12
+ </body>
13
+ </html>
@@ -0,0 +1,13 @@
1
+ import { expect, test } from '@playwright/test'
2
+ import { readFile } from 'node:fs/promises'
3
+ import { join } from 'node:path'
4
+
5
+ const smokePagePath = join(process.cwd(), 'e2e', 'fixtures', 'smoke.html')
6
+
7
+ test('checks the file-based smoke page', async () => {
8
+ const html = await readFile(smokePagePath, 'utf8')
9
+
10
+ expect(html).toContain('Agent Kit quality scaffold')
11
+ expect(html).toContain('data-testid="status"')
12
+ expect(html).toContain('ready')
13
+ })
@@ -0,0 +1,26 @@
1
+ import { config } from '@webpresso/agent-kit/oxlint'
2
+
3
+ const oxlintConfig: Record<string, unknown> = {
4
+ ...config,
5
+ env: {
6
+ builtin: true,
7
+ node: true,
8
+ },
9
+ ignorePatterns: [
10
+ 'dist',
11
+ 'node_modules',
12
+ 'reports',
13
+ '.stryker-tmp',
14
+ '.agent',
15
+ '.agents',
16
+ '.claude',
17
+ '.codex',
18
+ '.cursor',
19
+ '.gemini',
20
+ '.opencode',
21
+ '.omx',
22
+ '.windsurf',
23
+ ],
24
+ }
25
+
26
+ export default oxlintConfig
@@ -0,0 +1,10 @@
1
+ import { defineConfig } from '@playwright/test'
2
+
3
+ export default defineConfig({
4
+ testDir: './e2e',
5
+ fullyParallel: true,
6
+ reporter: [['list']],
7
+ use: {
8
+ trace: 'retain-on-failure',
9
+ },
10
+ })
@@ -0,0 +1,19 @@
1
+ import { describe, expect, it } from 'vitest'
2
+
3
+ import { add, clamp } from './quality-sample.js'
4
+
5
+ describe('quality sample', () => {
6
+ it('adds two numbers', () => {
7
+ expect(add(2, 3)).toBe(5)
8
+ })
9
+
10
+ it('clamps values below, inside, and above the range', () => {
11
+ expect(clamp(-1, 0, 10)).toBe(0)
12
+ expect(clamp(5, 0, 10)).toBe(5)
13
+ expect(clamp(11, 0, 10)).toBe(10)
14
+ })
15
+
16
+ it('rejects an invalid range', () => {
17
+ expect(() => clamp(1, 10, 0)).toThrow(RangeError)
18
+ })
19
+ })
@@ -0,0 +1,11 @@
1
+ export function add(left: number, right: number): number {
2
+ return left + right
3
+ }
4
+
5
+ export function clamp(value: number, min: number, max: number): number {
6
+ if (min > max) {
7
+ throw new RangeError('min must be less than or equal to max')
8
+ }
9
+
10
+ return Math.min(Math.max(value, min), max)
11
+ }
@@ -0,0 +1,14 @@
1
+ import { baseConfig } from '@webpresso/agent-kit/stryker'
2
+
3
+ export default {
4
+ ...baseConfig,
5
+ thresholds: {
6
+ high: 0,
7
+ low: 0,
8
+ break: 0,
9
+ },
10
+ vitest: {
11
+ configFile: 'vitest.config.ts',
12
+ },
13
+ mutate: ['src/**/*.ts', '!src/**/*.test.ts', '!src/**/*.d.ts'],
14
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "extends": "./node_modules/@webpresso/agent-kit/tsconfig/base.json",
3
+ "compilerOptions": {
4
+ "types": ["node", "vitest/globals"],
5
+ "noEmit": true
6
+ },
7
+ "include": ["src/**/*.ts", "test/**/*.ts", "e2e/**/*.ts", "*.config.ts"],
8
+ "exclude": ["node_modules", "dist", "reports", ".stryker-tmp"]
9
+ }
@@ -0,0 +1,10 @@
1
+ import { defineConfig } from 'vitest/config'
2
+
3
+ export default defineConfig({
4
+ test: {
5
+ globals: true,
6
+ environment: 'node',
7
+ include: ['src/**/*.test.ts'],
8
+ exclude: ['e2e/**', 'node_modules/**', '.stryker-tmp/**'],
9
+ },
10
+ })
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: adr
3
- last_updated: "YYYY-MM-DD"
3
+ last_updated: "2026-05-27"
4
4
  ---
5
5
 
6
6
  # ADR NNNN: {{Title}}
@@ -6,6 +6,7 @@ created: '2026-04-22'
6
6
  last_updated: '2026-04-22'
7
7
  progress: '0% (drafted)'
8
8
  depends_on: []
9
+ cross_repo_depends_on: []
9
10
  tags: []
10
11
  ---
11
12
 
@@ -21,12 +21,15 @@ frontmatter:
21
21
  format: YYYY-MM-DD
22
22
  description: Last modification date
23
23
  optional:
24
- parent:
24
+ parent_roadmap:
25
25
  type: string
26
- description: Path to parent epic (e.g., ../README.md)
26
+ description: Local parent-roadmap slug/path in the same repo
27
27
  depends_on:
28
28
  type: array
29
- description: Dependencies on other plans
29
+ description: Local blueprint dependencies in the same repo
30
+ cross_repo_depends_on:
31
+ type: array
32
+ description: Cross-repo blueprint dependencies expressed as { repo, slug, require_status? }
30
33
 
31
34
  sections:
32
35
  required: []
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: guide
3
- last_updated: "YYYY-MM-DD"
3
+ last_updated: "2026-05-27"
4
4
  ---
5
5
 
6
6
  # {{Title}}
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: postmortem
3
- last_updated: "YYYY-MM-DD"
3
+ last_updated: "2026-05-27"
4
4
  ---
5
5
 
6
6
  # Postmortem: {{Incident Title}}
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: research
3
- last_updated: "YYYY-MM-DD"
3
+ last_updated: "2026-05-27"
4
4
  ---
5
5
 
6
6
  # {{Research Title}}
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: runbook
3
- last_updated: "YYYY-MM-DD"
3
+ last_updated: "2026-05-27"
4
4
  ---
5
5
 
6
6
  # Runbook: {{Scenario}}
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  type: system
3
- last_updated: "YYYY-MM-DD"
3
+ last_updated: "2026-05-27"
4
4
  ---
5
5
 
6
6
  # {{System Name}}
@@ -11,8 +11,17 @@ last_updated: "YYYY-MM-DD"
11
11
 
12
12
  ## Architecture
13
13
 
14
- ```text
15
- [Diagram showing the main components and their edges]
14
+ ```mermaid
15
+ flowchart LR
16
+ A[Main component] --> B[Dependency or downstream system]
17
+ ```
18
+
19
+ ## Infrastructure / deployment
20
+
21
+ ```mermaid
22
+ flowchart LR
23
+ CI[Deploy entry point] --> RUNTIME[Runtime surface]
24
+ INFRA[Durable infrastructure owner] --> STATE[(Stateful resource)]
16
25
  ```
17
26
 
18
27
  ## Key invariants
@@ -5,6 +5,7 @@ severity: '{{severity}}'
5
5
  category: '{{category}}'
6
6
  review_cadence: quarterly
7
7
  last_reviewed: '{{date}}'
8
+ last_updated: '2026-05-27'
8
9
  created: '{{date}}'
9
10
  linked_blueprints: []
10
11
  affected_modules: []
@@ -8,6 +8,8 @@ Use the focused blueprint MCP tools.
8
8
  - `wp_blueprint_get` — fetch one blueprint with freshness metadata
9
9
  - `wp_blueprint_context` — assemble bounded task context
10
10
  - `wp_blueprint_create` — create a draft blueprint; requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe, stale-write-safe creation
11
+ - `wp_blueprint_put` — whole-document structured authoring; writes the canonical blueprint markdown from typed input and returns revision metadata
12
+ - `wp_blueprint_transition` — optimistic-concurrency lifecycle transition; requires `expected_version` and returns updated revision metadata
11
13
  - `wp_blueprint_task_next` — return the next ready task; accepts optional `project_id` when the current cwd is a multi-repo workspace container
12
14
  - `wp_blueprint_task_advance` — change task status (non-`done`); requires `project_id` and accepts optional `request_id` and `head_at_ingest` for retry-safe mutation
13
15
  - `wp_blueprint_task_verify` — mark a task `done` with evidence; accepts optional `request_id` and `head_at_ingest` for retry-safe verification
@@ -15,14 +17,45 @@ Use the focused blueprint MCP tools.
15
17
 
16
18
  Mutation guidance:
17
19
 
18
- - Use `request_id` on `wp_blueprint_create`, `wp_blueprint_task_advance`, and
19
- `wp_blueprint_task_verify` when the caller may retry the same request.
20
+ - V1 structured authoring is limited to `wp_blueprint_put + wp_blueprint_transition`.
21
+ - Use `request_id` on `wp_blueprint_create`, `wp_blueprint_put`,
22
+ `wp_blueprint_task_advance`, and `wp_blueprint_task_verify` when the caller
23
+ may retry the same request.
20
24
  - Prefer passing `project_id` from `wp_blueprint_projects` whenever the current
21
25
  working directory can see more than one blueprint-bearing repo.
22
26
  - Carry `head_at_ingest` from `wp_blueprint_list`, `wp_blueprint_get`, or
23
- `wp_blueprint_context` into mutation calls when the caller needs stale-write
24
- protection across retries or multi-agent handoff.
27
+ `wp_blueprint_context` into `wp_blueprint_create`, `wp_blueprint_put`, and
28
+ other mutation calls when the caller needs stale-write protection across
29
+ retries or multi-agent handoff.
25
30
  - Reusing the same `request_id` with the same payload is idempotent.
26
31
  - Reusing the same `request_id` with a different payload is rejected.
27
32
  - If `head_at_ingest` is stale, the mutation is rejected and points the caller
28
33
  back to a canonical `wp_*` refresh path.
34
+ - `wp_blueprint_transition` uses `expected_version` (the current
35
+ `content_hash`) for blueprint-scoped optimistic concurrency.
36
+
37
+ Deferred patch boundary:
38
+
39
+ - `wp_blueprint_patch` is **not** part of the v1 canonical surface.
40
+ - If/when added, the patch model must be **semantic**, not raw markdown
41
+ mutation.
42
+ - Minimum deferred operations:
43
+ - `add_task`
44
+ - `update_task`
45
+ - `set_summary`
46
+ - `replace_decision`
47
+ - Until then, whole-document `wp_blueprint_put` is the canonical authoring path.
48
+
49
+ Deferred UI/editor boundary:
50
+
51
+ - A future MCP Apps blueprint editor is an **enhancement**, not part of the v1
52
+ correctness path.
53
+ - Any UI flow must layer on top of `wp_blueprint_put + wp_blueprint_transition`
54
+ instead of introducing a parallel write surface.
55
+ - Hosts without MCP Apps support must still complete the full authoring flow
56
+ through the structured tools alone.
57
+ - Minimum v2 editor contract:
58
+ - capability detection for MCP Apps support
59
+ - structured form/editor over the full blueprint document
60
+ - non-UI fallback guidance that routes back to `wp_blueprint_put` and
61
+ `wp_blueprint_transition`
@@ -0,0 +1,24 @@
1
+ export interface ResolveAuditScriptDeps {
2
+ /** `import.meta.url` of the calling module (`cli/commands/audit` or `mcp/tools/audit`). */
3
+ moduleUrl: string;
4
+ /** Existence probe; defaults to `fs.existsSync`. Injected in tests to model each layout. */
5
+ exists?: (url: URL) => boolean;
6
+ }
7
+ /**
8
+ * Resolve the absolute path of a Bun audit script (`audit-tph.ts`,
9
+ * `audit-tph-e2e.ts`) living in the sibling `audit/` directory two levels up
10
+ * from the caller.
11
+ *
12
+ * `../../audit/` is correct relative to the caller in BOTH layouts:
13
+ * - dev: `src/{cli,mcp}/.../audit.ts` → `src/audit/`
14
+ * - published: `dist/esm/{cli,mcp}/.../audit.js` → `dist/esm/audit/`
15
+ *
16
+ * The npm tarball ships only `dist/` (never `src/`), so the dev `.ts` source is
17
+ * absent there — fall back to the compiled `.js` sibling the build emits. The
18
+ * previous CLI resolver instead hand-rolled a `<bundle>/src/audit/<name>.ts`
19
+ * path that does not exist in dist, which made `bun` fail with
20
+ * "Module not found"; the MCP twin reached for the unshipped `src/audit/` via
21
+ * `resolvePackageAsset` and failed the same way.
22
+ */
23
+ export declare function resolveAuditScriptPath(name: string, { moduleUrl, exists }: ResolveAuditScriptDeps): string;
24
+ //# sourceMappingURL=resolve-audit-script.d.ts.map
@@ -0,0 +1,27 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { fileURLToPath } from 'node:url';
3
+ /**
4
+ * Resolve the absolute path of a Bun audit script (`audit-tph.ts`,
5
+ * `audit-tph-e2e.ts`) living in the sibling `audit/` directory two levels up
6
+ * from the caller.
7
+ *
8
+ * `../../audit/` is correct relative to the caller in BOTH layouts:
9
+ * - dev: `src/{cli,mcp}/.../audit.ts` → `src/audit/`
10
+ * - published: `dist/esm/{cli,mcp}/.../audit.js` → `dist/esm/audit/`
11
+ *
12
+ * The npm tarball ships only `dist/` (never `src/`), so the dev `.ts` source is
13
+ * absent there — fall back to the compiled `.js` sibling the build emits. The
14
+ * previous CLI resolver instead hand-rolled a `<bundle>/src/audit/<name>.ts`
15
+ * path that does not exist in dist, which made `bun` fail with
16
+ * "Module not found"; the MCP twin reached for the unshipped `src/audit/` via
17
+ * `resolvePackageAsset` and failed the same way.
18
+ */
19
+ export function resolveAuditScriptPath(name, { moduleUrl, exists = existsSync }) {
20
+ const sourceUrl = new URL(`../../audit/${name}`, moduleUrl);
21
+ if (exists(sourceUrl)) {
22
+ return fileURLToPath(sourceUrl);
23
+ }
24
+ const compiledUrl = new URL(`../../audit/${name.replace(/\.ts$/, '.js')}`, moduleUrl);
25
+ return fileURLToPath(compiledUrl);
26
+ }
27
+ //# sourceMappingURL=resolve-audit-script.js.map
@@ -16,7 +16,6 @@ export { validatePlanTemplate } from './core/validation/template.js';
16
16
  export { type BlueprintDiff, type DiffChange, type DiffFieldChange, formatDiffForDisplay, generateBlueprintDiff, } from './history/diff.js';
17
17
  export { checkAllCheckboxes, checkFirstCheckbox, extractCodeBlocks, extractTaskSection, updateBlockedReason, updateTaskStatus, } from './markdown/helpers.js';
18
18
  export { applyBlueprintLifecycle, type BlueprintLifecycleIntent, type BlueprintLifecycleResult, type LifecycleTaskStatus, } from './lifecycle/engine.js';
19
- export { type GraphEdge, type GraphEdgeType, type GraphLayout, type GraphNode, type GraphNodeType, type NormalizedGraph, parseMermaidToGraph, serializeGraphToMermaid, taskGraphToNormalizedGraph, } from './graph/index.js';
20
19
  export type { BlueprintQueryFilters, BlueprintQueryResult, BlueprintQuerySummary, BlueprintRecord, BlueprintSortField, BlueprintSortOptions, Complexity, SortDirection, TaskStatus, } from './query/types.js';
21
20
  export { isBlueprintStatus, isComplexity, isTaskStatus } from './query/types.js';
22
21
  export { BlueprintNotFoundError } from './utils/errors.js';
@@ -17,8 +17,6 @@ export { formatDiffForDisplay, generateBlueprintDiff, } from './history/diff.js'
17
17
  // Markdown helpers (pure functions)
18
18
  export { checkAllCheckboxes, checkFirstCheckbox, extractCodeBlocks, extractTaskSection, updateBlockedReason, updateTaskStatus, } from './markdown/helpers.js';
19
19
  export { applyBlueprintLifecycle, } from './lifecycle/engine.js';
20
- // Graph model + Mermaid integration
21
- export { parseMermaidToGraph, serializeGraphToMermaid, taskGraphToNormalizedGraph, } from './graph/index.js';
22
20
  export { isBlueprintStatus, isComplexity, isTaskStatus } from './query/types.js';
23
21
  export { BlueprintNotFoundError } from './utils/errors.js';
24
22
  // Evidence Contract (F10) — pin per-kind evidence rules at zod parse time.
@@ -4,9 +4,6 @@
4
4
  * These exports use Node.js APIs (fs, simple-git) and are NOT compatible with Cloudflare Workers.
5
5
  * For Workers-safe functions, use the main 'webpresso/blueprint' entry point.
6
6
  */
7
- export type { FalseDependency, ParallelizeResult, TaskFiles, TaskPairAnalysis, } from './dag/local/independence.js';
8
- export { createMockPackageGraph, IndependenceDetector } from './dag/local/independence.js';
9
- export { createMockFileSystem, PackageGraph, realFileSystem } from './dag/local/package-graph.js';
10
7
  export { type AcceptanceCriteria, type Blueprint, buildRoadmapModel, buildBlueprintProgressBridgeState, type BlueprintStatus, type BlueprintTaskStatus, checkAcceptanceCriteria, checkAllCheckboxes, checkChangelog, checkFirstCheckbox, complexitySchema, type CriteriaResult, extractTaskSection, formatDiffForDisplay, generateBlueprintDiff, isBlueprintStatus, isComplexity, isTaskStatus, lifecycleBlueprintStatusSchema, normalizeOmxTeamTaskSnapshot, type OmxTeamTaskSnapshot, type Phase, parseBlueprint, type PlanComplexity, type PlanFrontmatter, planStatusSchema, projectBlueprintLifecycleFromRuntime, resolveBlueprintProgressBridgePath, type RoadmapModel, type RoadmapNode, type RoadmapRollup, type RoadmapLike, serializeBlueprint, type Task, taskStatusSchema, type TaskStatusValue, updateBlockedReason, updateTaskStatus, type ValidationResult, validateEmbeddedPhases, validatePlanLinks, validatePlanState, validatePlanTemplate, } from './index.js';
11
8
  export { BlueprintCreationService, type BlueprintCreationServiceOptions, type BlueprintDraft, type CreateBlueprintInput, type CreatedBlueprint, } from './service/BlueprintCreationService.js';
12
9
  export { type BlueprintQueryOptions, BlueprintService, type BlueprintSummary, } from './service/BlueprintService.js';
@@ -4,8 +4,6 @@
4
4
  * These exports use Node.js APIs (fs, simple-git) and are NOT compatible with Cloudflare Workers.
5
5
  * For Workers-safe functions, use the main 'webpresso/blueprint' entry point.
6
6
  */
7
- export { createMockPackageGraph, IndependenceDetector } from './dag/local/independence.js';
8
- export { createMockFileSystem, PackageGraph, realFileSystem } from './dag/local/package-graph.js';
9
7
  // Workers-safe exports for convenience (explicit re-export to avoid wildcard)
10
8
  export { buildRoadmapModel, buildBlueprintProgressBridgeState, checkAcceptanceCriteria, checkAllCheckboxes, checkChangelog, checkFirstCheckbox, complexitySchema, extractTaskSection, formatDiffForDisplay, generateBlueprintDiff, isBlueprintStatus, isComplexity, isTaskStatus, lifecycleBlueprintStatusSchema, normalizeOmxTeamTaskSnapshot, parseBlueprint, planStatusSchema, projectBlueprintLifecycleFromRuntime, resolveBlueprintProgressBridgePath, serializeBlueprint, taskStatusSchema, updateBlockedReason, updateTaskStatus, validateEmbeddedPhases, validatePlanLinks, validatePlanState, validatePlanTemplate, } from './index.js';
11
9
  // Services (require filesystem/git)