@drbaher/draft-cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,101 @@ All notable changes to this project will be documented in this file. The
 format is loosely based on [Keep a Changelog](https://keepachangelog.com/),
 and the project adheres to semantic versioning once it leaves 0.x.
 
+## 0.7.0 — 2026-05-17
+
+### Added
+
+- **Multi-document bundles.** `draft --bundle <bundle.json>` reads a
+  bundle definition and fills multiple templates with the same set of
+  parameter values in one invocation:
+  ```json
+  {
+    "_meta": { "schema_version": 1 },
+    "outputs": [
+      { "template": "msa/v3.md",        "output": "out/msa.md" },
+      { "template": "order-form/v3.md", "output": "out/order-form.md" }
+    ]
+  }
+  ```
+  Each template runs through detection independently. Placeholders
+  across templates are unioned by key (so a key declared in any
+  template's schema applies to all — Q3.3 locked). Resolution,
+  typed-parameter normalization, and computed values all run once on
+  the union. Each output is then substituted using its own
+  template/tier and written to its own path. `parties.json` refs
+  (v0.6.0) resolve inside bundle entries too.
+- **Schema-union semantics.** A key declared/detected in any bundle
+  template applies to every template in the bundle. First-occurrence
+  metadata wins; resolved values flow to all templates that reference
+  the same key.
+- **`.docx` bundle entries** round-trip through `substituteDocxXml`
+  when the entry's `output` path has the `.docx` extension. Same
+  runs/styles preservation as single-doc `.docx` mode.
+- **New public API:** `loadBundle(path)`, `cmdBundle(opts, bundle,
+  paramsObj, envObj, io)`.
+
+### Decisions locked (V2_BRIEFS_REMAINING Q3.1–Q3.3)
+
+- **Q3.1 Bundle file format:** JSON object with `outputs` array of
+  `{template, output}` pairs. Each entry has its own output path,
+  enabling per-doc overrides without inventing a custom DSL.
+- **Q3.2 Partial-failure policy:** abort-all. Any pre-write error
+  (no detection in an entry, missing required param across the
+  union, type / computed / ref failure, positional mismatch, schema
+  orphan) exits 4 before any file is written. Write failures
+  mid-bundle exit 1; earlier successful writes are not rolled back
+  (best-effort atomicity at the filesystem boundary).
+- **Q3.3 Schema union semantics:** keys declared in any template's
+  schema (or detected as canonical-key matches without a schema)
+  apply across the bundle. Same value resolves into every template
+  that references the key.
+
+## 0.6.0 — 2026-05-16
+
+### Added
+
+- **Cross-template `parties.json` registry.** A repo-local
+  `parties.json` declares known parties once; templates' schemas
+  reference fields with `ref:parties.<key>.<field>`:
+  ```json
+  // parties.json
+  { "acme_corp": { "name": "Acme Corporation", "state": "Delaware" } }
+  ```
+  ```json
+  // <template>.params.json
+  {
+    "_meta": { "v": 1 },
+    "party_a":       { "aliases": ["Party A"],       "default": "ref:parties.acme_corp.name" },
+    "party_a_state": { "aliases": ["Party A State"], "default": "ref:parties.acme_corp.state" }
+  }
+  ```
+  Resolution happens between `resolveValues` and typed-parameter
+  normalization, so `ref:`-resolved values feed cleanly into
+  `type: date | money | party` flows.
+- **`--parties PATH` flag** overrides the default CWD/`parties.json`
+  lookup. Missing explicit path → exit 1 with a clear error.
+- **New public API:** `loadParties(path)`, `resolveRef(value, parties)`,
+  `resolveRefs(resolved, sources, parties)`.
+
+### Decisions locked (V2_BRIEFS_REMAINING Q2.1–Q2.3)
+
+- **Q2.1 File location:** default is `./parties.json` in CWD;
+  override with `--parties PATH`.
+- **Q2.2 Ref scope:** refs resolve in `--params` JSON and schema
+  `default` values only. CLI flag values with `ref:` prefix pass
+  through **unchanged** — they're treated as literal strings.
+- **Q2.3 Versioning:** out of scope for v0.6.0. When a party's
+  metadata changes in `parties.json`, all drafts that ref it produce
+  different output if re-run. Documented as a known property.
+
+### Schema-contract change
+
+`PARAM_SCHEMA.md` §5 gains a "Cross-template `parties.json` registry"
+subsection. v0.6.0 schemas are forward-compatible with v0.5.x
+readers — `ref:` strings just look like literal values to older
+readers (and won't substitute correctly, but won't error out either
+since "ref:..." is a valid string).
+
 ## 0.5.0 — 2026-05-16
 
 ### Added

package/PARAM_SCHEMA.md

@@ -388,6 +388,133 @@ and `position_index` (0-based) fields. `substitute` switches to
 byte-index substitution for these, which `substituteDocxXml` does not
 currently support.
 
+### Cross-template `parties.json` registry (v0.6.0, opt-in)
+
+A repo-local `parties.json` declares known parties once; templates'
+schemas reference fields with `ref:parties.<party_key>.<field>`.
+Eliminates duplicating party metadata (name, state, CIK, signing
+contact) across every template.
+
+```json
+// parties.json
+{
+  "acme_corp": {
+    "name": "Acme Corporation",
+    "state": "Delaware",
+    "cik": "0001234567"
+  }
+}
+```
+
+```json
+// <template>.params.json
+{
+  "_meta": { "schema_version": 1 },
+  "party_a":       { "aliases": ["Party A"],       "default": "ref:parties.acme_corp.name" },
+  "party_a_state": { "aliases": ["Party A State"], "default": "ref:parties.acme_corp.state" }
+}
+```
+
+**Q2.1 locked:** default file location is `./parties.json` in the
+process CWD. Override with `--parties PATH`. Missing explicit path
+is exit 1 (`EXIT.IO`); missing default file silently means "no
+registry loaded" (refs then fail at resolution time with a clear hint).
+
+**Q2.2 locked:** refs resolve in `--params` JSON values and schema
+`default` values only. **CLI flag values pass through unchanged** —
+`--party-a "ref:parties.acme.name"` is treated as a literal string
+that happens to start with `ref:`. This keeps CLI parsing
+unambiguous and avoids users accidentally leaking parties data on
+the command line.
+
+**Q2.3 locked:** versioning is out of scope for v0.6.0. When a
+party's metadata changes in `parties.json`, all drafts that ref it
+produce different output if re-run. This is by design (single source
+of truth for party info), but worth knowing — historical drafts may
+diverge from their original `parties.json` values.
+
+**Ref syntax:** `ref:parties.<party_key>.<field>` where both
+`<party_key>` and `<field>` match `[A-Za-z_][A-Za-z0-9_]*`. Malformed
+refs, unknown party keys, and unknown fields all surface as hard
+errors before substitution (exit 4).
+
+**Resolution order:** value resolution → ref expansion → typed-param
+normalization → computed values → substitute. Refs run before typed
+normalization so a ref returning `"2027-01-15"` can still flow
+through `type: date` formatting.
+
+**Field-value coercion:** ref'd fields are coerced to strings via
+`String(value)` (e.g. `cik: 1234567` becomes `"1234567"`). The
+parties registry can store non-string values for ergonomics, but
+substitution always uses string output.
+
+Programmatic API: `loadParties(path)`, `resolveRef(value, parties)`,
+`resolveRefs(resolved, sources, parties)`.
+
+### Multi-document bundles (v0.7.0, opt-in)
+
+`draft --bundle <bundle.json>` reads a bundle definition and fills
+multiple templates with one shared set of parameter values:
+
+```json
+{
+  "_meta": { "schema_version": 1 },
+  "outputs": [
+    { "template": "msa/v3.md",        "output": "out/msa.md" },
+    { "template": "order-form/v3.md", "output": "out/order-form.md" },
+    { "template": "dpa/v2.docx",      "output": "out/dpa.docx" }
+  ]
+}
+```
+
+```sh
+draft --bundle deal.bundle.json --params deal.json --parties parties.json
+```
+
+**Q3.1 locked:** the bundle file is a JSON object with an `outputs`
+array of `{template, output}` pairs. Each entry has its own
+`template` (filesystem path or `template-vault get` ref) and own
+`output` path. No alternative shorter DSL — JSON is unambiguous and
+extensible.
+
+**Q3.2 locked:** abort-all. Any pre-write error (no detection in an
+entry, missing required param across the union, type validation
+failure, computed-value failure, ref-resolution failure, positional
+mismatch, schema orphan) returns exit 4 **before any file is
+written**. The bundle either writes all `outputs` or writes none.
+Filesystem write errors mid-bundle exit 1; earlier successful
+writes are not rolled back (best-effort atomicity at the filesystem
+boundary).
+
+**Q3.3 locked:** schema union. A key declared in any template's
+schema, or detected as a canonical-key match without a schema,
+applies across the entire bundle. The same resolved value flows to
+every template that references the key. First-occurrence metadata
+wins (`type`, `format`, `currency`, `computed`, `positions`, etc.);
+templates with richer aliases for the same key contribute their
+aliases for detection in their own body but don't redefine the key.
+
+**Per-template detection independence:** each bundle entry runs the
+full T1–T5 cascade against its own body. Different entries can land
+on different tiers (e.g. MSA on T1 brackets, DPA on T3 highlights).
+Positional addressing on T1/T2 still works per entry.
+
+**`.docx` entries** with a `.docx` output path round-trip via
+`substituteDocxXml` + `writeDocxBuffer`, preserving runs/styles.
+Mixing text and `.docx` entries in the same bundle works.
+
+**`parties.json` refs** (v0.6.0) resolve inside bundles too — load
+the same parties file once via `--parties PATH` (or the CWD
+default), and ref strings in any bundle template's schema default
+or in shared `--params` expand against it.
+
+**`--json`** for bundles emits a structured result listing each
+entry's template, output path, and tier, plus the union of resolved
+keys and their sources.
+
+Programmatic API: `loadBundle(path)` parses + validates; `cmdBundle`
+runs the orchestration with the same IO contract as `cmdDraft`.
+
 ### Orphan handling (Q4 locked)
 
 Schema declares a key whose alias list matches no detected phrase →

package/draft-cli.mjs

@@ -70,7 +70,7 @@ import { fileURLToPath } from "node:url";
  */
 
 /** @type {string} */
-export const VERSION = "0.5.0";
+export const VERSION = "0.7.0";
 
 // ─── EXIT CODES ─────────────────────────────────────────────────────────────
 /**
@@ -277,6 +277,8 @@ export function parseArgs(argv) {
     if (a === "--silent" || a === "-q") { opts.silent = true; continue; }
     if (a === "--diff") { opts.diff = true; continue; }
     if (a === "--params") { opts.params = argv[++i]; continue; }
+    if (a === "--parties") { opts.parties = argv[++i]; continue; }
+    if (a === "--bundle") { opts.bundle = argv[++i]; continue; }
     if (a === "--output" || a === "-o") { opts.output = argv[++i]; continue; }
     if (a === "--syntax") {
       const v = argv[++i];
@@ -1272,6 +1274,181 @@ export function loadParamsFile(path) {
   }
 }
 
+/**
+ * Load a `parties.json` registry (v2 #5). Returns the parsed object or
+ * `null` if no file is present. Explicit `--parties PATH` errors if
+ * the path doesn't exist; the default `./parties.json` is treated as
+ * absent if the file isn't there (no error).
+ *
+ * @param {string | null} explicitPath — value of `--parties PATH`, or null
+ *   to auto-detect `./parties.json` in CWD.
+ * @returns {Object<string, Object<string, *>> | null}
+ * @throws {Error} with `.exitCode = EXIT.IO` on missing explicit file or invalid JSON.
+ */
+export function loadParties(explicitPath) {
+  const fallback = "parties.json";
+  const path = explicitPath || (existsSync(fallback) ? fallback : null);
+  if (!path) return null;
+  if (!existsSync(path)) {
+    const e = new Error(`parties file not found: ${path}`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    const e = new Error(`could not parse ${path}: ${err.message}`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const e = new Error(`parties file ${path} must be a JSON object`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  // Reject non-object party entries early so downstream `ref:` resolution
+  // can safely lookup fields without a per-call shape check.
+  for (const [partyKey, party] of Object.entries(parsed)) {
+    if (!party || typeof party !== "object" || Array.isArray(party)) {
+      const e = new Error(`parties file ${path}: entry "${partyKey}" must be a JSON object`);
+      e.exitCode = EXIT.IO;
+      throw e;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Resolve a `ref:parties.<party>.<field>` reference against a loaded
+ * parties object. Throws on malformed ref, missing parties registry,
+ * unknown party, or unknown field. Non-`ref:` strings pass through
+ * unchanged.
+ *
+ * @param {string} value
+ * @param {Object<string, Object<string, *>> | null} parties
+ * @returns {string}
+ * @throws {Error} on malformed or unresolvable reference.
+ */
+export function resolveRef(value, parties) {
+  if (typeof value !== "string" || !value.startsWith("ref:")) return value;
+  if (!parties) {
+    throw new Error(`reference "${value}" but no parties.json loaded (pass --parties PATH or put parties.json in cwd)`);
+  }
+  const m = /^ref:parties\.([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+  if (!m) {
+    throw new Error(`malformed reference "${value}" (expected "ref:parties.<party_key>.<field>")`);
+  }
+  const [, partyKey, fieldKey] = m;
+  const party = parties[partyKey];
+  if (!party) {
+    throw new Error(`unknown party "${partyKey}" in reference "${value}"`);
+  }
+  if (!(fieldKey in party)) {
+    throw new Error(`unknown field "${fieldKey}" on party "${partyKey}" in reference "${value}"`);
+  }
+  const out = party[fieldKey];
+  return out == null ? "" : String(out);
+}
+
+/**
+ * Walk a resolved-values map and replace any `ref:` strings with their
+ * resolved values from the parties registry. CLI-sourced values are
+ * left alone (Q2.2: refs are params/default only, never CLI). Collects
+ * all errors before returning so the user sees every failure at once.
+ *
+ * @param {Object<string,string>} resolved — mutated in place.
+ * @param {Object<string,string>} sources — from `resolveValues`.
+ * @param {Object<string, Object<string, *>> | null} parties
+ * @returns {{ ok: boolean, errors: Array<{ key: string, message: string }> }}
+ */
+export function resolveRefs(resolved, sources, parties) {
+  const errors = [];
+  for (const [key, value] of Object.entries(resolved)) {
+    if (sources[key] === "cli") continue; // Q2.2: CLI values pass through
+    if (typeof value !== "string" || !value.startsWith("ref:")) continue;
+    try {
+      resolved[key] = resolveRef(value, parties);
+    } catch (e) {
+      errors.push({ key, message: e.message });
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Load and validate a bundle definition (v2 #6). Bundles describe
+ * multiple templates that should be filled with the same set of
+ * parameter values in one invocation:
+ *
+ *   {
+ *     "_meta": { "schema_version": 1 },
+ *     "outputs": [
+ *       { "template": "msa/v3.md",        "output": "out/msa.md" },
+ *       { "template": "order-form/v3.md", "output": "out/order-form.md" }
+ *     ]
+ *   }
+ *
+ * Returns the parsed bundle. Throws on missing file, invalid JSON, no
+ * `outputs` array, empty `outputs`, missing `template`/`output` on an
+ * entry, or duplicate output paths.
+ *
+ * @param {string} path
+ * @returns {{ outputs: Array<{ template: string, output: string }> }}
+ * @throws {Error} with `.exitCode = EXIT.IO`
+ */
+export function loadBundle(path) {
+  if (!existsSync(path)) {
+    const e = new Error(`bundle file not found: ${path}`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    const e = new Error(`could not parse bundle ${path}: ${err.message}`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const e = new Error(`bundle ${path} must be a JSON object`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  if (!Array.isArray(parsed.outputs) || parsed.outputs.length === 0) {
+    const e = new Error(`bundle ${path}: missing or empty "outputs" array`);
+    e.exitCode = EXIT.IO;
+    throw e;
+  }
+  const seenOutputs = new Set();
+  for (let i = 0; i < parsed.outputs.length; i++) {
+    const o = parsed.outputs[i];
+    if (!o || typeof o !== "object" || Array.isArray(o)) {
+      const e = new Error(`bundle ${path}: outputs[${i}] must be an object`);
+      e.exitCode = EXIT.IO;
+      throw e;
+    }
+    if (typeof o.template !== "string" || !o.template) {
+      const e = new Error(`bundle ${path}: outputs[${i}].template must be a non-empty string`);
+      e.exitCode = EXIT.IO;
+      throw e;
+    }
+    if (typeof o.output !== "string" || !o.output) {
+      const e = new Error(`bundle ${path}: outputs[${i}].output must be a non-empty string`);
+      e.exitCode = EXIT.IO;
+      throw e;
+    }
+    if (seenOutputs.has(o.output)) {
+      const e = new Error(`bundle ${path}: outputs[${i}].output "${o.output}" is duplicated`);
+      e.exitCode = EXIT.IO;
+      throw e;
+    }
+    seenOutputs.add(o.output);
+  }
+  return { outputs: parsed.outputs.map(o => ({ template: o.template, output: o.output })) };
+}
+
 /**
  * Resolve a value for every placeholder using the locked precedence chain:
  * CLI flag > `--params` JSON > `--interactive` prompt > schema default >
@@ -1912,7 +2089,7 @@ export async function cmdListPlaceholders(opts, input, schema, envObj, { fetcher
   return EXIT.OK;
 }
 
-export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err } = {}) {
+export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null } = {}) {
   const result = await runCascade(input, opts, schema, envObj, { fetcher });
   if (result.tier === "none") {
     err.write(paint("error: no placeholders detected by any tier\n", "red", err));
@@ -1940,6 +2117,22 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
     }
     return EXIT.VALIDATION;
   }
+  // v2 #5: parties.json ref resolution. Refs like
+  // `ref:parties.acme_corp.name` in --params or schema defaults expand
+  // before typed normalization. CLI values pass through unchanged.
+  const refCheck = resolveRefs(resolved, sources, parties);
+  if (!refCheck.ok) {
+    for (const re of refCheck.errors) {
+      err.write(paint(`error: parties reference failed for "${re.key}": ${re.message}\n`, "red", err));
+    }
+    if (opts.json) {
+      out.write(JSON.stringify({
+        ok: false,
+        ref_errors: refCheck.errors.map(({ key, message }) => ({ key, message })),
+      }, null, 2) + "\n");
+    }
+    return EXIT.VALIDATION;
+  }
   // v2 #3: typed-parameter validation. Mirror what cmdDraft does so
   // `--validate` catches type errors before the user runs draft.
   const typeCheck = normalizeTypedValues(result.placeholders, resolved);
@@ -1977,7 +2170,7 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
   return EXIT.OK;
 }
 
-export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err } = {}) {
+export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties = null } = {}) {
   const result = await runCascade(input, opts, schema, envObj, { fetcher });
   if (result.tier === "none") {
     const hasProvider = Boolean(llmProviderFromEnv(envObj));
@@ -2045,6 +2238,18 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
     return EXIT.VALIDATION;
   }
 
+  // v2 #5: parties.json ref resolution. Refs like
+  // `ref:parties.acme_corp.name` in --params or schema defaults expand
+  // before typed normalization. CLI values pass through unchanged
+  // (Q2.2 lock).
+  const refCheck = resolveRefs(resolved, sources, parties);
+  if (!refCheck.ok) {
+    for (const re of refCheck.errors) {
+      err.write(paint(`error: parties reference failed for "${re.key}": ${re.message}\n`, "red", err));
+    }
+    return EXIT.VALIDATION;
+  }
+
   // v2 #3: typed-parameter normalization. Schema entries can declare
   // `type: date | money | party`. Inputs are validated and normalized
   // before substitution. Hard error on bad input (Q3.3 decision).
@@ -2151,6 +2356,151 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
   return EXIT.OK;
 }
 
+/**
+ * cmdBundle — orchestrate filling multiple templates with one shared
+ * parameter set (v2 #6). For each bundle entry:
+ *   1. resolveInput + loadSchema (per template)
+ *   2. runCascade (per template)
+ *   3. union placeholders by key
+ * Then resolve values once across the union (CLI/--params/interactive/
+ * default), run typed-param normalization + computed values, and write
+ * each output. Q3.2 locked: any pre-write error (no-detection in an
+ * entry, missing required param across the union, type / computed
+ * failure) aborts the whole bundle before any file is written.
+ *
+ * @param {Object} opts
+ * @param {{outputs: Array<{template: string, output: string}>}} bundle
+ * @param {Object} paramsObj
+ * @param {Object} envObj
+ * @returns {Promise<number>} exit code
+ */
+export async function cmdBundle(opts, bundle, paramsObj, envObj, { fetcher, out, err, spawner, stdinReader, parties = null } = {}) {
+  // Phase 1: load each template + schema, run detection.
+  const entries = [];
+  for (let i = 0; i < bundle.outputs.length; i++) {
+    const o = bundle.outputs[i];
+    let input, schema, cascade;
+    try {
+      input = await resolveInput(o.template, { spawner, stdinReader });
+      schema = loadSchema(input.path);
+    } catch (e) {
+      err.write(paint(`error: bundle entry ${i} "${o.template}": ${e.message}\n`, "red", err));
+      return e.exitCode || EXIT.IO;
+    }
+    cascade = await runCascade(input, opts, schema, envObj, { fetcher });
+    if (cascade.tier === "none") {
+      err.write(paint(`error: bundle entry ${i} "${o.template}": no placeholders detected by any tier\n`, "red", err));
+      return EXIT.VALIDATION;
+    }
+    // v2 #7 positional errors per template — abort early.
+    if (cascade.positional_errors && cascade.positional_errors.length > 0) {
+      for (const pe of cascade.positional_errors) {
+        err.write(paint(`error: bundle entry ${i} "${o.template}" positional placeholder "${pe.key}": ${pe.reason}\n`, "red", err));
+      }
+      return EXIT.VALIDATION;
+    }
+    // Orphan check per template (schema declares something not detected here).
+    const orphans = findOrphans(schema, cascade.placeholders, cascade.detected_schema_keys);
+    if (orphans.length > 0) {
+      for (const oo of orphans) {
+        err.write(paint(`error: bundle entry ${i} "${o.template}" schema declares "${oo.key}" but no matching phrase was detected by tier '${cascade.tier}'.\n`, "red", err));
+      }
+      return EXIT.VALIDATION;
+    }
+    entries.push({ output: o.output, input, schema, cascade });
+  }
+
+  // Phase 2: union placeholders by key. Q3.3 locked: union semantics —
+  // a key declared/detected in any template applies to all. First
+  // occurrence's metadata wins (required, default, type, format, etc.);
+  // a per-template later occurrence may have richer aliases but we keep
+  // the first canonical entry.
+  const unionPlaceholders = [];
+  const seenKeys = new Set();
+  for (const e of entries) {
+    for (const p of e.cascade.placeholders) {
+      if (seenKeys.has(p.key)) continue;
+      seenKeys.add(p.key);
+      unionPlaceholders.push(p);
+    }
+  }
+
+  // Phase 3: shared value resolution + footgun guard.
+  const { resolved, missing, sources } = await resolveValues(unionPlaceholders, opts, paramsObj);
+  const declaredKeys = new Set(unionPlaceholders.map((p) => p.key));
+  const unusedFlags = Object.keys(opts.paramFlags).filter((k) => !declaredKeys.has(k));
+  for (const u of unusedFlags) {
+    err.write(paint(`warning: flag --${u.replace(/_/g, "-")} did not match any placeholder in any bundle template (possible typo?)\n`, "yellow", err));
+  }
+  if (missing.length > 0) {
+    printMissing(missing, err);
+    return EXIT.VALIDATION;
+  }
+
+  // v2 #5: parties.json refs resolve across the union before typed
+  // normalization (same order as cmdDraft / cmdValidate).
+  const refCheck = resolveRefs(resolved, sources, parties);
+  if (!refCheck.ok) {
+    for (const re of refCheck.errors) {
+      err.write(paint(`error: parties reference failed for "${re.key}": ${re.message}\n`, "red", err));
+    }
+    return EXIT.VALIDATION;
+  }
+
+  // Phase 4: typed-parameter + computed pipelines (same as cmdDraft).
+  const typeCheck = normalizeTypedValues(unionPlaceholders, resolved);
+  if (!typeCheck.ok) {
+    for (const te of typeCheck.errors) {
+      err.write(paint(`error: type validation failed for "${te.key}": ${te.message}\n`, "red", err));
+    }
+    return EXIT.VALIDATION;
+  }
+  const computeCheck = computeValues(unionPlaceholders, resolved);
+  if (!computeCheck.ok) {
+    for (const ce of computeCheck.errors) {
+      err.write(paint(`error: computed value failed for "${ce.key}": ${ce.message}\n`, "red", err));
+    }
+    return EXIT.VALIDATION;
+  }
+
+  // Phase 5: substitute per template + write. Q3.2: any write failure
+  // exits with EXIT.IO; earlier successful writes are NOT rolled back
+  // (atomicity at the filesystem is best-effort).
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const outputText = substitute(e.input.body, e.cascade.placeholders, resolved, e.cascade.tier);
+    try {
+      // For .docx input with .docx output: round-trip via substituteDocxXml.
+      if (e.input.kind === "docx" && extname(e.output) === ".docx") {
+        const { xml: newXml, warnings: dw } = substituteDocxXml(
+          e.input.docxXml, e.cascade.placeholders, resolved, e.cascade.tier
+        );
+        if (dw.length) for (const w of dw) err.write(paint(`warning (entry ${i}): ${w}\n`, "yellow", err));
+        const buf = await writeDocxBuffer(e.input.path, newXml);
+        writeFileSync(e.output, buf);
+      } else {
+        writeFileSync(e.output, outputText, "utf8");
+      }
+    } catch (writeErr) {
+      err.write(paint(`error: bundle entry ${i} could not write ${e.output}: ${writeErr.message}\n`, "red", err));
+      return EXIT.IO;
+    }
+  }
+
+  if (!opts.silent && !opts.json) {
+    err.write(paint(`ok: wrote ${entries.length} document(s) — ${entries.map(e => e.output).join(", ")}\n`, "green", err));
+  }
+  if (opts.json) {
+    out.write(JSON.stringify({
+      ok: true,
+      outputs: entries.map(e => ({ template: e.input.path, output: e.output, tier: e.cascade.tier })),
+      resolved_keys: Object.keys(resolved),
+      sources,
+    }, null, 2) + "\n");
+  }
+  return EXIT.OK;
+}
+
 function describeInput(input) {
   if (input.path) return input.path;
   if (input.kind === "text") return "stdin";
@@ -2452,6 +2802,33 @@ export async function main(argv, io = {}) {
     return await runCheckLlm(envObj, out, err, { fetcher });
   }
 
+  // v2 #6: bundle mode. `--bundle PATH` reads a bundle definition and
+  // orchestrates filling each entry's template with shared parameters.
+  // In bundle mode, no positional template arg is required (the bundle
+  // declares them).
+  if (opts.bundle) {
+    if (opts.positional.length > 0) {
+      err.write(paint(`error: --bundle does not take a positional template arg (the bundle declares them)\n`, "red", err));
+      return EXIT.IO;
+    }
+    let bundle, paramsObj, envObj, parties;
+    try {
+      bundle = loadBundle(opts.bundle);
+      paramsObj = loadParamsFile(opts.params);
+      envObj = effectiveEnv(cwd, processEnv);
+      parties = loadParties(opts.parties || null);
+    } catch (e) {
+      err.write(paint(`error: ${e.message}\n`, "red", err));
+      return e.exitCode || EXIT.IO;
+    }
+    try {
+      return await cmdBundle(opts, bundle, paramsObj, envObj, { fetcher, out, err, spawner, stdinReader, parties });
+    } catch (e) {
+      err.write(paint(`error: ${e.message}\n`, "red", err));
+      return e.exitCode || EXIT.IO;
+    }
+  }
+
   if (opts.positional.length === 0) {
     err.write(paint(`error: no template given\n`, "red", err));
     err.write(`run \`draft --help\` for usage.\n`);
@@ -2462,12 +2839,13 @@ export async function main(argv, io = {}) {
     return EXIT.IO;
   }
 
-  let input, schema, paramsObj, envObj;
+  let input, schema, paramsObj, envObj, parties;
   try {
     input = await resolveInput(opts.positional[0], { spawner, stdinReader });
     schema = loadSchema(input.path);
     paramsObj = loadParamsFile(opts.params);
     envObj = effectiveEnv(cwd, processEnv);
+    parties = loadParties(opts.parties || null);
   } catch (e) {
     err.write(paint(`error: ${e.message}\n`, "red", err));
     return e.exitCode || EXIT.IO;
@@ -2478,9 +2856,9 @@ export async function main(argv, io = {}) {
       return await cmdListPlaceholders(opts, input, schema, envObj, { fetcher, out, err });
     }
     if (opts.validate) {
-      return await cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err });
+      return await cmdValidate(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties });
     }
-    return await cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err });
+    return await cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher, out, err, parties });
   } catch (e) {
     err.write(paint(`error: ${e.message}\n`, "red", err));
     return e.exitCode || EXIT.IO;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drbaher/draft-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Fill placeholders in a legal-document template with parameter values. Part of the contract-operations suite.",
   "type": "module",
   "bin": {