@aiwg/cli 2026.11.5 → 2026.11.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/agentic/code/providers/model-capabilities.v1.json +9 -9
  2. package/bin/aiwg.mjs +6 -4
  3. package/dist/src/activity-log/cli.js +1 -1
  4. package/dist/src/agents/agent-deployer.js +1 -1
  5. package/dist/src/artifacts/audit/types.js +1 -1
  6. package/dist/src/artifacts/discover-facets.js +1 -1
  7. package/dist/src/artifacts/enrichment/prompt.js +1 -1
  8. package/dist/src/artifacts/enrichment/types.js +1 -1
  9. package/dist/src/artifacts/views/definition.js +1 -1
  10. package/dist/src/artifacts/views/types.js +1 -1
  11. package/dist/src/catalog/cli.js +1 -1
  12. package/dist/src/catalog/cli.mjs +1 -1
  13. package/dist/src/catalog/loader.js +1 -1
  14. package/dist/src/catalog/loader.mjs +1 -1
  15. package/dist/src/catalog/types.js +1 -1
  16. package/dist/src/cli/cli-extension-loader.js +19 -5
  17. package/dist/src/cli/cli-extension-paths.js +65 -0
  18. package/dist/src/cli/handlers/best-practices-audit.js +1 -1
  19. package/dist/src/cli/handlers/help.js +3 -4
  20. package/dist/src/cli/handlers/index.js +1 -1
  21. package/dist/src/cli/handlers/marketplace-plugin-search.js +37 -0
  22. package/dist/src/cli/handlers/marketplace.js +3 -1
  23. package/dist/src/cli/handlers/models.js +1 -1
  24. package/dist/src/cli/handlers/ralph-launcher.js +8 -2
  25. package/dist/src/cli/handlers/ralph.js +1 -1
  26. package/dist/src/cli/handlers/runtime-info.js +1 -1
  27. package/dist/src/cli/handlers/scaffolding.js +2 -2
  28. package/dist/src/cli/handlers/script-runner.js +1 -1
  29. package/dist/src/cli/handlers/sdlc-accelerate.js +1 -1
  30. package/dist/src/cli/handlers/subcommands-bundles.js +1 -1
  31. package/dist/src/cli/handlers/subcommands-list-format.js +19 -1
  32. package/dist/src/cli/handlers/types.js +1 -1
  33. package/dist/src/cli/handlers/use.js +2 -2
  34. package/dist/src/cli/handlers/utilities.js +1 -1
  35. package/dist/src/cli/handlers/version.js +1 -1
  36. package/dist/src/cli/handlers/workspace.js +1 -1
  37. package/dist/src/cli/help-generator.js +9 -11
  38. package/dist/src/cli/hooks/builtin/activity-log-hook.js +1 -1
  39. package/dist/src/cli/router.js +1 -1
  40. package/dist/src/cli/workflow-orchestrator.js +1 -1
  41. package/dist/src/config/worker-context.js +37 -7
  42. package/dist/src/config/worker-parallelism.js +11 -0
  43. package/dist/src/contributors/detect.js +1 -1
  44. package/dist/src/contributors/discover.js +1 -1
  45. package/dist/src/contributors/heuristic.js +1 -1
  46. package/dist/src/contributors/index.js +1 -1
  47. package/dist/src/contributors/types.js +1 -1
  48. package/dist/src/contributors/validation.js +1 -1
  49. package/dist/src/effects/worker-delivery.js +83 -0
  50. package/dist/src/extensions/capability-index.js +1 -1
  51. package/dist/src/extensions/commands/definitions.js +2 -2
  52. package/dist/src/extensions/deployment-registration.js +1 -1
  53. package/dist/src/extensions/index.js +1 -1
  54. package/dist/src/extensions/loader.js +1 -1
  55. package/dist/src/extensions/manifest.js +4 -2
  56. package/dist/src/extensions/project-local-activity.js +1 -1
  57. package/dist/src/extensions/project-local-discovery.js +2 -2
  58. package/dist/src/extensions/project-local-doctor.js +7 -3
  59. package/dist/src/extensions/project-local-promote.js +3 -3
  60. package/dist/src/extensions/project-local-remove.js +3 -3
  61. package/dist/src/extensions/project-local-scaffold.js +1 -1
  62. package/dist/src/extensions/registry.js +1 -1
  63. package/dist/src/extensions/shadow-resolver.js +1 -1
  64. package/dist/src/extensions/types.js +1 -1
  65. package/dist/src/extensions/upstream-registry.js +1 -1
  66. package/dist/src/extensions/validation.js +1 -1
  67. package/dist/src/intake/git-history-analyzer.js +1 -1
  68. package/dist/src/kb/cli.js +1 -1
  69. package/dist/src/marketplace/plugin-directory.js +36 -0
  70. package/dist/src/marketplace/plugin-search.js +180 -0
  71. package/dist/src/mcp/cli.mjs +2 -2
  72. package/dist/src/mcp/helpers.mjs +1 -1
  73. package/dist/src/mcp/http-tools.mjs +8 -6
  74. package/dist/src/mcp/http-transport.mjs +3 -1
  75. package/dist/src/mcp/server.mjs +1 -1
  76. package/dist/src/mcp/tools/command-run.mjs +1 -1
  77. package/dist/src/mcp/tools/discovery.mjs +1 -1
  78. package/dist/src/mcp/tools/subsystems.mjs +1 -1
  79. package/dist/src/mcp/tools/worker-invoke.mjs +68 -22
  80. package/dist/src/mcp/tools/worker-local-only-preflight.mjs +79 -0
  81. package/dist/src/mcp/tools/worker-recorded-launch.mjs +26 -0
  82. package/dist/src/mcp/tools/worker-stdin-runtime.mjs +33 -6
  83. package/dist/src/mcp/tools/worker-verify-deliver-schema.mjs +33 -0
  84. package/dist/src/mcp/tools/worker-verify-deliver.mjs +27 -0
  85. package/dist/src/models/catalog-policy.js +2 -2
  86. package/dist/src/models/conductor-data-policy.mjs +83 -14
  87. package/dist/src/models/config-loader.js +2 -2
  88. package/dist/src/models/index.js +2 -2
  89. package/dist/src/models/local-endpoint-models.js +155 -0
  90. package/dist/src/models/model-capabilities.v1.json +9 -9
  91. package/dist/src/models/model-discovery.js +9 -5
  92. package/dist/src/models/opencode-worker-model.mjs +16 -0
  93. package/dist/src/models/resolver.js +2 -2
  94. package/dist/src/models/worker-installation.mjs +5 -3
  95. package/dist/src/models/worker-plan.js +1 -1
  96. package/dist/src/plugin/plugin-installer.js +2 -2
  97. package/dist/src/plugin/registry-validator.js +2 -2
  98. package/dist/src/plugin/skill-command-translator.js +1 -1
  99. package/dist/src/rlm/cache/hash.js +1 -1
  100. package/dist/src/rlm/cache/store.js +1 -1
  101. package/dist/src/rlm/cache/types.js +1 -1
  102. package/dist/src/serve/worker-invocation-preparation.js +13 -0
  103. package/dist/src/serve/worker-invocation.js +21 -6
  104. package/dist/src/skills/run.js +0 -11
  105. package/dist/src/smiths/agentsmith/generator.js +1 -1
  106. package/dist/src/smiths/context-pipeline/index.js +1 -1
  107. package/dist/src/smiths/context-pipeline/provider-policy.js +1 -1
  108. package/dist/src/smiths/context-pipeline/types.js +1 -1
  109. package/dist/src/smiths/mcpsmith/analyzers/cli-analyzer.js +2 -2
  110. package/dist/src/smiths/mcpsmith/generator.js +2 -2
  111. package/dist/src/smiths/mcpsmith/index.js +2 -2
  112. package/dist/src/smiths/mcpsmith/types.js +2 -2
  113. package/dist/src/smiths/skillsmith/collision-detector.js +1 -1
  114. package/dist/src/smiths/skillsmith/namespace-adapter.js +1 -1
  115. package/dist/src/smiths/toolsmith/runtime-discovery.mjs +2 -2
  116. package/dist/src/smiths/toolsmith/types.js +2 -2
  117. package/dist/src/storage/backends/fortemi.js +1 -1
  118. package/dist/src/storage/backends/fs.js +1 -1
  119. package/dist/src/storage/backends/logseq.js +1 -1
  120. package/dist/src/storage/backends/obsidian.js +1 -1
  121. package/dist/src/storage/cli.js +2 -2
  122. package/dist/src/storage/config.js +1 -1
  123. package/dist/src/storage/index.js +1 -1
  124. package/dist/src/storage/subsystem-cli.js +1 -1
  125. package/dist/src/storage/types.js +1 -1
  126. package/dist/src/testing/generators/test-case-generator.js +1 -1
  127. package/dist/src/writing/validation-engine.js +1 -1
  128. package/package.json +11 -1
  129. package/schemas/models/model-catalog.v1.schema.json +6 -3
  130. package/tools/agents/providers/conductor-data-guard.mjs +1 -1
  131. package/tools/ralph-external/lib/mcp-worker-launch.mjs +67 -0
  132. package/tools/ralph-external/lib/opencode-adapter.mjs +9 -7
  133. package/tools/ralph-external/lib/trusted-verification.mjs +1021 -0
  134. package/tools/ralph-external/lib/typed-stop-delivery.mjs +46 -0
  135. package/tools/ralph-external/lib/verification-isolation.mjs +509 -0
  136. package/tools/ralph-external/lib/worker-context.mjs +3 -3
  137. package/tools/ralph-external/lib/worker-delivery-guards.mjs +95 -0
  138. package/tools/ralph-external/lib/worker-delivery-record.mjs +15 -0
  139. package/tools/ralph-external/lib/worker-final.mjs +4 -1
  140. package/tools/ralph-external/lib/worker-isolation-status.mjs +3 -0
  141. package/tools/ralph-external/lib/worker-launch-cli.mjs +8 -0
  142. package/tools/ralph-external/lib/worker-local-only-paths.mjs +45 -0
  143. package/tools/ralph-external/lib/worker-prompt.mjs +4 -1
  144. package/tools/ralph-external/lib/worker-retry-evidence.mjs +2 -1
  145. package/tools/ralph-external/lib/worker-run-directory.mjs +45 -0
  146. package/tools/ralph-external/lib/worker-unit-cleanup.mjs +10 -2
  147. package/tools/ralph-external/lib/worker-verification-cli.mjs +164 -0
  148. package/tools/ralph-external/lib/worktree-preparation.mjs +417 -0
  149. package/tools/ralph-external/session-launcher.mjs +8 -15
  150. package/vscode-extension/schemas/aiwg.config.v1.json +27 -0
@@ -4,7 +4,7 @@
4
4
  * Handlers for utility commands including card prefilling, contribution workflow,
5
5
  * metadata validation, health diagnostics, and update checking.
6
6
  *
7
- * @implements @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
7
+ * @implements @docs/architecture/cli/adr-001-unified-extension-registry.md
8
8
  * @source @src/cli/router.ts
9
9
  * @tests @test/unit/cli/handlers/utilities.test.ts
10
10
  * @issue #33, #342
@@ -4,7 +4,7 @@
4
4
  * Displays version and channel information for the AIWG installation.
5
5
  * Supports --verbose / --json for full environment fingerprint (Phase 4.5 #925).
6
6
  *
7
- * @implements @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
7
+ * @implements @docs/architecture/cli/adr-001-unified-extension-registry.md
8
8
  * @source @src/cli/router.ts
9
9
  * @issue #33, #925
10
10
  */
@@ -4,7 +4,7 @@
4
4
  * Handlers for workspace health, migration, and rollback operations.
5
5
  * Delegates to existing CLI scripts in tools/cli/.
6
6
  *
7
- * @implements @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
7
+ * @implements @docs/architecture/cli/adr-001-unified-extension-registry.md
8
8
  * @source @src/cli/router.ts
9
9
  * @issue #33
10
10
  */
@@ -2,12 +2,13 @@
2
2
  * Help Generator
3
3
  *
4
4
  * Dynamically generates CLI help text from the extension registry.
5
- * Replaces hardcoded displayHelp() with registry-driven approach.
5
+ * Shares provider help between the launcher and command handler.
6
6
  *
7
- * @implements @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
7
+ * @implements @docs/architecture/cli/adr-001-unified-extension-registry.md
8
8
  * @tests @test/unit/cli/help-generator.test.ts
9
9
  * @version 1.0.0
10
10
  */
11
+ import { listProviderDefinitions } from '../providers/provider-definitions.js';
11
12
  /**
12
13
  * Category display order and titles
13
14
  *
@@ -82,15 +83,7 @@ export function generateHelp(registry) {
82
83
  }
83
84
  // Platform options
84
85
  lines.push('Platform Options (--provider):');
85
- lines.push(' claude Claude Code (default)');
86
- lines.push(' copilot GitHub Copilot');
87
- lines.push(' factory Factory AI');
88
- lines.push(' codex / openai OpenAI Codex');
89
- lines.push(' cursor Cursor IDE');
90
- lines.push(' opencode OpenCode');
91
- lines.push(' warp Warp Terminal');
92
- lines.push(' devin Devin Desktop');
93
- lines.push(' windsurf Deprecated alias for devin');
86
+ lines.push(` ${generateProviderHelp()}`);
94
87
  lines.push('');
95
88
  // Examples
96
89
  lines.push('Examples:');
@@ -176,4 +169,9 @@ function formatCommandName(cmd) {
176
169
  // Show command name with first alias
177
170
  return `${cmd.id}, ${aliases[0]}`;
178
171
  }
172
+ /** Provider list shared by both production help paths, including generic. */
173
+ export function generateProviderHelp() {
174
+ const providers = listProviderDefinitions();
175
+ return `Providers: ${providers.length} — ${providers.map(({ id, status }) => status === 'experimental' ? `${id} (experimental)` : id).join(', ')} (default: claude; aliases: agy → antigravity, devin → windsurf, oh-my-pi → omp, openai → codex)`;
176
+ }
179
177
  //# sourceMappingURL=help-generator.js.map
@@ -11,7 +11,7 @@
11
11
  * Failures are non-blocking: if the entry can't be written, we log to
12
12
  * stderr and let the primary command's success stand.
13
13
  *
14
- * @design @.aiwg/architecture/storage-design.md
14
+ * @design @docs/storage/overview.md
15
15
  * @issue #934
16
16
  * @issue #978
17
17
  */
@@ -6,7 +6,7 @@
6
6
  * Integrates hook system for lifecycle events.
7
7
  *
8
8
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
9
- * @architecture @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
9
+ * @architecture @docs/architecture/cli/adr-001-unified-extension-registry.md
10
10
  * @tests @test/unit/cli/router.test.ts
11
11
  * @issue #33
12
12
  * @issue #58
@@ -5,7 +5,7 @@
5
5
  * Supports batch processing, watch mode, auto-fix, and multiple output formats.
6
6
  *
7
7
  * @implements @.aiwg/requirements/use-cases/UC-001-validate-ai-generated-content.md
8
- * @architecture @.aiwg/architecture/software-architecture-doc.md - Section 4.2 Core Orchestrator
8
+ * @architecture @docs/architecture/cli/index.md
9
9
  * @tests @test/unit/cli/workflow-orchestrator.test.ts
10
10
  * @depends @src/writing/validation-engine.ts
11
11
  * @depends @src/writing/prompt-optimizer.ts
@@ -13,7 +13,8 @@
13
13
  * config through `readAiwgConfig` and injects it here; direct callers may
14
14
  * pass an already-loaded config object instead.
15
15
  */
16
- import { existsSync, readdirSync, readFileSync } from 'node:fs';
16
+ import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
17
+ import { tmpdir } from 'node:os';
17
18
  import { spawnSync } from 'node:child_process';
18
19
  import path from 'node:path';
19
20
  import { getProviderArtifactPathStrings, getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
@@ -239,7 +240,8 @@ export async function syncWorkerContextProviders(options) {
239
240
  }
240
241
  /**
241
242
  * Canonical one-pass deploy argv: a single `aiwg use all` invocation
242
- * covering every listed provider. Never one deploy per provider:
243
+ * covering every listed provider, or explicitly selecting one project-local
244
+ * launch provider. Never one deploy per provider in a union preparation:
243
245
  * per-provider invocations rewrite AGENTS.md piecemeal and clobber each
244
246
  * other's rule sections, while one pass keeps them all. No `--providers`
245
247
  * flag: it feeds only the global bootstrap and the orchestrated
@@ -249,14 +251,32 @@ export async function syncWorkerContextProviders(options) {
249
251
  * configured-provider path: `syncWorkerContextProviders` first, then this
250
252
  * single pass reads the union back from the worktree config.
251
253
  */
252
- export function buildWorkerContextDeployArgs({ providers, target }) {
254
+ export function buildWorkerContextDeployArgs({ providers, target, selectedProvider }) {
253
255
  // Fail fast on a hostile list; the synced worktree config carries the set.
254
256
  validateExplicitWorkerContextProviders(providers);
257
+ if (selectedProvider !== undefined) {
258
+ validateExplicitWorkerContextProviders([selectedProvider]);
259
+ return ['use', 'all', '--provider', selectedProvider, '--scope', 'project', '--target', target, '--yes'];
260
+ }
255
261
  return ['use', 'all', '--target', target, '--yes'];
256
262
  }
263
+ /** Keep CLI bootstrap state and caches local to a launch-time context deploy. */
264
+ export function workerContextDeployEnv(workdir, env = process.env, scratch) {
265
+ const local = path.join(workdir, '.aiwg');
266
+ // Data and cache hold regenerable deploy output (the framework search index
267
+ // alone exceeds 100 MB). Inside the worker tree they break the verifier's
268
+ // tree digest, so a scratch directory outside the tree takes them (#4150).
269
+ return { ...env, HOME: workdir, USERPROFILE: workdir, AIWG_CONFIG: local,
270
+ XDG_CONFIG_HOME: path.join(local, 'config'), XDG_CACHE_HOME: path.join(scratch ?? local, 'cache'),
271
+ XDG_DATA_HOME: path.join(scratch ?? local, 'data'), XDG_STATE_HOME: path.join(local, 'state'),
272
+ AIWG_USER_REGISTRY_PATH: path.join(local, 'installed.json'),
273
+ AIWG_ARTIFACTS_PATH: local, AIWG_PROJECT_AIWG_DIR: local,
274
+ CODEX_HOME: path.join(workdir, '.codex'), HERMES_HOME: path.join(workdir, '.hermes') };
275
+ }
257
276
  /**
258
277
  * Ensure a worker workdir carries its CLI's AIWG bootstrap before launch.
259
- * Present: no-op. Missing: sync the union set into the workdir config,
278
+ * Present: no-op. Missing: select one provider for projectLocal launches;
279
+ * otherwise sync the union set into the workdir config,
260
280
  * then exactly one `aiwg use all` pass into the workdir (never anywhere
261
281
  * else), then re-verify. Impossible (no binary, failed deploy, still
262
282
  * missing afterwards): throw `WorkerContextBootstrapError` naming the
@@ -280,14 +300,15 @@ export async function ensureWorkerContextBootstrap(options) {
280
300
  const sync = options.syncFn ?? syncWorkerContextProviders;
281
301
  let synced;
282
302
  try {
283
- synced = await sync({ workdir, providers });
303
+ synced = options.projectLocal ? { providers: [provider], updated: false } : await sync({ workdir, providers });
284
304
  }
285
305
  catch (error) {
286
306
  if (error instanceof WorkerContextBootstrapError)
287
307
  throw error;
288
308
  throw new WorkerContextBootstrapError(`worker context sync failed: ${error instanceof Error ? error.message : String(error)}`, `write the union providers into ${path.join(workdir, '.aiwg', 'aiwg.config')} (or run 'aiwg use all --target ${workdir} --yes' manually) before launch`, { provider, workdir });
289
309
  }
290
- const argv = buildWorkerContextDeployArgs({ providers: synced.providers, target: workdir });
310
+ const argv = buildWorkerContextDeployArgs({ providers: synced.providers, target: workdir,
311
+ ...(options.projectLocal ? { selectedProvider: provider } : {}) });
291
312
  const deploy = options.deployFn ?? (({ worktreePath, providers: deployProviders, aiwgBin: bin }) => {
292
313
  // worktreePath IS the worker workdir by construction: the only
293
314
  // `--target` ever passed is `workdir` above, and the spawn cwd is the
@@ -295,7 +316,16 @@ export async function ensureWorkerContextBootstrap(options) {
295
316
  if (path.resolve(worktreePath) !== path.resolve(workdir)) {
296
317
  throw new WorkerContextBootstrapError(`refusing worker context deploy outside the worker workdir (${worktreePath} !== ${workdir})`, 'deploy worker context only into the worker workdir', { provider, workdir });
297
318
  }
298
- const result = spawn(bin, argv, { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
319
+ const scratch = options.projectLocal ? mkdtempSync(path.join(tmpdir(), 'aiwg-worker-deploy-')) : undefined;
320
+ let result;
321
+ try {
322
+ result = spawn(bin, argv, { cwd: workdir, encoding: 'utf8', timeout: timeoutMs,
323
+ ...(options.projectLocal ? { env: workerContextDeployEnv(workdir, process.env, scratch) } : {}) });
324
+ }
325
+ finally {
326
+ if (scratch)
327
+ rmSync(scratch, { recursive: true, force: true });
328
+ }
299
329
  if (result.error) {
300
330
  throw new WorkerContextBootstrapError(`worker context deploy failed to run (${result.error?.message});`
301
331
  + ` missing in ${workdir}: ${status.missing.join('; ')}`, `install the aiwg CLI on PATH or set AIWG_BIN to its location (tried '${bin}'),`
@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
7
7
  import { PROVIDER_IDS } from '../providers/provider-definitions.js';
8
8
  import { isCanonicalWorkerModelKey, loadProviderModelCapabilities, resolveWorkerInstallation } from '../models/provider-policy.js';
9
9
  import { resolveDispatchHostThresholds } from './dispatch-thresholds-runtime.mjs';
10
+ import { localModelsUrl } from '../models/local-endpoint-models.js';
10
11
  import { expandWorkerGroupTemplates } from './worker-group-templates.js';
11
12
  let parallelismValidator;
12
13
  /** Offline shape and declaration validation. Qualification is checked at use time. */
@@ -37,6 +38,16 @@ export function validateParallelismConfig(value) {
37
38
  const error = (pointer, message) => { errors.push(`OG_CONFIG_REFERENCE /parallelism/${pointer}: ${message}`); };
38
39
  const builtinIds = new Set(PROVIDER_IDS.filter(id => id !== 'generic'));
39
40
  for (const [id, installation] of Object.entries(policy.clis ?? {})) {
41
+ if (installation.localModels) {
42
+ try {
43
+ localModelsUrl(installation.localModels);
44
+ }
45
+ catch {
46
+ error(`clis/${id}/localModels/endpoint`, 'Requires a credential-free HTTP endpoint on loopback or allowedHosts');
47
+ }
48
+ if (new Set(installation.localModels.models.map(model => model.id)).size !== installation.localModels.models.length)
49
+ error(`clis/${id}/localModels/models`, 'Duplicate model ID');
50
+ }
40
51
  if (installation.adapter.startsWith('providers:') && !builtinIds.has(installation.adapter.slice(10)))
41
52
  error(`clis/${id}/adapter`, 'Unknown provider binding');
42
53
  }
@@ -5,7 +5,7 @@
5
5
  * Determines whether the contributor's framework is *in use* on this project,
6
6
  * not just installed. Pure I/O — no code execution.
7
7
  *
8
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
8
+ * @architecture @docs/contributing/contributor-quickstart.md
9
9
  * @issue #938
10
10
  */
11
11
  import { glob } from 'glob';
@@ -6,7 +6,7 @@
6
6
  * runs detection on each candidate. Returns kept records and skipped entries
7
7
  * with reasons. Failures of one contributor never abort discovery.
8
8
  *
9
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
9
+ * @architecture @docs/contributing/contributor-quickstart.md
10
10
  * @issue #938
11
11
  */
12
12
  import { existsSync } from 'fs';
@@ -12,7 +12,7 @@
12
12
  * it only checks a small number of well-known paths and runs a handful of
13
13
  * bounded globs.
14
14
  *
15
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
15
+ * @architecture @docs/contributing/contributor-quickstart.md
16
16
  * @issue #941
17
17
  */
18
18
  import { existsSync, statSync } from 'fs';
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Contributor Discovery — Public API
3
3
  *
4
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
4
+ * @architecture @docs/contributing/contributor-quickstart.md
5
5
  * @issue #938
6
6
  */
7
7
  export { discoverContributors } from './discover.js';
@@ -6,7 +6,7 @@
6
6
  * best-practices-audit, ...) by shipping `<framework>/<kind>/contributor.md`
7
7
  * files. The aggregator discovers, validates, and runs detection against them.
8
8
  *
9
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
9
+ * @architecture @docs/contributing/contributor-quickstart.md
10
10
  * @issue #938
11
11
  */
12
12
  export {};
@@ -5,7 +5,7 @@
5
5
  * keyed by kind so future consumers register their schema without forking the
6
6
  * discovery module.
7
7
  *
8
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
8
+ * @architecture @docs/contributing/contributor-quickstart.md
9
9
  * @issue #938
10
10
  */
11
11
  import { z } from 'zod';
@@ -0,0 +1,83 @@
1
+ // Signed publication receipts and current-byte lookup for verified worker artifacts.
2
+ import { readFile, realpath } from 'node:fs/promises';
3
+ import { dirname, basename, join } from 'node:path';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { assertKeyring } from './keyring.js';
6
+ import { sha256Digest } from './identity.js';
7
+ import { recordIntent, recordOutcome } from './ledger.js';
8
+ import { readAllSegments, readKeyring, lineFailures } from './reader.js';
9
+ import { verifyLedger } from './verify.js';
10
+ import { ensureLedgerDirectories, withLedgerLock } from './store.js';
11
+ const canonicalDestination = async (destination) => join(await realpath(dirname(destination)), basename(destination));
12
+ /** A signed intent reserves the path even if publication crashed or bytes changed. */
13
+ async function reserveDelivery(ledger, delivery, target) {
14
+ const paths = ledger.paths();
15
+ await ensureLedgerDirectories(paths);
16
+ return withLedgerLock(paths, 'worker-delivery', ledger.lockTimeoutMs, async () => {
17
+ if (!(await verifyLedger(ledger, { checkIndex: false })).ok)
18
+ throw new Error('Delivery ledger integrity failed; publication refused');
19
+ const records = (await readAllSegments(paths)).flatMap(segment => segment.lines.flatMap(line => line.decoded ? [line.decoded] : []));
20
+ const conflict = records.some(({ statement: { predicate: p } }) => p.kind === 'file.digest' && p.target === `file:${target}`
21
+ && typeof p.context?.deliveryId === 'string' && (delivery.kind === 'typed-stop' || p.context?.kind === 'typed-stop'));
22
+ if (conflict)
23
+ throw Object.assign(new Error('TYPED_STOP_CONFLICT: a delivery record already exists for this path'), { code: 'TYPED_STOP_CONFLICT' });
24
+ const context = { artifactDigest: delivery.artifactDigest, verifierId: delivery.verifierId,
25
+ deliverablePath: target, deliveryId: randomUUID() };
26
+ if (delivery.kind)
27
+ context.kind = delivery.kind;
28
+ if (delivery.kind !== 'typed-stop') {
29
+ context.runDir = delivery.runDir;
30
+ context.invocationId = delivery.invocationId;
31
+ }
32
+ return recordIntent(ledger, { kind: 'file.digest', target: `file:${target}`, context, payloadDigest: delivery.artifactDigest });
33
+ });
34
+ }
35
+ /** Persist intent before publication, then complete only after the digest-checked rename. */
36
+ export async function prepareWorkerDelivery(ledger, delivery) {
37
+ if (delivery.kind === 'typed-stop' && (delivery.verifierId !== 'typed-stop@1' || 'runDir' in delivery || 'invocationId' in delivery)) {
38
+ throw Object.assign(new Error('TYPED_STOP_INVALID: typed stops cannot have worker lineage'), { code: 'TYPED_STOP_INVALID' });
39
+ }
40
+ const target = await canonicalDestination(delivery.deliverablePath);
41
+ const intent = await reserveDelivery(ledger, delivery, target);
42
+ return async () => {
43
+ if (sha256Digest(await readFile(target)) !== delivery.artifactDigest)
44
+ throw new Error('Published deliverable digest does not match acceptance; delivery record refused');
45
+ return recordOutcome(ledger, intent.effectId, { phase: 'completed', payloadDigest: delivery.artifactDigest,
46
+ verification: { verifier: { kind: 'file.digest', version: '1.0.0', canReportAbsent: false }, result: 'present', reason: 'digest-match', complete: true, checkedAt: ledger.now(), evidenceDigest: delivery.artifactDigest } });
47
+ };
48
+ }
49
+ /** Read-only: signatures/chains and a completed delivery must match the current bytes. */
50
+ export async function lookupWorkerDelivery(ledger, deliverablePath) {
51
+ let target, artifactDigest;
52
+ try {
53
+ target = await canonicalDestination(deliverablePath);
54
+ artifactDigest = sha256Digest(await readFile(target));
55
+ }
56
+ catch {
57
+ return { verified: false, deliverablePath, reason: 'deliverable-unreadable' };
58
+ }
59
+ const verification = await verifyLedger(ledger, { checkIndex: false });
60
+ if (!verification.ok)
61
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'ledger-integrity-failed' };
62
+ const records = (await readAllSegments(ledger.paths())).flatMap(segment => segment.lines.flatMap(line => line.decoded ? [line.decoded] : []));
63
+ const keyring = await readKeyring(ledger.paths());
64
+ if (!keyring)
65
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'ledger-empty' };
66
+ assertKeyring(keyring, ledger.scope);
67
+ const previous = new Map();
68
+ for (const record of records) {
69
+ if (lineFailures(keyring, ledger.scope, record.line.writer, record.line.seq, record, previous.get(record.line.writer) ?? null).length)
70
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'ledger-integrity-failed' };
71
+ previous.set(record.line.writer, record.line.recordHash);
72
+ }
73
+ const match = records.reverse().find(({ statement: { predicate: p } }) => p.kind === 'file.digest' && p.phase === 'completed'
74
+ && p.target === `file:${target}` && p.payloadDigest === artifactDigest && p.context?.artifactDigest === artifactDigest
75
+ && typeof p.context?.deliveryId === 'string' && typeof p.context?.verifierId === 'string'
76
+ && (p.context?.kind === 'typed-stop'
77
+ ? p.context.verifierId === 'typed-stop@1' && !('runDir' in p.context) && !('invocationId' in p.context)
78
+ : typeof p.context?.runDir === 'string' && typeof p.context?.invocationId === 'string'));
79
+ if (!match)
80
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'matching-delivery-missing' };
81
+ return { verified: true, ...match.statement.predicate.context, recordHash: match.line.recordHash };
82
+ }
83
+ //# sourceMappingURL=worker-delivery.js.map
@@ -2,7 +2,7 @@
2
2
  * CapabilityIndex - Capability-based extension discovery system
3
3
  *
4
4
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
5
- * @architecture @.aiwg/architecture/software-architecture-doc.md
5
+ * @architecture @docs/architecture/cli/index.md
6
6
  * @tests @test/unit/extensions/capability-index.test.ts
7
7
  */
8
8
  /**
@@ -4,8 +4,8 @@
4
4
  * Defines Extension objects for all CLI commands. Maps command handlers to the
5
5
  * unified Extension schema for discovery, semantic search, and help generation.
6
6
  *
7
- * @implements @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
7
+ * @implements @docs/architecture/cli/adr-001-unified-extension-registry.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  * @source @src/cli/handlers/index.ts
10
10
  * @tests @test/unit/extensions/commands/definitions.test.ts
11
11
  * @issue #42
@@ -5,7 +5,7 @@
5
5
  * and registers them in the extension registry for discovery.
6
6
  *
7
7
  * @implements #56, #57
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  * @tests @test/unit/extensions/deployment-registration.test.ts
10
10
  */
11
11
  import fs from 'fs';
@@ -5,7 +5,7 @@
5
5
  * capability indexing, and loading functionality for all extension types.
6
6
  *
7
7
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  */
10
10
  // Core types
11
11
  export * from './types.js';
@@ -5,7 +5,7 @@
5
5
  * capability indexes for fast lookup.
6
6
  *
7
7
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  * @tests @test/unit/extensions/loader.test.ts
10
10
  */
11
11
  import { getRegistry, createRegistry } from './registry.js';
@@ -3,14 +3,14 @@
3
3
  *
4
4
  * Validates `.aiwg/{extensions,addons,frameworks,plugins,providers}/<name>/manifest.json`
5
5
  * for project-local artifact bundles. Implements the design in
6
- * `.aiwg/architecture/design-manifest-schema.md` (#1044).
6
+ * `docs/project-local/manifest-reference.md` (#1044).
7
7
  *
8
8
  * Layered above the per-artifact Extension type validation in `validation.ts`:
9
9
  * the bundle manifest declares the bundle (a directory containing artifacts);
10
10
  * the existing schemas validate individual artifact bodies inside the bundle.
11
11
  *
12
12
  * @implements #1044
13
- * @architecture .aiwg/architecture/design-manifest-schema.md
13
+ * @architecture docs/project-local/manifest-reference.md
14
14
  */
15
15
  import { z } from 'zod';
16
16
  import { integer, dateTime, url } from '../schema/zod-validation.mjs';
@@ -49,6 +49,7 @@ const bundleNamePattern = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
49
49
  // Per-type config blocks
50
50
  // ============================================
51
51
  const ArtifactListsSchema = z.object({
52
+ flows: z.array(z.string()).max(200).optional(),
52
53
  agents: z.array(z.string()).max(200).optional(),
53
54
  skills: z.array(z.string()).max(500).optional(),
54
55
  rules: z.array(z.string()).max(200).optional(),
@@ -60,6 +61,7 @@ const ArtifactListsSchema = z.object({
60
61
  gatePacks: z.array(z.string().min(1).max(128)).max(50).optional(),
61
62
  });
62
63
  const EntryPathsSchema = z.strictObject({
64
+ flows: safeRelativePath.optional(),
63
65
  agents: safeRelativePath.optional(),
64
66
  skills: safeRelativePath.optional(),
65
67
  rules: safeRelativePath.optional(),
@@ -10,7 +10,7 @@
10
10
  * per-event entries (per-bundle, per-provider) at finer granularity, as
11
11
  * specified by the design doc.
12
12
  *
13
- * @design @.aiwg/architecture/design-doctor-log-promote.md
13
+ * @design @docs/customization/project-local-lifecycle.md
14
14
  * @implements #1037
15
15
  * @issue #1049
16
16
  */
@@ -6,8 +6,8 @@
6
6
  * deployment side effects.
7
7
  *
8
8
  * @implements #1034
9
- * @architecture .aiwg/architecture/adr-aiwg-directory-layout.md (#1039)
10
- * @architecture .aiwg/architecture/design-manifest-schema.md (#1044)
9
+ * @architecture docs/architecture/cli/extending-cli.md (#1039)
10
+ * @architecture docs/project-local/manifest-reference.md (#1044)
11
11
  */
12
12
  import { readFile, readdir, lstat, stat, access, realpath } from 'fs/promises';
13
13
  import { join, relative, resolve, sep } from 'path';
@@ -2,17 +2,18 @@
2
2
  * Project-Local Doctor Section
3
3
  *
4
4
  * Builds the "Project-local artifacts" section for `aiwg doctor` output
5
- * per the spec at @.aiwg/architecture/design-doctor-log-promote.md (#1049).
5
+ * per the spec at @docs/customization/project-local-lifecycle.md (#1049).
6
6
  *
7
7
  * Pure function over (projectDir, frameworkRoot) — returns a string. The
8
8
  * doctor handler in src/cli/handlers/utilities.ts is responsible for
9
9
  * printing it. Section is fully suppressed when no project-local dirs
10
10
  * are present.
11
11
  *
12
- * @design @.aiwg/architecture/design-doctor-log-promote.md
12
+ * @design @docs/customization/project-local-lifecycle.md
13
13
  * @implements #1037
14
14
  */
15
15
  import { join } from 'path';
16
+ import { cliExtensionSourceWarnings } from '../cli/cli-extension-paths.js';
16
17
  import { readFile, readdir } from 'fs/promises';
17
18
  import { discoverProjectLocalBundles } from './project-local-discovery.js';
18
19
  import { parseRuleFrontmatter, formatRuleFrontmatterError } from '../rules/activation.mjs';
@@ -103,6 +104,7 @@ async function collectBundleRuleFiles(artifactPath) {
103
104
  export async function buildProjectLocalDoctorSection(opts) {
104
105
  const { projectDir, frameworkRoot, config, quiet = false } = opts;
105
106
  const discovery = await discoverProjectLocalBundles(projectDir);
107
+ const cliWarnings = await cliExtensionSourceWarnings(projectDir);
106
108
  const quickrefAudit = await auditProjectQuickref(projectDir, config?.providers ?? []);
107
109
  const quickrefErrors = [...quickrefAudit.errors];
108
110
  if (quickrefAudit.exists) {
@@ -118,10 +120,12 @@ export async function buildProjectLocalDoctorSection(opts) {
118
120
  }
119
121
  }
120
122
  // No project-local content → no section at all
121
- if (discovery.isEmpty && discovery.errors.length === 0 && !quickrefAudit.exists && quickrefErrors.length === 0) {
123
+ if (discovery.isEmpty && discovery.errors.length === 0 && !quickrefAudit.exists && quickrefErrors.length === 0 && cliWarnings.length === 0) {
122
124
  return { output: '', validationErrors: 0, denylistViolations: 0, driftCount: 0, undeployedCount: 0, hasFailures: false };
123
125
  }
124
126
  const lines = ['', '── Project-local artifacts ────────────────────────────────────'];
127
+ for (const warning of cliWarnings)
128
+ lines.push(` ⚠ ${warning}`);
125
129
  // Counts
126
130
  if (!quiet) {
127
131
  lines.push(` Discovered: ${discovery.bundles.length} bundle${discovery.bundles.length === 1 ? '' : 's'}`);
@@ -2,11 +2,11 @@
2
2
  * Project-Local Bundle Promotion (Graduate)
3
3
  *
4
4
  * Operationalizes the identical-form portability invariant from
5
- * @.aiwg/architecture/adr-identical-form-portability.md (#1038): a
5
+ * @docs/customization/project-local-lifecycle.md (#1038): a
6
6
  * project-local bundle should graduate to upstream (or to a private
7
7
  * corpus path) by byte-identical copy.
8
8
  *
9
- * Per the design at @.aiwg/architecture/design-doctor-log-promote.md
9
+ * Per the design at @docs/customization/project-local-lifecycle.md
10
10
  * (#1049), promote performs:
11
11
  * 1. Pre-flight checks (bundle exists, manifest valid, no project-
12
12
  * local @-refs, destination doesn't exist, identical-form layout)
@@ -17,7 +17,7 @@
17
17
  * 6. Optional --cleanup: remove .aiwg/<type>/<name>/ source
18
18
  * 7. Activity log entry
19
19
  *
20
- * @design @.aiwg/architecture/design-doctor-log-promote.md
20
+ * @design @docs/customization/project-local-lifecycle.md
21
21
  * @implements #1037
22
22
  */
23
23
  import { createHash } from 'crypto';
@@ -2,14 +2,14 @@
2
2
  * Project-Local Bundle Remove
3
3
  *
4
4
  * Reverts a project-local bundle's deployed artifacts from provider paths
5
- * per the case table in `.aiwg/architecture/design-aiwg-remove-revert.md`
5
+ * per the case table in `docs/customization/project-local-lifecycle.md`
6
6
  * (#1048). Reads artifactHashes from the registry to detect pristine vs
7
7
  * mutated vs replaced files.
8
8
  *
9
9
  * Source under `.aiwg/<type>/<name>/` is NEVER deleted (load-bearing
10
10
  * invariant — `--force` does not change this).
11
11
  *
12
- * @design @.aiwg/architecture/design-aiwg-remove-revert.md
12
+ * @design @docs/customization/project-local-lifecycle.md
13
13
  * @implements #1037
14
14
  */
15
15
  import { lstat, readdir, readFile, stat, unlink, rmdir } from 'fs/promises';
@@ -232,7 +232,7 @@ function resolveOwnership(config, selfBundleId, provider, sourceRel) {
232
232
  }
233
233
  /**
234
234
  * Remove a project-local bundle's deploys per the design at
235
- * `.aiwg/architecture/design-aiwg-remove-revert.md`.
235
+ * `docs/customization/project-local-lifecycle.md`.
236
236
  *
237
237
  * Pure function over (config, projectDir, opts). The caller is responsible
238
238
  * for persisting the returned (mutated) config.
@@ -8,7 +8,7 @@
8
8
  * The output is byte-identical-shaped to upstream addon directories so
9
9
  * `aiwg promote` can graduate it without any rewrite.
10
10
  *
11
- * @design @.aiwg/architecture/adr-identical-form-portability.md (#1038)
11
+ * @design @docs/customization/project-local-lifecycle.md (#1038)
12
12
  * @implements #1050
13
13
  */
14
14
  import { mkdir, writeFile, stat } from 'fs/promises';
@@ -4,7 +4,7 @@
4
4
  * Provides efficient storage, indexing, and retrieval of AIWG extensions.
5
5
  * Supports O(1) lookup by ID, type-based indexing, and command alias resolution.
6
6
  *
7
- * @architecture @.aiwg/architecture/unified-extension-schema.md
7
+ * @architecture @docs/architecture/cli/extending-cli.md
8
8
  * @tests @test/unit/extensions/registry.test.ts
9
9
  * @version 1.0.0
10
10
  */
@@ -2,7 +2,7 @@
2
2
  * Shadow Resolver
3
3
  *
4
4
  * Implements the override / shadow-resolution policy from
5
- * `.aiwg/architecture/adr-override-shadow-policy.md` (#1041) for project-local
5
+ * `docs/customization/project-local-lifecycle.md` (#1041) for project-local
6
6
  * artifact bundles deployed via `aiwg use` / `aiwg refresh`.
7
7
  *
8
8
  * Resolves the seven cases from ADR §4:
@@ -5,7 +5,7 @@
5
5
  * hooks, tools, and MCP servers. Enables dynamic discovery, semantic search,
6
6
  * and unified help generation.
7
7
  *
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  * @version 1.0.0
10
10
  */
11
11
  // ============================================
@@ -10,7 +10,7 @@
10
10
  *
11
11
  * Consumed by the shadow resolver (#1036) to detect collisions between project-
12
12
  * local bundles and upstream artifacts and apply the override / safety-critical
13
- * denylist policy from `.aiwg/architecture/adr-override-shadow-policy.md`.
13
+ * denylist policy from `docs/customization/project-local-lifecycle.md`.
14
14
  *
15
15
  * @implements #1036
16
16
  */