@drbaher/draft-cli 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,102 @@ 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.5.0 — 2026-05-16
+
+### Added
+
+- **Positional addressing** for same-text placeholders with different
+  semantic roles. Long-form schema entries can declare a `positions`
+  array; each position gets its own canonical key (via `role`), so the
+  CLI uses standard `--<role>` flags. Validated against the YC SAFE
+  `$[_____________] × 2` case (valuation cap vs. purchase amount).
+  ```json
+  "blank": {
+    "aliases": ["_____________"],
+    "type": "money", "currency": "USD",
+    "positions": [
+      { "role": "valuation_cap" },
+      { "role": "purchase_amount" }
+    ]
+  }
+  ```
+  ```sh
+  draft safe.docx \
+    --valuation-cap 5000000 \
+    --purchase-amount 100000
+  ```
+  Decisions locked (V2_BRIEFS_REMAINING Q1.1–Q1.3):
+  - **Q1.1 Index base**: schema positions are 0-indexed internally;
+    the CLI uses role names, not numeric indices.
+  - **Q1.2 Length mismatch**: schema declares N positions but
+    detection finds M ≠ N occurrences → hard error (exit 4).
+  - **Q1.3 Bare-key CLI**: a `--<role>` flag targets its specific
+    position; values still flow through `--params` JSON or
+    `--interactive` normally.
+
+### Constraints
+
+- Positional addressing only works at tier T1 (bracket) and T2
+  (mustache) — those tiers carry per-hit byte indices needed for
+  position-specific substitution. T3 (docx-highlight), T4 (heuristic),
+  T5 (LLM) raise a positional error if a positional schema entry's
+  aliases are matched by them. `.docx` templates with `[X]` brackets
+  that fire T1 still work; `.docx` templates that rely on T3 highlights
+  for the same alias do not.
+
+### Schema-contract change
+
+`PARAM_SCHEMA.md` §5 gains a "Positional addressing" subsection. Long-
+form entries can now include a `positions` array; short form is
+unchanged. Forward-compatible with v0.4.x readers — they'll ignore the
+unknown field and treat the entry as a regular non-positional
+placeholder (which means the first detected occurrence wins for
+substitution, and ambiguity is unresolved).
+
+## 0.4.0 — 2026-05-16
+
+### Added
+
+- **Computed placeholders.** Long-form schema entries can declare a
+  `computed` block referencing another key:
+  ```json
+  "term_end": {
+    "aliases": ["Term End"],
+    "type": "date",
+    "format": "MMMM d, yyyy",
+    "computed": { "from": "effective_date", "op": "+", "value": "2 years" }
+  }
+  ```
+  At substitution time, if no value was supplied via CLI / `--params`
+  / interactive / default, the computed entry's value is derived from
+  the `from` placeholder. Explicit CLI / `--params` values still win —
+  computed only fills the gap. Q2.1 locked: expression syntax lives
+  in the schema only, not in template text — keeps T1 detection
+  unchanged. Q2.2 locked: v0.4.0 supports date arithmetic only
+  (`+` / `-` with `<n> day|week|month|year[s]` durations). Money
+  math and string concat deferred to a future release.
+- **Schema-time cycle detection.** `parseSchema` throws if any
+  `computed.from` chain revisits a key (e.g. `a → b → a`), or if
+  `computed.from` references a key that doesn't exist in the same
+  schema. Catches misconfiguration before substitution starts.
+- **Orphan-check exemption.** Schema entries that are referenced only
+  as another entry's `computed.from` source (and never appear as
+  detected aliases in the template) are no longer reported as
+  orphans. They're "feeders" — declared so a computed entry can
+  reference them, even though the template doesn't show them.
+- **New public API:** `parseDuration(raw)`, `addDuration(date, op, dur)`,
+  `computeValues(placeholders, resolved)`.
+
+### Schema-contract change
+
+`PARAM_SCHEMA.md` §5 gains a "Computed placeholders" section. Long-
+form entries can now include a `computed: { from, op, value }` block;
+short form is unchanged. v0.4.0 schemas are forward-compatible with
+v0.3.x readers (which will silently ignore the `computed` field as
+unrecognized long-form metadata, treating the entry as a regular
+placeholder — but then the user has to supply a value, since v0.3.x
+won't compute one).
+
 ## 0.3.2 — 2026-05-16
 
 ### Fixed
@@ -219,22 +315,25 @@ suite ([cli.drbaher.com](https://cli.drbaher.com)).
   that contains at least one letter. False positives are filtered with
   the schema file; false negatives in this domain are higher-cost.
 
-## Deferred (v2 candidates)
-
-- **`.docx` output round-trip.** v1 writes plain markdown even from a
-  `.docx` input. Re-writing back into a `.docx` (preserving styles,
-  numbering, and run formatting) is a separate problem.
-- **Computed placeholders** (`[Effective Date + 2 years]`). The long-form
-  schema reserves a future `"computed"` field.
-- **Typed parameters** (`party`, `date`, `money` with format validation).
-  Schema reserves a future `"type"` field.
-- **LLM-assisted parameter inference from a deal description.** v1's T5
-  only suggests placeholders from template text — not from external prose
-  describing the deal.
-- **Cross-template parameter registry** (`parties.json` remembering
-  addresses, e-signature contacts, etc.). Additive — would layer
-  underneath `--params` in precedence.
-- **Multi-document bundles** (MSA + SOW sharing parameters in one call).
-  v1 is one document per invocation.
+## Deferred (post-v0.4.0 candidates)
+
+Three of the original seven v1 "Deferred" entries shipped in v0.2.0,
+v0.3.2, and v0.4.0 (see entries above). The four remaining items are
+the next chunk of design work, with briefs in `V2_BRIEFS_REMAINING.md`:
+
+- **Positional addressing.** Disambiguate same-text placeholders by
+  index in the schema. The validated case: YC SAFE has
+  `$[_____________]` twice — once for the valuation cap, once for
+  the purchase amount. Smallest of the four (~150 LOC).
+- **Cross-template `parties.json` registry.** Declare parties once
+  with `ref:parties.<key>.<field>` references from schemas. Eliminates
+  duplicating party metadata across every template (~250 LOC).
+- **Multi-document bundles.** Resolve placeholders once and emit
+  multiple documents in one call (MSA + Order Form + DPA with shared
+  parameter values) (~250 LOC).
+- **LLM inference from a deal description.** `--from-deal <path>`
+  reads free-form deal text and asks the T5 LLM provider to fill the
+  schema's parameters. Inverse of the existing T5 detection (~250 LOC).
 - **`.docx` highlight detection beyond yellow/green/cyan/magenta.** v1
-  ignores other colors (black/white/none) by design.
+  ignores other colors (black/white/none) by design. Backlog, not in
+  V2_BRIEFS_REMAINING (low priority).

package/PARAM_SCHEMA.md

@@ -270,6 +270,124 @@ Programmatic API for drivers: `parseDateValue`, `formatDateValue`,
 `parseMoneyValue`, `formatMoneyValue`, `normalizeTypedValue`,
 `normalizeTypedValues`.
 
+### Computed placeholders (v0.4.0, opt-in)
+
+Long-form entries can declare a `computed` block referencing another
+key in the same schema. At substitution time, if no value was
+supplied via CLI / `--params` / interactive / default, the computed
+entry's value is derived from the `from` placeholder via simple
+date arithmetic. Explicit user-supplied values still win — computed
+only fills the gap.
+
+```json
+{
+  "_meta": { "schema_version": 1 },
+  "effective_date": {
+    "aliases": ["Effective Date"],
+    "type": "date", "format": "MMMM d, yyyy"
+  },
+  "term_end": {
+    "aliases": ["Term End"],
+    "type": "date", "format": "MMMM d, yyyy",
+    "computed": { "from": "effective_date", "op": "+", "value": "2 years" }
+  }
+}
+```
+
+| Field   | Type     | Required | Notes |
+| ------- | -------- | -------- | ----- |
+| `from`  | string   | yes      | Key of another entry in the same schema. Schema validation rejects unknown references. |
+| `op`    | `"+"`/`"-"` | yes   | Add or subtract the duration from the `from` value. |
+| `value` | string   | yes      | Duration in `<n> <unit>` form, where `<unit>` is `day`, `week`, `month`, or `year` (singular or plural; case-insensitive). |
+
+**Q2.1 locked:** Expression syntax lives in the schema, **not** in
+template text. T1 bracket detection treats `[Term End]` as an
+ordinary placeholder; the schema-level `computed` block decides how
+its value is derived.
+
+**Q2.2 locked:** v0.4.0 supports **date arithmetic only**. Money
+math (`+ 10%`) and string concat (`Party A + " Inc."`) are deferred
+to a future release once the date-arithmetic design is proven against
+real templates.
+
+**Resolution order:** value resolution → typed-parameter normalization
+(§ above) → computed-placeholder evaluation → substitution.
+
+**Cycle and reference safety:** `parseSchema` walks every
+`computed.from` chain and throws at load time if a chain revisits a
+key (e.g. `a → b → a`) or references a non-existent key. Caught
+before substitution.
+
+**Orphan-check exemption:** an entry that's referenced only as
+another entry's `computed.from` (never appears in the template) is
+**not** an orphan. It's a feeder used solely for computation.
+
+**Format inheritance:** the computed entry's `format` field is used
+to render the result. If the computed entry doesn't declare `format`,
+the default `MMMM d, yyyy` applies. The `from` entry's `format` is
+used for parsing the source value (since by then it's normalized to
+that format).
+
+Programmatic API for drivers: `parseDuration`, `addDuration`,
+`computeValues`.
+
+### Positional addressing (v0.5.0, opt-in)
+
+Some templates have the same placeholder text appearing multiple times
+with *different* semantic roles. The validated YC SAFE case:
+`$[_____________]` appears twice — once as valuation cap, once as
+purchase amount. Long-form entries can declare a `positions` array
+that splits each occurrence into its own canonical-keyed placeholder.
+
+```json
+{
+  "_meta": { "schema_version": 1 },
+  "blank": {
+    "aliases": ["_____________"],
+    "type": "money", "currency": "USD",
+    "positions": [
+      { "role": "valuation_cap" },
+      { "role": "purchase_amount" }
+    ]
+  }
+}
+```
+
+CLI uses standard `--<role>` flags (no special `@N` grammar):
+
+```sh
+draft safe.docx --valuation-cap 5000000 --purchase-amount 100000
+```
+
+**Q1.1 locked:** index base is 0 internally; the CLI uses role names,
+not numeric indices.
+
+**Q1.2 locked:** count mismatch (schema declares N positions but
+detection finds M ≠ N occurrences of the alias) is a **hard error**
+(exit 4). The schema and the template are out of sync; silently filling
+or trimming hides the bug.
+
+**Q1.3 locked:** there is no bare-key CLI variant (`--<parent-key>
+VALUE` with no role). The CLI uses role-named flags. Bare `--<role>`
+targets that role's position; values can also come from `--params`
+JSON keyed by role, or `--interactive`.
+
+**Tier constraint:** positional addressing only works at T1 (bracket)
+or T2 (mustache). T3/T4/T5 detection paths don't carry per-hit byte
+indices needed for position-specific substitution; if a positional
+schema entry's aliases are matched by those tiers, the command exits 4
+with a clear error.
+
+**Validation:** at schema parse time, positions must be a non-empty
+array of `{role: string}` objects; roles must be valid snake_case keys
+and unique within the entry.
+
+Programmatic API: positions flow through detection and resolution as
+normal `Placeholder` objects with `position_parent` (parent schema key)
+and `position_index` (0-based) fields. `substitute` switches to
+byte-index substitution for these, which `substituteDocxXml` does not
+currently support.
+
 ### 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.3.2";
+export const VERSION = "0.5.0";
 
 // ─── EXIT CODES ─────────────────────────────────────────────────────────────
 /**
@@ -914,6 +914,66 @@ export function parseSchema(parsed, sourceLabel = "<schema>") {
         e.exitCode = EXIT.IO;
         throw e;
       }
+      // v2 #7: positional addressing. Optional `positions` array; each
+      // element declares a role (its own canonical key) for the Nth detected
+      // occurrence of this entry's aliases. Roles must be valid keys and
+      // unique within the entry.
+      let positions = null;
+      if (v.positions !== undefined) {
+        if (!Array.isArray(v.positions) || v.positions.length === 0) {
+          const e = new Error(`${sourceLabel}: long-form entry '${k}' positions must be a non-empty array`);
+          e.exitCode = EXIT.IO;
+          throw e;
+        }
+        const roleSet = new Set();
+        positions = [];
+        for (let pi = 0; pi < v.positions.length; pi++) {
+          const pos = v.positions[pi];
+          if (!pos || typeof pos !== "object" || Array.isArray(pos)) {
+            const e = new Error(`${sourceLabel}: '${k}'.positions[${pi}] must be an object with a 'role' string`);
+            e.exitCode = EXIT.IO;
+            throw e;
+          }
+          if (typeof pos.role !== "string" || !validKey(pos.role)) {
+            const e = new Error(`${sourceLabel}: '${k}'.positions[${pi}].role must be a valid snake_case key`);
+            e.exitCode = EXIT.IO;
+            throw e;
+          }
+          if (roleSet.has(pos.role)) {
+            const e = new Error(`${sourceLabel}: '${k}'.positions has duplicate role '${pos.role}'`);
+            e.exitCode = EXIT.IO;
+            throw e;
+          }
+          roleSet.add(pos.role);
+          positions.push({ role: pos.role });
+        }
+      }
+      // v2 #2: computed placeholders. Optional `computed` block on long-form
+      // entries; { from: <other-key>, op: "+"|"-", value: "<n> <unit>" }.
+      let computed = null;
+      if (v.computed !== undefined) {
+        if (!v.computed || typeof v.computed !== "object" || Array.isArray(v.computed)) {
+          const e = new Error(`${sourceLabel}: long-form entry '${k}' has invalid 'computed' (must be an object)`);
+          e.exitCode = EXIT.IO;
+          throw e;
+        }
+        if (typeof v.computed.from !== "string") {
+          const e = new Error(`${sourceLabel}: long-form entry '${k}' computed.from must be a string (key of another schema entry)`);
+          e.exitCode = EXIT.IO;
+          throw e;
+        }
+        if (v.computed.op !== "+" && v.computed.op !== "-") {
+          const e = new Error(`${sourceLabel}: long-form entry '${k}' computed.op must be "+" or "-"`);
+          e.exitCode = EXIT.IO;
+          throw e;
+        }
+        if (typeof v.computed.value !== "string") {
+          const e = new Error(`${sourceLabel}: long-form entry '${k}' computed.value must be a string (duration like "2 years")`);
+          e.exitCode = EXIT.IO;
+          throw e;
+        }
+        computed = { from: v.computed.from, op: v.computed.op, value: v.computed.value };
+      }
       entries[k] = {
         aliases: v.aliases.slice(),
         required: v.required !== false,
@@ -924,6 +984,8 @@ export function parseSchema(parsed, sourceLabel = "<schema>") {
         type: typeof v.type === "string" ? v.type : null,
         format: typeof v.format === "string" ? v.format : null,
         currency: typeof v.currency === "string" ? v.currency : null,
+        computed,
+        positions,
       };
     } else {
       if (!Array.isArray(v)) {
@@ -931,7 +993,30 @@ export function parseSchema(parsed, sourceLabel = "<schema>") {
         e.exitCode = EXIT.IO;
         throw e;
       }
-      entries[k] = { aliases: v.slice(), required: true, default: null, type: null, format: null, currency: null };
+      entries[k] = { aliases: v.slice(), required: true, default: null, type: null, format: null, currency: null, computed: null, positions: null };
+    }
+  }
+  // v2 #2: validate computed references (point to existing keys; no cycles).
+  for (const [key, entry] of Object.entries(entries)) {
+    if (!entry.computed) continue;
+    if (!entries[entry.computed.from]) {
+      const e = new Error(`${sourceLabel}: '${key}'.computed.from = "${entry.computed.from}" does not match any other key in this schema`);
+      e.exitCode = EXIT.IO;
+      throw e;
+    }
+    // Walk the computed.from chain from this key; bail if we revisit.
+    const visited = [key];
+    let cursor = entry.computed.from;
+    while (cursor) {
+      if (visited.includes(cursor)) {
+        const e = new Error(`${sourceLabel}: computed cycle detected: ${[...visited, cursor].join(" → ")}`);
+        e.exitCode = EXIT.IO;
+        throw e;
+      }
+      visited.push(cursor);
+      const next = entries[cursor];
+      if (!next || !next.computed) break;
+      cursor = next.computed.from;
     }
   }
   return { form: long ? "long" : "short", entries };
@@ -1075,6 +1160,8 @@ function assemble(tier, hits, schema, warnings, fromLlm = false) {
         type: resolved.type,
         format: resolved.format,
         currency: resolved.currency,
+        computed: resolved.computed,
+        positions: resolved.positions,
         hits: [],
       });
     }
@@ -1082,7 +1169,52 @@ function assemble(tier, hits, schema, warnings, fromLlm = false) {
     entry.occurrences += 1;
     entry.hits.push(h);
   }
-  return { tier, placeholders: [...byKey.values()], warnings, unmapped };
+  // v2 #7: expand positional entries. Each detected occurrence becomes a
+  // separate role-keyed placeholder. Count mismatch → positional_errors;
+  // tier T3/T4/T5 (no per-hit index) → positional_errors (not supported).
+  const placeholders = [];
+  const positional_errors = [];
+  const detected_schema_keys = [...byKey.keys()];
+  for (const p of byKey.values()) {
+    if (!p.positions) {
+      placeholders.push(p);
+      continue;
+    }
+    if (tier !== "bracket" && tier !== "mustache") {
+      positional_errors.push({
+        key: p.key,
+        reason: `tier '${tier}' does not carry per-hit index info; positional addressing requires T1 (bracket) or T2 (mustache) detection`,
+      });
+      continue;
+    }
+    if (p.hits.length !== p.positions.length) {
+      positional_errors.push({
+        key: p.key,
+        reason: `schema declares ${p.positions.length} position(s) but detected ${p.hits.length} occurrence(s) of "${p.aliases[0] || p.key}"`,
+      });
+      continue;
+    }
+    for (let i = 0; i < p.positions.length; i++) {
+      placeholders.push({
+        key: p.positions[i].role,
+        first_seen_as: p.hits[i].inner,
+        occurrences: 1,
+        tier,
+        required: true,
+        default: null,
+        aliases: p.aliases.slice(),
+        type: p.type,
+        format: p.format,
+        currency: p.currency,
+        computed: null,
+        positions: null, // expanded; no further re-expansion
+        hits: [p.hits[i]],
+        position_parent: p.key,
+        position_index: i,
+      });
+    }
+  }
+  return { tier, placeholders, warnings, unmapped, positional_errors, detected_schema_keys };
 }
 
 function resolveKey(hit, schema, fromLlm) {
@@ -1097,6 +1229,8 @@ function resolveKey(hit, schema, fromLlm) {
           type: entry.type || null,
           format: entry.format || null,
           currency: entry.currency || null,
+          computed: entry.computed || null,
+          positions: entry.positions || null,
         };
       }
     }
@@ -1104,7 +1238,7 @@ function resolveKey(hit, schema, fromLlm) {
   }
   const key = fromLlm && hit.suggested_key ? hit.suggested_key : canonicalKey(hit.inner);
   if (!validKey(key)) return null;
-  return { key, required: true, default: null, aliases: [hit.inner], type: null, format: null, currency: null };
+  return { key, required: true, default: null, aliases: [hit.inner], type: null, format: null, currency: null, computed: null, positions: null };
 }
 
 // ─── VALUE RESOLUTION (CLI > JSON > prompt > default) ───────────────────────
@@ -1177,7 +1311,9 @@ export async function resolveValues(placeholders, opts, paramsObj, { prompter =
       sources[p.key] = "default";
       continue;
     }
-    if (p.required) missing.push(p);
+    // v2 #2: computed placeholders auto-resolve later via `computeValues`.
+    // Don't count them as missing here even though no source supplied a value.
+    if (p.required && !p.computed) missing.push(p);
   }
   return { resolved, missing, sources };
 }
@@ -1255,6 +1391,46 @@ export function formatDateValue(date, format) {
   });
 }
 
+/**
+ * Parse a duration string for computed placeholders (v2 #2).
+ * Accepts `<n> <unit>` where unit is one of `day | week | month | year`
+ * (singular or plural). Returns an object with the unit as plural key.
+ * Returns `null` on parse failure.
+ *
+ * @param {string} raw
+ * @returns {{ days?: number, weeks?: number, months?: number, years?: number } | null}
+ */
+export function parseDuration(raw) {
+  const m = /^(\d+)\s+(day|week|month|year)s?$/i.exec(String(raw).trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  if (!isFinite(n) || n < 0) return null;
+  const unit = m[2].toLowerCase();
+  return { [`${unit}s`]: n };
+}
+
+/**
+ * Add or subtract a duration from a Date. Uses UTC field manipulation
+ * via `setUTC*` methods, so day/month/year overflow follows JavaScript's
+ * default behavior (e.g. Jan 31 + 1 month = Mar 3, not Feb 28). For
+ * legal-doc use cases ("2 years from effective date") this is the
+ * expected behavior; anniversary dates are unambiguous.
+ *
+ * @param {Date} date
+ * @param {"+"|"-"} op
+ * @param {{ days?: number, weeks?: number, months?: number, years?: number }} dur
+ * @returns {Date}
+ */
+export function addDuration(date, op, dur) {
+  const sign = op === "-" ? -1 : 1;
+  const d = new Date(date.getTime());
+  if (dur.years) d.setUTCFullYear(d.getUTCFullYear() + sign * dur.years);
+  if (dur.months) d.setUTCMonth(d.getUTCMonth() + sign * dur.months);
+  if (dur.weeks) d.setUTCDate(d.getUTCDate() + sign * dur.weeks * 7);
+  if (dur.days) d.setUTCDate(d.getUTCDate() + sign * dur.days);
+  return d;
+}
+
 /**
  * Parse a money input. Accepts `$5,000`, `5000.50`, `$5M`, `2.5K`, etc.
  * Handles `K`/`M`/`B` suffixes (case-insensitive). Returns the value in
@@ -1394,6 +1570,91 @@ export function normalizeTypedValues(placeholders, resolved) {
   return { ok: errors.length === 0, errors, normalized };
 }
 
+// ─── COMPUTED PLACEHOLDERS (v2 #2) ──────────────────────────────────────────
+// Schema entries can declare a `computed` block referencing another key in
+// the same schema:
+//
+//   "term_end": { "aliases": ["Term End"], "type": "date",
+//                 "computed": { "from": "effective_date", "op": "+", "value": "2 years" } }
+//
+// At substitution time, if no value was supplied via CLI/--params/interactive/
+// default, the computed entry's value is derived from its `from` placeholder.
+// CLI/--params explicit values still win — computed only fills the gap.
+//
+// Cycles in `from` references are detected at parseSchema time. Missing-`from`
+// errors and bad-duration errors surface at compute time with a per-key
+// message; like typed-param errors, all errors are collected before returning
+// so the user sees every failure at once.
+
+/**
+ * Run computed-placeholder evaluation on already-resolved values. Mutates
+ * `resolved` in place with computed values for any placeholder that has a
+ * `computed` block and no existing value. Iterative — handles chains
+ * (B from A, C from B) without an explicit topological sort.
+ *
+ * @param {Placeholder[]} placeholders
+ * @param {Object<string,string>} resolved
+ * @returns {{ ok: boolean, errors: Array<{ key: string, message: string }>, computed: Object<string,{from: string, op: string, value: string, to: string}> }}
+ */
+export function computeValues(placeholders, resolved) {
+  const errors = [];
+  const computed = {};
+  const pending = placeholders.filter(
+    (p) => p.computed && resolved[p.key] === undefined
+  );
+  if (pending.length === 0) return { ok: true, errors: [], computed: {} };
+
+  let progress = true;
+  while (progress && pending.length > 0) {
+    progress = false;
+    for (let i = pending.length - 1; i >= 0; i--) {
+      const p = pending[i];
+      const fromKey = p.computed.from;
+      const fromValue = resolved[fromKey];
+      if (fromValue === undefined) continue;
+      try {
+        const result = computeOneValue(p, fromValue);
+        resolved[p.key] = result;
+        computed[p.key] = { from: fromKey, op: p.computed.op, value: p.computed.value, to: result };
+        pending.splice(i, 1);
+        progress = true;
+      } catch (e) {
+        errors.push({ key: p.key, message: e.message });
+        pending.splice(i, 1);
+      }
+    }
+  }
+  for (const p of pending) {
+    errors.push({
+      key: p.key,
+      message: `cannot compute: depends on "${p.computed.from}" which is unresolved`,
+    });
+  }
+  return { ok: errors.length === 0, errors, computed };
+}
+
+function computeOneValue(p, fromValue) {
+  // v2: dates only. Future expansions (money math, string concat) would
+  // dispatch on placeholder type here.
+  const date = parseDateValue(fromValue);
+  if (!date) {
+    throw new Error(
+      `cannot parse "${fromValue}" as a date (from "${p.computed.from}"). ` +
+      `Computed placeholders need a date-shaped source value.`
+    );
+  }
+  const dur = parseDuration(p.computed.value);
+  if (!dur) {
+    throw new Error(
+      `cannot parse duration "${p.computed.value}". Expected ` +
+      `"<n> <unit>" where unit is day, week, month, or year (singular ` +
+      `or plural).`
+    );
+  }
+  const result = addDuration(date, p.computed.op, dur);
+  return formatDateValue(result, p.format || "MMMM d, yyyy");
+}
+
 async function nodePrompter(placeholder) {
   if (!process.stdin.isTTY) return null;
   const rl = createInterface({ input: process.stdin, output: process.stderr });
@@ -1413,12 +1674,30 @@ async function nodePrompter(placeholder) {
  * @param {Placeholder[]} placeholders
  * @returns {Array<{key: string, aliases: string[]}>}
  */
-export function findOrphans(schema, placeholders) {
+export function findOrphans(schema, placeholders, detectedSchemaKeys = null) {
   if (!schema) return [];
-  const present = new Set(placeholders.map((p) => p.key));
+  // v2 #7: for positional entries we check `detectedSchemaKeys` (the
+  // pre-expansion key set) since the placeholders list shows role keys,
+  // not the parent positional key. When detectedSchemaKeys is not given
+  // (older callers / no schema-expansion path), fall back to the
+  // placeholders list — same behavior as before v0.5.0.
+  const presentForPositional = detectedSchemaKeys
+    ? new Set(detectedSchemaKeys)
+    : new Set(placeholders.map((p) => p.key));
+  const presentForRegular = new Set(placeholders.map((p) => p.key));
+  // v2 #2: an entry that another entry's `computed.from` points at is
+  // legitimately not in the template — it's a "feeder" used only for
+  // computation. Exempt those from the orphan check.
+  const computedFromTargets = new Set();
+  for (const entry of Object.values(schema.entries)) {
+    if (entry.computed && entry.computed.from) computedFromTargets.add(entry.computed.from);
+  }
   const orphans = [];
   for (const [key, entry] of Object.entries(schema.entries)) {
-    if (!present.has(key)) orphans.push({ key, aliases: entry.aliases.slice() });
+    if (computedFromTargets.has(key)) continue;
+    const present = entry.positions ? presentForPositional : presentForRegular;
+    if (present.has(key)) continue;
+    orphans.push({ key, aliases: entry.aliases.slice() });
   }
   return orphans;
 }
@@ -1437,8 +1716,30 @@ export function findOrphans(schema, placeholders) {
  * @returns {string} the substituted body.
  */
 export function substitute(body, placeholders, values, tier) {
+  // v2 #7: positional placeholders (`position_index !== undefined`) substitute
+  // at a specific byte index, not by global replace. Collect them first,
+  // apply in reverse-index order so earlier hits' indices stay stable. Then
+  // the remaining (non-positional) placeholders use the original
+  // replaceAll/regex logic, which is safe because positional hits all share
+  // the same alias text — and after the index-based substitution, only the
+  // exact bytes at each position have been replaced.
   let out = body;
+  const positionalSubs = [];
   for (const p of placeholders) {
+    if (p.position_index === undefined) continue;
+    const v = values[p.key];
+    if (v === undefined) continue;
+    for (const h of p.hits) {
+      if (typeof h.index !== "number") continue;
+      positionalSubs.push({ index: h.index, length: h.match.length, value: v });
+    }
+  }
+  positionalSubs.sort((a, b) => b.index - a.index);
+  for (const s of positionalSubs) {
+    out = out.slice(0, s.index) + s.value + out.slice(s.index + s.length);
+  }
+  for (const p of placeholders) {
+    if (p.position_index !== undefined) continue; // already handled above
     const v = values[p.key];
     if (v === undefined) continue;
     for (const h of p.hits) {
@@ -1617,7 +1918,14 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
     err.write(paint("error: no placeholders detected by any tier\n", "red", err));
     return EXIT.VALIDATION;
   }
-  const orphans = findOrphans(schema, result.placeholders);
+  // v2 #7: positional addressing errors (count mismatch, unsupported tier).
+  if (result.positional_errors && result.positional_errors.length > 0) {
+    for (const pe of result.positional_errors) {
+      err.write(paint(`error: positional placeholder "${pe.key}": ${pe.reason}\n`, "red", err));
+    }
+    return EXIT.VALIDATION;
+  }
+  const orphans = findOrphans(schema, result.placeholders, result.detected_schema_keys);
   if (orphans.length > 0) {
     for (const o of orphans) {
       err.write(paint(`error: schema declares "${o.key}" with aliases [${o.aliases.map(a => `"${a}"`).join(",")}], but no matching phrase was detected by tier '${result.tier}'.\n`, "red", err));
@@ -1647,6 +1955,20 @@ export async function cmdValidate(opts, input, schema, paramsObj, envObj, { fetc
     }
     return EXIT.VALIDATION;
   }
+  // v2 #2: computed-placeholder validation (same gate as cmdDraft).
+  const computeCheck = computeValues(result.placeholders, 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));
+    }
+    if (opts.json) {
+      out.write(JSON.stringify({
+        ok: false,
+        computed_errors: computeCheck.errors.map(({ key, message }) => ({ key, message })),
+      }, null, 2) + "\n");
+    }
+    return EXIT.VALIDATION;
+  }
   if (opts.json) {
     out.write(JSON.stringify({ ok: true, resolved: Object.keys(resolved), sources }, null, 2) + "\n");
   } else {
@@ -1689,8 +2011,15 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
     }
   }
 
+  // v2 #7: positional addressing errors (count mismatch, unsupported tier).
+  if (result.positional_errors && result.positional_errors.length > 0) {
+    for (const pe of result.positional_errors) {
+      err.write(paint(`error: positional placeholder "${pe.key}": ${pe.reason}\n`, "red", err));
+    }
+    return EXIT.VALIDATION;
+  }
   // Orphan check.
-  const orphans = findOrphans(schema, result.placeholders);
+  const orphans = findOrphans(schema, result.placeholders, result.detected_schema_keys);
   if (orphans.length > 0) {
     for (const o of orphans) {
       err.write(paint(`error: schema declares "${o.key}" with aliases [${o.aliases.map(a => `"${a}"`).join(",")}], but no matching phrase was detected by tier '${result.tier}'.\n`, "red", err));
@@ -1727,6 +2056,19 @@ export async function cmdDraft(opts, input, schema, paramsObj, envObj, { fetcher
     return EXIT.VALIDATION;
   }
 
+  // v2 #2: computed placeholders. Fill any computed entries whose value
+  // wasn't already supplied via CLI / --params / --interactive / default.
+  // Runs after typed normalization so the source values are in canonical
+  // form (e.g. a "date" type is already in the format string before we
+  // parse it back for arithmetic).
+  const computeCheck = computeValues(result.placeholders, 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;
+  }
+
   // Diff mode: print a substitution table and exit without writing output.
   if (opts.diff) {
     if (opts.json) {

package/package.json

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