@lumenflow/cli 2.1.2 → 2.2.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 (87) hide show
  1. package/dist/agent-issues-query.d.ts +16 -0
  2. package/dist/agent-log-issue.d.ts +10 -0
  3. package/dist/agent-session-end.d.ts +10 -0
  4. package/dist/agent-session.d.ts +10 -0
  5. package/dist/backlog-prune.d.ts +84 -0
  6. package/dist/cli-entry-point.d.ts +8 -0
  7. package/dist/deps-add.d.ts +91 -0
  8. package/dist/deps-remove.d.ts +17 -0
  9. package/dist/docs-sync.d.ts +50 -0
  10. package/dist/file-delete.d.ts +84 -0
  11. package/dist/file-edit.d.ts +82 -0
  12. package/dist/file-read.d.ts +92 -0
  13. package/dist/file-write.d.ts +90 -0
  14. package/dist/flow-bottlenecks.d.ts +16 -0
  15. package/dist/flow-report.d.ts +16 -0
  16. package/dist/gates.d.ts +94 -0
  17. package/dist/git-branch.d.ts +65 -0
  18. package/dist/git-diff.d.ts +58 -0
  19. package/dist/git-log.d.ts +69 -0
  20. package/dist/git-status.d.ts +58 -0
  21. package/dist/guard-locked.d.ts +62 -0
  22. package/dist/guard-main-branch.d.ts +50 -0
  23. package/dist/guard-worktree-commit.d.ts +59 -0
  24. package/dist/index.d.ts +10 -0
  25. package/dist/init-plan.d.ts +80 -0
  26. package/dist/init.d.ts +46 -0
  27. package/dist/initiative-add-wu.d.ts +22 -0
  28. package/dist/initiative-bulk-assign-wus.d.ts +16 -0
  29. package/dist/initiative-create.d.ts +28 -0
  30. package/dist/initiative-edit.d.ts +34 -0
  31. package/dist/initiative-list.d.ts +12 -0
  32. package/dist/initiative-status.d.ts +11 -0
  33. package/dist/lumenflow-upgrade.d.ts +103 -0
  34. package/dist/mem-checkpoint.d.ts +16 -0
  35. package/dist/mem-cleanup.d.ts +29 -0
  36. package/dist/mem-create.d.ts +17 -0
  37. package/dist/mem-export.d.ts +10 -0
  38. package/dist/mem-export.js +138 -0
  39. package/dist/mem-inbox.d.ts +35 -0
  40. package/dist/mem-init.d.ts +15 -0
  41. package/dist/mem-ready.d.ts +16 -0
  42. package/dist/mem-signal.d.ts +16 -0
  43. package/dist/mem-start.d.ts +16 -0
  44. package/dist/mem-summarize.d.ts +22 -0
  45. package/dist/mem-triage.d.ts +22 -0
  46. package/dist/metrics-cli.d.ts +90 -0
  47. package/dist/metrics-snapshot.d.ts +18 -0
  48. package/dist/orchestrate-init-status.d.ts +11 -0
  49. package/dist/orchestrate-initiative.d.ts +12 -0
  50. package/dist/orchestrate-monitor.d.ts +11 -0
  51. package/dist/release.d.ts +117 -0
  52. package/dist/rotate-progress.d.ts +48 -0
  53. package/dist/session-coordinator.d.ts +74 -0
  54. package/dist/spawn-list.d.ts +16 -0
  55. package/dist/state-bootstrap.d.ts +92 -0
  56. package/dist/sync-templates.d.ts +52 -0
  57. package/dist/trace-gen.d.ts +84 -0
  58. package/dist/validate-agent-skills.d.ts +50 -0
  59. package/dist/validate-agent-sync.d.ts +36 -0
  60. package/dist/validate-backlog-sync.d.ts +37 -0
  61. package/dist/validate-skills-spec.d.ts +40 -0
  62. package/dist/validate.d.ts +60 -0
  63. package/dist/wu-block.d.ts +16 -0
  64. package/dist/wu-claim.d.ts +74 -0
  65. package/dist/wu-cleanup.d.ts +35 -0
  66. package/dist/wu-cleanup.js +11 -2
  67. package/dist/wu-create.d.ts +69 -0
  68. package/dist/wu-delete.d.ts +21 -0
  69. package/dist/wu-deps.d.ts +13 -0
  70. package/dist/wu-done.d.ts +225 -0
  71. package/dist/wu-done.js +9 -3
  72. package/dist/wu-edit.d.ts +63 -0
  73. package/dist/wu-edit.js +76 -9
  74. package/dist/wu-infer-lane.d.ts +17 -0
  75. package/dist/wu-preflight.d.ts +47 -0
  76. package/dist/wu-prune.d.ts +16 -0
  77. package/dist/wu-recover.d.ts +37 -0
  78. package/dist/wu-release.d.ts +19 -0
  79. package/dist/wu-repair.d.ts +60 -0
  80. package/dist/wu-spawn-completion.d.ts +10 -0
  81. package/dist/wu-spawn.d.ts +192 -0
  82. package/dist/wu-spawn.js +176 -12
  83. package/dist/wu-status.d.ts +25 -0
  84. package/dist/wu-unblock.d.ts +16 -0
  85. package/dist/wu-unlock-lane.d.ts +19 -0
  86. package/dist/wu-validate.d.ts +16 -0
  87. package/package.json +7 -6
package/dist/wu-edit.js CHANGED
@@ -84,6 +84,9 @@ export function validateDoneWUEdits(opts) {
84
84
  if (opts.codePaths && Array.isArray(opts.codePaths) && opts.codePaths.length > 0) {
85
85
  disallowedEdits.push('--code-paths');
86
86
  }
87
+ if (opts.risks && Array.isArray(opts.risks) && opts.risks.length > 0) {
88
+ disallowedEdits.push('--risks');
89
+ }
87
90
  if (opts.lane)
88
91
  disallowedEdits.push('--lane');
89
92
  if (opts.type)
@@ -157,13 +160,24 @@ const EDIT_OPTIONS = {
157
160
  acceptance: {
158
161
  name: 'acceptance',
159
162
  flags: '--acceptance <criterion>',
160
- description: 'Acceptance criterion (repeatable, replaces existing; use --append to add)',
163
+ description: 'Acceptance criterion (repeatable, appends to existing; use --replace-acceptance to overwrite)',
161
164
  isRepeatable: true,
162
165
  },
163
166
  notes: {
164
167
  name: 'notes',
165
168
  flags: '--notes <text>',
166
- description: 'New notes text (replaces existing)',
169
+ description: 'Notes text (appends to existing; use --replace-notes to overwrite)',
170
+ },
171
+ // WU-1144: Add explicit replace flags for notes and acceptance
172
+ replaceNotes: {
173
+ name: 'replaceNotes',
174
+ flags: '--replace-notes',
175
+ description: 'Replace existing notes instead of appending',
176
+ },
177
+ replaceAcceptance: {
178
+ name: 'replaceAcceptance',
179
+ flags: '--replace-acceptance',
180
+ description: 'Replace existing acceptance criteria instead of appending',
167
181
  },
168
182
  codePaths: {
169
183
  name: 'codePaths',
@@ -171,10 +185,16 @@ const EDIT_OPTIONS = {
171
185
  description: 'Code path (repeatable, replaces existing; use --append to add)',
172
186
  isRepeatable: true,
173
187
  },
188
+ risks: {
189
+ name: 'risks',
190
+ flags: '--risks <risk>',
191
+ description: 'Risk entry (repeatable, replaces existing; use --append to add)',
192
+ isRepeatable: true,
193
+ },
174
194
  append: {
175
195
  name: 'append',
176
196
  flags: '--append',
177
- description: 'Append to existing array values instead of replacing (for --acceptance, --code-paths)',
197
+ description: 'Append to existing array values instead of replacing (for --code-paths, --test-paths-*, --blocked-by, --add-dep)',
178
198
  },
179
199
  // WU-1456: Add lane reassignment support
180
200
  lane: {
@@ -310,7 +330,11 @@ function parseArgs() {
310
330
  EDIT_OPTIONS.description,
311
331
  EDIT_OPTIONS.acceptance,
312
332
  EDIT_OPTIONS.notes,
333
+ // WU-1144: Add explicit replace flags for notes and acceptance
334
+ EDIT_OPTIONS.replaceNotes,
335
+ EDIT_OPTIONS.replaceAcceptance,
313
336
  EDIT_OPTIONS.codePaths,
337
+ EDIT_OPTIONS.risks,
314
338
  EDIT_OPTIONS.append,
315
339
  // WU-1390: Add test path flags
316
340
  WU_OPTIONS.testPathsManual,
@@ -581,6 +605,25 @@ function mergeArrayField(existing, newValues, shouldAppend) {
581
605
  const existingArray = Array.isArray(existing) ? existing : [];
582
606
  return [...existingArray, ...newValues];
583
607
  }
608
+ /**
609
+ * WU-1144: Merge string field values with append-by-default behavior
610
+ *
611
+ * Notes and acceptance criteria should append by default (preserving original),
612
+ * with explicit --replace-notes and --replace-acceptance flags for overwrite.
613
+ *
614
+ * @param {string | undefined} existing - Current string value from WU
615
+ * @param {string} newValue - New value from CLI
616
+ * @param {boolean} shouldReplace - Whether to replace instead of append
617
+ * @returns {string} Merged string value
618
+ */
619
+ export function mergeStringField(existing, newValue, shouldReplace) {
620
+ // If replace mode or no existing value, just use new value
621
+ if (shouldReplace || !existing || existing.trim() === '') {
622
+ return newValue;
623
+ }
624
+ // Append with double newline separator
625
+ return `${existing}\n\n${newValue}`;
626
+ }
584
627
  /**
585
628
  * Load spec file and merge with original WU (preserving id and status)
586
629
  * @param {string} specPath - Path to spec file
@@ -610,7 +653,7 @@ function loadSpecFile(specPath, originalWU) {
610
653
  * Returns the updated WU object
611
654
  */
612
655
  // eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
613
- function applyEdits(wu, opts) {
656
+ export function applyEdits(wu, opts) {
614
657
  // Full spec replacement from file
615
658
  if (opts.specFile) {
616
659
  return loadSpecFile(opts.specFile, wu);
@@ -620,12 +663,17 @@ function applyEdits(wu, opts) {
620
663
  if (opts.description) {
621
664
  updated.description = opts.description;
622
665
  }
623
- // Handle repeatable --acceptance flags (WU-1388: replace by default, append with --append)
666
+ // WU-1144: Handle --acceptance with append-by-default behavior
667
+ // Appends to existing acceptance criteria unless --replace-acceptance is set
624
668
  if (opts.acceptance && opts.acceptance.length > 0) {
625
- updated.acceptance = mergeArrayField(wu.acceptance, opts.acceptance, opts.append);
669
+ // Invert the logic: append by default, replace with --replace-acceptance
670
+ const shouldAppend = !opts.replaceAcceptance;
671
+ updated.acceptance = mergeArrayField(wu.acceptance, opts.acceptance, shouldAppend);
626
672
  }
673
+ // WU-1144: Handle --notes with append-by-default behavior
674
+ // Appends to existing notes unless --replace-notes is set
627
675
  if (opts.notes) {
628
- updated.notes = opts.notes;
676
+ updated.notes = mergeStringField(wu.notes, opts.notes, opts.replaceNotes ?? false);
629
677
  }
630
678
  // WU-1456: Handle lane reassignment
631
679
  if (opts.lane) {
@@ -670,6 +718,21 @@ function applyEdits(wu, opts) {
670
718
  .filter(Boolean);
671
719
  updated.code_paths = mergeArrayField(wu.code_paths, codePaths, opts.append);
672
720
  }
721
+ // WU-1073: Handle repeatable --risks flags (replace by default, append with --append)
722
+ // Split comma-separated values within each entry for consistency with other list fields
723
+ if (opts.risks && opts.risks.length > 0) {
724
+ const rawRisks = opts.risks;
725
+ const risks = Array.isArray(rawRisks)
726
+ ? rawRisks
727
+ .flatMap((risk) => risk.split(','))
728
+ .map((risk) => risk.trim())
729
+ .filter(Boolean)
730
+ : rawRisks
731
+ .split(',')
732
+ .map((risk) => risk.trim())
733
+ .filter(Boolean);
734
+ updated.risks = mergeArrayField(wu.risks, risks, opts.append);
735
+ }
673
736
  // WU-1390: Handle test path flags (DRY refactor)
674
737
  const testPathMappings = [
675
738
  { optKey: 'testPathsManual', field: 'manual' },
@@ -757,6 +820,7 @@ async function main() {
757
820
  (opts.acceptance && opts.acceptance.length > 0) ||
758
821
  opts.notes ||
759
822
  (opts.codePaths && opts.codePaths.length > 0) ||
823
+ (opts.risks && opts.risks.length > 0) ||
760
824
  // WU-1390: Add test path flags to hasEdits check
761
825
  (opts.testPathsManual && opts.testPathsManual.length > 0) ||
762
826
  (opts.testPathsUnit && opts.testPathsUnit.length > 0) ||
@@ -779,9 +843,12 @@ async function main() {
779
843
  'Provide one of:\n' +
780
844
  ' --spec-file <path> Replace full spec from YAML file\n' +
781
845
  ' --description <text> Update description field\n' +
782
- ' --acceptance <text> Replace acceptance criteria (repeatable; use --append to add)\n' +
783
- ' --notes <text> Update notes field\n' +
846
+ ' --acceptance <text> Append acceptance criteria (repeatable; use --replace-acceptance to overwrite)\n' +
847
+ ' --notes <text> Append to notes (use --replace-notes to overwrite)\n' +
848
+ ' --replace-notes Replace existing notes instead of appending\n' +
849
+ ' --replace-acceptance Replace existing acceptance instead of appending\n' +
784
850
  ' --code-paths <paths> Replace code paths (repeatable; use --append to add)\n' +
851
+ ' --risks <risk> Replace risks (repeatable; use --append to add)\n' +
785
852
  ' --lane <lane> Update lane assignment (e.g., "Operations: Tooling")\n' +
786
853
  ' --type <type> Update WU type (feature, bug, refactor, documentation)\n' +
787
854
  ' --priority <priority> Update priority (P0, P1, P2, P3)\n' +
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * WU Lane Inference CLI (WU-908)
4
+ *
5
+ * Suggests sub-lane for a WU based on code paths and description.
6
+ * Wrapper around lib/lane-inference.mjs for standalone CLI usage.
7
+ *
8
+ * Usage:
9
+ * # Infer from existing WU
10
+ * node tools/wu-infer-lane.mjs --id WU-123
11
+ *
12
+ * # Infer from manual inputs
13
+ * node tools/wu-infer-lane.mjs --paths "tools/**" "docs/**" --desc "Tooling improvements"
14
+ *
15
+ * Returns suggested lane and confidence score (0-100).
16
+ */
17
+ export {};
@@ -0,0 +1,47 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * WU Preflight Validation
4
+ *
5
+ * WU-1803: Fast validation of code_paths and test paths before gates run.
6
+ * Completes in under 5 seconds vs 2+ minutes for full gates.
7
+ *
8
+ * This catches YAML mismatches early, preventing wasted time running full
9
+ * gates only to fail on code_paths validation at the end of wu:done.
10
+ *
11
+ * Usage:
12
+ * pnpm wu:preflight --id WU-1803 # Validate from main checkout
13
+ * pnpm wu:preflight --id WU-1803 --worktree worktrees/operations-gates-wu-1803
14
+ *
15
+ * Validates:
16
+ * - code_paths files exist
17
+ * - test file paths exist (unit, e2e, integration)
18
+ * - WU YAML schema is valid
19
+ */
20
+ /**
21
+ * Parse command-line arguments
22
+ * @param {string[]} argv - Process arguments
23
+ * @returns {object} Parsed arguments
24
+ */
25
+ declare function parseArgs(argv: any): {
26
+ help: boolean;
27
+ error?: undefined;
28
+ id?: undefined;
29
+ worktree?: undefined;
30
+ } | {
31
+ error: string;
32
+ help?: undefined;
33
+ id?: undefined;
34
+ worktree?: undefined;
35
+ } | {
36
+ id: any;
37
+ worktree: any;
38
+ help: boolean;
39
+ error?: undefined;
40
+ };
41
+ /**
42
+ * Detect worktree path from WU YAML or calculate from lane
43
+ * @param {string} id - WU ID
44
+ * @returns {string|null} Worktree path or null if not found
45
+ */
46
+ declare function detectWorktreePath(id: any): string;
47
+ export { parseArgs, detectWorktreePath };
@@ -0,0 +1,16 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * WU Prune Utility
4
+ *
5
+ * Maintains worktree hygiene by:
6
+ * - Running git worktree prune to clean stale metadata
7
+ * - Validating worktree ↔ WU ↔ lane mappings
8
+ * - Warning on orphaned worktrees (no matching WU YAML)
9
+ * - Warning on stale worktrees (WU status is done/blocked)
10
+ * - Warning on invalid branch naming conventions
11
+ *
12
+ * Usage:
13
+ * pnpm wu:prune # Dry-run mode (shows what would be done)
14
+ * pnpm wu:prune --execute # Actually run cleanup
15
+ */
16
+ export {};
@@ -0,0 +1,37 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * WU Recovery Command
4
+ *
5
+ * WU-1090: Context-aware state machine for WU lifecycle commands
6
+ *
7
+ * Analyzes WU state inconsistencies and offers recovery actions:
8
+ * - resume: Reconcile state and continue working (preserves work)
9
+ * - reset: Discard worktree and reset WU to ready
10
+ * - nuke: Remove all artifacts completely (requires --force)
11
+ * - cleanup: Remove leftover worktree for done WUs
12
+ *
13
+ * Usage:
14
+ * pnpm wu:recover --id WU-123 # Analyze issues
15
+ * pnpm wu:recover --id WU-123 --action resume # Apply fix
16
+ * pnpm wu:recover --id WU-123 --action nuke --force # Destructive
17
+ */
18
+ import { type RecoveryAnalysis } from '@lumenflow/core/dist/recovery/recovery-analyzer.js';
19
+ /**
20
+ * Check if action requires --force flag
21
+ */
22
+ export declare function requiresForceFlag(action: string): boolean;
23
+ /**
24
+ * Validate recovery action
25
+ */
26
+ export declare function validateRecoveryAction(action: string): {
27
+ valid: boolean;
28
+ error?: string;
29
+ };
30
+ /**
31
+ * Format recovery analysis output
32
+ */
33
+ export declare function formatRecoveryOutput(analysis: RecoveryAnalysis): string;
34
+ /**
35
+ * Get exit code for recovery command
36
+ */
37
+ export declare function getRecoveryExitCode(analysis: RecoveryAnalysis, actionFailed: boolean): number;
@@ -0,0 +1,19 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * WU Release Command (WU-1080)
4
+ *
5
+ * Releases an orphaned WU from in_progress back to ready state.
6
+ * Use when an agent is interrupted mid-WU and the WU needs to be reclaimed.
7
+ *
8
+ * Sequence (micro-worktree pattern):
9
+ * 1) Validate WU is in_progress
10
+ * 2) Create micro-worktree from main
11
+ * 3) Append release event to state store
12
+ * 4) Regenerate backlog.md and status.md
13
+ * 5) Commit in micro-worktree, push directly to origin/main
14
+ * 6) Optionally remove the work worktree
15
+ *
16
+ * Usage:
17
+ * pnpm wu:release --id WU-1080 --reason "Agent interrupted"
18
+ */
19
+ export {};
@@ -0,0 +1,60 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * WU State Repair Tool (Unified - WU-1826, WU-2240)
4
+ *
5
+ * Layer 2 defense-in-depth: detect and repair WU state inconsistencies.
6
+ *
7
+ * This unified tool consolidates four repair modes:
8
+ * - Consistency mode (default): detect/repair state inconsistencies
9
+ * - Claim mode (--claim): repair missing claim metadata in worktrees
10
+ * - Admin mode (--admin): administrative fixes for done WUs
11
+ * - State mode (--repair-state): repair corrupted wu-events.jsonl (WU-2240)
12
+ *
13
+ * Usage:
14
+ * # Consistency mode (default)
15
+ * pnpm wu:repair --id WU-123 # Repair single WU
16
+ * pnpm wu:repair --id WU-123 --check # Audit only, no changes
17
+ * pnpm wu:repair --all # Batch repair all WUs
18
+ * pnpm wu:repair --all --check # Audit all WUs
19
+ *
20
+ * # Claim mode
21
+ * pnpm wu:repair --claim --id WU-123 # Repair claim metadata
22
+ * pnpm wu:repair --claim --id WU-123 --check # Check only
23
+ * pnpm wu:repair --claim --id WU-123 --worktree /path/to/worktree
24
+ *
25
+ * # Admin mode
26
+ * pnpm wu:repair --admin --id WU-123 --lane "Operations: Tooling"
27
+ * pnpm wu:repair --admin --id WU-123 --status cancelled
28
+ * pnpm wu:repair --admin --id WU-123 --notes "Administrative fix"
29
+ * pnpm wu:repair --admin --id WU-123 --initiative INIT-001
30
+ *
31
+ * # State mode (WU-2240)
32
+ * pnpm wu:repair --repair-state # Repair default state file
33
+ * pnpm wu:repair --repair-state --path /path/to/wu-events.jsonl # Repair specific file
34
+ *
35
+ * Exit codes:
36
+ * 0: Success (no issues or all repaired)
37
+ * 1: Issues detected (--check mode)
38
+ * 2: Repair failed
39
+ *
40
+ * DEPRECATION NOTICE:
41
+ * - pnpm wu:repair-claim is deprecated. Use: pnpm wu:repair --claim
42
+ * - pnpm wu:admin-repair is deprecated. Use: pnpm wu:repair --admin
43
+ *
44
+ * @see {@link tools/lib/wu-repair-core.mjs} - Core repair logic
45
+ * @see {@link tools/lib/wu-consistency-checker.mjs} - Consistency detection/repair
46
+ * @see {@link tools/lib/wu-state-store.mjs} - State file repair (repairStateFile)
47
+ */
48
+ /**
49
+ * Normalise WU ID to uppercase with WU- prefix
50
+ * @param {string} id - Raw WU ID
51
+ * @returns {string} Normalised WU ID
52
+ */
53
+ declare function normaliseWUId(id: any): any;
54
+ /**
55
+ * Validate WU ID format
56
+ * @param {string} id - WU ID to validate
57
+ * @returns {boolean} True if valid
58
+ */
59
+ declare function isValidWUId(id: any): boolean;
60
+ export { normaliseWUId, isValidWUId };
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Generate the Completion Workflow section for sub-agents (WU-2682).
3
+ *
4
+ * Explicitly instructs sub-agents to run wu:done autonomously after gates pass.
5
+ * This prevents agents from asking permission instead of completing.
6
+ *
7
+ * @param {string} id - WU ID
8
+ * @returns {string} Completion Workflow section
9
+ */
10
+ export declare function generateCompletionWorkflowSection(id: string): string;
@@ -0,0 +1,192 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * WU Spawn Helper
4
+ *
5
+ * Generates ready-to-use Task tool invocations for sub-agent WU execution.
6
+ * Includes context loading preamble, skills selection guidance, and constraints block.
7
+ *
8
+ * Usage:
9
+ * pnpm wu:spawn --id WU-123
10
+ * pnpm wu:spawn --id WU-123 --codex
11
+ *
12
+ * Output:
13
+ * A complete Task tool invocation block with:
14
+ * - Context loading preamble (.claude/CLAUDE.md, README, lumenflow, WU YAML)
15
+ * - WU details and acceptance criteria
16
+ * - Skills Selection section (sub-agent reads catalogue and selects at runtime)
17
+ * - Mandatory agent advisory
18
+ * - Constraints block at end (Lost in the Middle research)
19
+ *
20
+ * Skills Selection:
21
+ * This command is AGENT-FACING. Unlike /wu-prompt (human-facing, skills selected
22
+ * at generation time), wu:spawn instructs the sub-agent to read the skill catalogue
23
+ * and select skills at execution time based on WU context.
24
+ *
25
+ * Codex Mode:
26
+ * When --codex is used, outputs a Codex/GPT-friendly Markdown prompt (no antml/XML escaping).
27
+ *
28
+ * @see {@link docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md} - Context loading templates
29
+ */
30
+ import { getConfig } from '@lumenflow/core/dist/lumenflow-config.js';
31
+ import type { ClientConfig } from '@lumenflow/core/dist/lumenflow-config-schema.js';
32
+ /**
33
+ * WU-1131: Truncation prevention constants
34
+ *
35
+ * These constants help detect when spawn output has been truncated during
36
+ * copy-paste operations or context loading. The warning banner alerts users
37
+ * to the truncation risk, and the end sentinel allows verification that
38
+ * the full output was received.
39
+ */
40
+ export declare const TRUNCATION_WARNING_BANNER = "<!-- LUMENFLOW_TRUNCATION_WARNING -->\n<!--\n \u26A0\uFE0F CRITICAL: DO NOT TRUNCATE THIS OUTPUT\n\n This spawn prompt MUST be copied verbatim. Truncation causes:\n - Missing constraints (agents ignore safety rules)\n - Missing TDD directives (agents skip tests)\n - Degraded agent performance\n\n VERIFICATION: The output MUST end with: <!-- LUMENFLOW_SPAWN_END -->\n If you don't see that sentinel at the end, the output was truncated.\n-->\n";
41
+ export declare const SPAWN_END_SENTINEL = "<!-- LUMENFLOW_SPAWN_END -->";
42
+ /**
43
+ * Generate effort scaling rules section (WU-1986)
44
+ *
45
+ * Based on Anthropic multi-agent research: helps agents decide when to
46
+ * spawn sub-agents vs handle inline.
47
+ *
48
+ * @returns {string} Effort scaling section
49
+ */
50
+ export declare function generateEffortScalingRules(): string;
51
+ /**
52
+ * Generate parallel tool call guidance (WU-1986)
53
+ *
54
+ * Based on Anthropic research: 3+ parallel tool calls significantly improve performance.
55
+ *
56
+ * @returns {string} Parallel tool call guidance
57
+ */
58
+ export declare function generateParallelToolCallGuidance(): string;
59
+ /**
60
+ * Generate iterative search heuristics (WU-1986)
61
+ *
62
+ * Based on Anthropic research: start broad, narrow focus.
63
+ *
64
+ * @returns {string} Search heuristics section
65
+ */
66
+ export declare function generateIterativeSearchHeuristics(): string;
67
+ /**
68
+ * Generate token budget awareness section (WU-1986)
69
+ *
70
+ * @param {string} id - WU ID
71
+ * @returns {string} Token budget section
72
+ */
73
+ export declare function generateTokenBudgetAwareness(id: any): string;
74
+ /**
75
+ * Generate structured completion format (WU-1986)
76
+ *
77
+ * @param {string} id - WU ID
78
+ * @returns {string} Completion format section
79
+ */
80
+ export declare function generateCompletionFormat(_id: any): string;
81
+ /**
82
+ * Generate agent coordination section (WU-1987)
83
+ *
84
+ * Provides guidance on mem:signal for parallel agent coordination,
85
+ * orchestrate:status for dashboard checks, and abandoned WU handling.
86
+ *
87
+ * @param {string} id - WU ID
88
+ * @returns {string} Agent coordination section
89
+ */
90
+ export declare function generateAgentCoordinationSection(id: any): string;
91
+ /**
92
+ * Generate quick fix commands section (WU-1987)
93
+ *
94
+ * Provides format/lint/typecheck commands for quick fixes before gates.
95
+ *
96
+ * @returns {string} Quick fix commands section
97
+ */
98
+ export declare function generateQuickFixCommands(): string;
99
+ /**
100
+ * Generate Lane Selection section (WU-2107)
101
+ *
102
+ * Provides guidance on lane selection when creating new WUs.
103
+ * Points agents to wu:infer-lane for automated lane suggestions.
104
+ *
105
+ * @returns {string} Lane Selection section
106
+ */
107
+ export declare function generateLaneSelectionSection(): string;
108
+ /**
109
+ * Generate Worktree Path Guidance section (WU-2362)
110
+ *
111
+ * Provides guidance for sub-agents on working within worktrees, including
112
+ * how to determine the worktree root and where to create stamps.
113
+ *
114
+ * Problem: CLAUDE_PROJECT_DIR is hook-only; sub-agents inherit parent cwd (main).
115
+ * Solution: Use git rev-parse --show-toplevel to determine actual worktree root.
116
+ *
117
+ * @param {string|undefined} worktreePath - Worktree path from WU YAML
118
+ * @returns {string} Worktree path guidance section
119
+ */
120
+ export declare function generateWorktreePathGuidance(worktreePath: any): string;
121
+ /**
122
+ * Generate the Action section based on WU claim status (WU-1745).
123
+ *
124
+ * If WU is already claimed (has claimed_at and worktree_path), tells agent
125
+ * to continue in the existing worktree.
126
+ *
127
+ * If WU is unclaimed (status: ready), tells agent to run wu:claim first.
128
+ *
129
+ * @param {object} doc - WU YAML document
130
+ * @param {string} id - WU ID
131
+ * @returns {string} Action section content
132
+ */
133
+ export declare function generateActionSection(doc: any, id: any): string;
134
+ /**
135
+ * Generate the Completion Workflow section for sub-agents (WU-2682).
136
+ *
137
+ * Explicitly instructs sub-agents to run wu:done autonomously after gates pass.
138
+ * This prevents agents from asking permission instead of completing.
139
+ *
140
+ * @param {string} id - WU ID
141
+ * @returns {string} Completion Workflow section
142
+ */
143
+ export declare function generateCompletionWorkflowSection(id: string): string;
144
+ interface ClientContext {
145
+ name: string;
146
+ config?: ClientConfig;
147
+ }
148
+ interface SpawnOptions {
149
+ thinking?: boolean;
150
+ noThinking?: boolean;
151
+ budget?: string;
152
+ client?: ClientContext;
153
+ config?: ReturnType<typeof getConfig>;
154
+ }
155
+ /**
156
+ * Generate the complete Task tool invocation
157
+ *
158
+ * @param {object} doc - WU YAML document
159
+ * @param {string} id - WU ID
160
+ * @param {SpawnStrategy} strategy - Client strategy
161
+ * @param {object} [options={}] - Thinking mode options
162
+ * @param {boolean} [options.thinking] - Whether extended thinking is enabled
163
+ * @param {boolean} [options.noThinking] - Whether thinking is explicitly disabled
164
+ * @param {string} [options.budget] - Token budget for thinking
165
+ * @returns {string} Complete Task tool invocation
166
+ */
167
+ export declare function generateTaskInvocation(doc: any, id: any, strategy: any, options?: SpawnOptions): string;
168
+ export declare function generateCodexPrompt(doc: any, id: any, strategy: any, options?: SpawnOptions): string;
169
+ /**
170
+ * WU-1603: Check if a lane is currently occupied by another WU
171
+ *
172
+ * @param {string} lane - Lane name (e.g., "Operations: Tooling")
173
+ * @returns {import('@lumenflow/core/dist/lane-lock.js').LockMetadata|null} Lock metadata if occupied, null otherwise
174
+ */
175
+ export declare function checkLaneOccupation(lane: any): import("@lumenflow/core/dist/lane-lock.js").LockMetadata;
176
+ /**
177
+ * WU-1603: Generate a warning message when lane is occupied
178
+ *
179
+ * @param {import('@lumenflow/core/dist/lane-lock.js').LockMetadata} lockMetadata - Lock metadata
180
+ * @param {string} targetWuId - WU ID being spawned
181
+ * @param {Object} [options={}] - Options
182
+ * @param {boolean} [options.isStale] - Whether the lock is stale (>24h old)
183
+ * @returns {string} Warning message
184
+ */
185
+ interface LaneOccupationOptions {
186
+ isStale?: boolean;
187
+ }
188
+ export declare function generateLaneOccupationWarning(lockMetadata: {
189
+ lane: string;
190
+ wuId: string;
191
+ }, targetWuId: string, options?: LaneOccupationOptions): string;
192
+ export {};