@geraldmaron/construct 1.0.14 → 1.0.15

package/README.md

@@ -85,6 +85,12 @@ Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competit
 
 Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage).
 
+### Document ingestion fidelity
+
+`construct ingest <file>` extracts text from PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and audio/video. High-fidelity extraction is the default and routes through a [docling](https://github.com/docling-project/docling) Python sidecar (MIT, IBM, donated to LF AI & Data) provisioned via [`uv`](https://github.com/astral-sh/uv); audio and video route through [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp) (Metal-accelerated on macOS).
+
+First run downloads `uv` and creates `.cx/runtime/docling/.venv` (~1.5 GB including PyTorch). Audio requires a system `whisper-cli` binary — `brew install whisper-cpp` on macOS. Pass `--strict` to fail on any extraction info loss; pass `--legacy-extractor` to use the pre-docling regex path. Any silent drops (image-heavy PDFs, scanned pages with low OCR yield) are surfaced as `droppedInfo` in the CLI output.
+
 ## Hard gates
 
 Every code mutation runs through enforcement. No secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places: write-time, commit-time, CI safety net. They can only be bypassed with explicit env vars so every exception leaves an audit trail. [Gates and enforcement](https://geraldmaron.github.io/construct/concepts/gates-and-enforcement).

package/bin/construct

@@ -917,7 +917,7 @@ async function cmdDoctor() {
     }
 
     try {
-      const { recentViolations } = await import('../lib/specialist-contracts-enforce.mjs');
+      const { recentViolations } = await import('../lib/contracts/violation-log.mjs');
       const violations = recentViolations({ windowMs: 24 * 60 * 60 * 1000 });
       const label = violations.length === 0
         ? 'Contract violations (none in last 24h)'
@@ -1598,12 +1598,12 @@ async function cmdHandoffs(args) {
   }
 
   if (sub === 'validate') {
-    const { parseHandoffFile, validateHandoff } = await import('../lib/handoffs/contract.mjs');
+    const { parseHandoffFile, validateHandoffFile } = await import('../lib/handoffs/contract.mjs');
     if (summary.state === 'empty') { info('No handoffs to validate.'); return; }
     let hasErrors = false;
     for (const f of summary.files) {
       const parsed = parseHandoffFile(f.path);
-      const { valid, errors } = validateHandoff(parsed);
+      const { valid, errors } = validateHandoffFile(parsed);
       if (valid) {
         println(`✓ ${f.filename}`);
       } else {

package/commands/build/feature.md

@@ -1,12 +1,6 @@
-<!--
-commands/build/feature.md (Build a feature) implement it end to end, tested and ready to ship
-
-Build a feature: implement it end to end, tested and ready to ship
--->
 ---
 description: "Build a feature: implement it end to end, tested and ready to ship"
 ---
-
 You are Construct. Build the following: $ARGUMENTS
 
 Before writing a line:

package/commands/build/fix.md

@@ -1,12 +1,6 @@
-<!--
-commands/build/fix.md (Fix something broken) reproduce, find the root cause, apply the smallest safe change
-
-Fix something broken: reproduce, find the root cause, apply the smallest safe change
--->
 ---
 description: "Fix something broken: reproduce, find the root cause, apply the smallest safe change"
 ---
-
 You are Construct.
 
 Debugging protocol for: $ARGUMENTS

package/commands/design/access.md

@@ -1,12 +1,6 @@
-<!--
-commands/design/access.md (Accessibility audit) WCAG 2.1 AA, keyboard, screen readers, contrast, motion
-
-Accessibility audit: WCAG 2.1 AA, keyboard, screen readers, contrast, motion
--->
 ---
 description: "Accessibility audit: WCAG 2.1 AA, keyboard, screen readers, contrast, motion"
 ---
-
 You are Construct. Audit: $ARGUMENTS
 
 WCAG 2.1 AA baseline:

package/commands/design/flow.md

@@ -1,12 +1,6 @@
-<!--
-commands/design/flow.md (Map the user flow) entry to success, friction points, jobs-to-be-done
-
-Map the user flow: entry to success, friction points, jobs-to-be-done
--->
 ---
 description: "Map the user flow: entry to success, friction points, jobs-to-be-done"
 ---
-
 You are Construct. Map the user flow for: $ARGUMENTS
 
 Produce:

package/commands/design/ui.md

@@ -1,12 +1,6 @@
-<!--
-commands/design/ui.md (Design or review UI) visual hierarchy, states, interaction model, accessibility baseline
-
-Design or review UI: visual hierarchy, states, interaction model, accessibility baseline
--->
 ---
 description: "Design or review UI: visual hierarchy, states, interaction model, accessibility baseline"
 ---
-
 You are Construct. Design or review the UI for: $ARGUMENTS
 
 Every meaningful UI surface needs:

package/commands/measure/experiment.md

@@ -1,12 +1,6 @@
-<!--
-commands/measure/experiment.md (Design an experiment) hypothesis, test, evidence threshold, go/no-go decision
-
-Design an experiment: hypothesis, test, evidence threshold, go/no-go decision
--->
 ---
 description: "Design an experiment: hypothesis, test, evidence threshold, go/no-go decision"
 ---
-
 You are Construct. Design an experiment for: $ARGUMENTS
 
 Produce:

package/commands/measure/metrics.md

@@ -1,12 +1,6 @@
-<!--
-commands/measure/metrics.md (Define metrics) what to measure, baselines, success thresholds, instrumentation needed
-
-Define metrics: what to measure, baselines, success thresholds, instrumentation needed
--->
 ---
 description: "Define metrics: what to measure, baselines, success thresholds, instrumentation needed"
 ---
-
 You are Construct. Define metrics for: $ARGUMENTS
 
 For each metric:

package/commands/measure/results.md

@@ -1,12 +1,6 @@
-<!--
-commands/measure/results.md (Analyze results) interpret data, separate signal from noise, produce a recommendation
-
-Analyze results: interpret data, separate signal from noise, produce a recommendation
--->
 ---
 description: "Analyze results: interpret data, separate signal from noise, produce a recommendation"
 ---
-
 You are Construct. Analyze: $ARGUMENTS
 
 For each finding:

package/commands/plan/api.md

@@ -1,12 +1,6 @@
-<!--
-commands/plan/api.md (Design an API) contracts, endpoints, error model, data schema
-
-Design an API: contracts, endpoints, error model, data schema
--->
 ---
 description: "Design an API: contracts, endpoints, error model, data schema"
 ---
-
 You are Construct. Design the API for: $ARGUMENTS
 
 Produce:

package/commands/plan/challenge.md

@@ -1,12 +1,6 @@
-<!--
-commands/plan/challenge.md (Challenge a plan) stress-test assumptions, surface failure modes and risks
-
-Challenge a plan: stress-test assumptions, surface failure modes and risks
--->
 ---
 description: "Challenge a plan: stress-test assumptions, surface failure modes and risks"
 ---
-
 You are Construct. Challenge the following: $ARGUMENTS
 
 Challenge in severity order:

package/commands/plan/decide.md

@@ -1,12 +1,6 @@
-<!--
-commands/plan/decide.md (Record a decision) context, options considered, consequences, what it locks in
-
-Record a decision: context, options considered, consequences, what it locks in
--->
 ---
 description: "Record a decision: context, options considered, consequences, what it locks in"
 ---
-
 You are Construct. Document the decision about: $ARGUMENTS
 
 ADR format:

package/commands/plan/feature.md

@@ -1,13 +1,6 @@
-<!--
-commands/plan/feature.md: Plan a feature and turn it into a tracker-linked implementation plan
-
-Produces a structured spec using the canonical Construct plan format, saves it
-to .cx/plans/ as a durable planning artifact linked to the active tracker slice.
--->
 ---
 description: "Plan a feature: produce a structured spec and link it to the active tracker-backed plan"
 ---
-
 You are Construct. Plan the following: $ARGUMENTS
 
 Use the code-backed orchestration policy for routing/escalation decisions; this prompt only defines the plan artifact shape.

package/commands/plan/requirements.md

@@ -1,12 +1,6 @@
-<!--
-commands/plan/requirements.md (Define requirements) what needs to be true for this to be done
-
-Define requirements: what needs to be true for this to be done
--->
 ---
 description: "Define requirements: what needs to be true for this to be done"
 ---
-
 You are Construct. Define requirements for: $ARGUMENTS
 
 Produce:

package/commands/remember/context.md

@@ -1,12 +1,6 @@
-<!--
-commands/remember/context.md (Save project context) update .cx/context.md so the next session picks up where this one left off
-
-Save project context: update .cx/context.md so the next session picks up where this one left off
--->
 ---
 description: "Save project context: update .cx/context.md so the next session picks up where this one left off"
 ---
-
 You are Construct. Save context for: $ARGUMENTS
 
 Update `.cx/context.json` as canonical state and refresh `.cx/context.md` as the readable mirror:

package/commands/remember/handoff.md

@@ -1,12 +1,6 @@
-<!--
-commands/remember/handoff.md (Write a handoff) transfer context so the next session or person can continue without loss
-
-Write a handoff: transfer context so the next session or person can continue without loss
--->
 ---
 description: "Write a handoff: transfer context so the next session or person can continue without loss"
 ---
-
 You are Construct. Write a handoff for: $ARGUMENTS
 
 - CURRENT STATE: what is working, in progress, blocked

package/commands/remember/runbook.md

@@ -1,12 +1,6 @@
-<!--
-commands/remember/runbook.md (Write a runbook) step-by-step procedure for a recurring task or incident
-
-Write a runbook: step-by-step procedure for a recurring task or incident
--->
 ---
 description: "Write a runbook: step-by-step procedure for a recurring task or incident"
 ---
-
 You are Construct. Write a runbook for: $ARGUMENTS
 
 Structure:

package/commands/review/code.md

@@ -1,12 +1,6 @@
-<!--
-commands/review/code.md (Code review) correctness, regressions, security, test coverage
-
-Code review: correctness, regressions, security, test coverage
--->
 ---
 description: "Code review: correctness, regressions, security, test coverage"
 ---
-
 You are Construct. Review: $ARGUMENTS
 
 If no target specified, review all uncommitted changes (`git diff HEAD`).

package/commands/review/quality.md

@@ -1,12 +1,6 @@
-<!--
-commands/review/quality.md (Quality audit) complexity, naming, duplication, dead code, maintainability
-
-Quality audit: complexity, naming, duplication, dead code, maintainability
--->
 ---
 description: "Quality audit: complexity, naming, duplication, dead code, maintainability"
 ---
-
 You are Construct. Audit quality for: $ARGUMENTS
 
 Check:

package/commands/review/security.md

@@ -1,12 +1,6 @@
-<!--
-commands/review/security.md (Security scan) secrets, auth, injection, data exposure, dependency risk
-
-Security scan: secrets, auth, injection, data exposure, dependency risk
--->
 ---
 description: "Security scan: secrets, auth, injection, data exposure, dependency risk"
 ---
-
 You are Construct. Scan: $ARGUMENTS
 
 If no target specified, scan all uncommitted changes.

package/commands/ship/ready.md

@@ -1,12 +1,6 @@
-<!--
-commands/ship/ready.md (Pre-release check) is this ready to ship?
-
-Pre-release check: is this ready to ship?
--->
 ---
 description: "Pre-release check: is this ready to ship?"
 ---
-
 You are Construct. Check if the following is ready: $ARGUMENTS
 
 Check:

package/commands/ship/release.md

@@ -1,12 +1,6 @@
-<!--
-commands/ship/release.md (Release) plan rollout, changelog, rollback, and post-release verification
-
-Release: plan rollout, changelog, rollback, and post-release verification
--->
 ---
 description: "Release: plan rollout, changelog, rollback, and post-release verification"
 ---
-
 You are Construct. Release the following: $ARGUMENTS
 
 Readiness checklist:

package/commands/ship/status.md

@@ -1,12 +1,6 @@
-<!--
-commands/ship/status.md (Status) current project state, workflow, uncommitted changes, recent activity
-
-Status: current project state, workflow, uncommitted changes, recent activity
--->
 ---
 description: "Status: current project state, workflow, uncommitted changes, recent activity"
 ---
-
 You are Construct. Report status for: $ARGUMENTS
 
 Check and report:

package/commands/understand/docs.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/docs.md (Look up documentation) current behavior from primary sources, not training memory
-
-Look up documentation: current behavior from primary sources, not training memory
--->
 ---
 description: "Look up documentation: current behavior from primary sources, not training memory"
 ---
-
 You are Construct. Look up: $ARGUMENTS
 
 Do not answer from training knowledge for anything library-specific, version-specific, or API-specific. Search first.

package/commands/understand/research.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/research.md. Research a topic. Verify facts from primary sources, separate evidence from inference.
-
-Research a topic. Verify facts from primary sources, separate evidence from inference.
--->
 ---
 description: Research a topic. Verify facts from primary sources, separate evidence from inference.
 ---
-
 You are Construct. Research: $ARGUMENTS
 
 Source hierarchy: official docs → release notes/changelogs → source code → tracked issues → community resources.

package/commands/understand/this.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/this.md (Explore and understand something) trace execution paths, map structure, gather evidence
-
-Explore and understand something: trace execution paths, map structure, gather evidence
--->
 ---
 description: "Explore and understand something: trace execution paths, map structure, gather evidence"
 ---
-
 You are Construct. Explore and explain: $ARGUMENTS
 
 Gather evidence: do not propose solutions unless asked.

package/commands/understand/why.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/why.md (Investigate a failure) why is this broken, what is the root cause
-
-Investigate a failure: why is this broken, what is the root cause
--->
 ---
 description: "Investigate a failure: why is this broken, what is the root cause"
 ---
-
 You are Construct. Investigate: $ARGUMENTS
 
 1. Capture: exact error, stack trace, reproduction steps

package/commands/work/clean.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/clean.md (Remove AI-generated code smells) verbosity, hedging, dead comments, generic names
-
-Remove AI-generated code smells: verbosity, hedging, dead comments, generic names
--->
 ---
 description: "Remove AI-generated code smells: verbosity, hedging, dead comments, generic names"
 ---
-
 You are cx-reviewer identifying AI slop in: $ARGUMENTS
 
 Then dispatch cx-engineer to apply the fixes.

package/commands/work/drive.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/drive.md (Full autonomous execution) explore, plan, implement, verify, loop until done
-
-Full autonomous execution: explore, plan, implement, verify, loop until done
--->
 ---
 description: "Full autonomous execution: explore, plan, implement, verify, loop until done"
 ---
-
 You are Construct in drive mode. Execute $ARGUMENTS fully and autonomously without stopping for confirmation.
 
 ## Execution contract

package/commands/work/optimize-prompts.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/optimize-prompts.md: Prompt optimization command.
-
-Runs the closed-loop prompt optimization workflow using telemetry trace data.
--->
 ---
 description: "Closed-loop prompt optimization: read telemetry traces, diagnose failures, push improved version to staging"
 ---
-
 You are cx-trace-reviewer running a prompt optimization cycle for: $ARGUMENTS
 
 If $ARGUMENTS is empty, optimize all agents with median quality score below 0.65 in the past 7 days.

package/commands/work/parallel-review.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/parallel-review.md (Adversarial parallel review) 5 reviewers must agree before output ships
-
-Adversarial parallel review: 5 reviewers must agree before output ships
--->
 ---
 description: "Adversarial parallel review: 5 reviewers must agree before output ships"
 ---
-
 You are Construct running a parallel adversarial review of: $ARGUMENTS
 
 Dispatch the following 5 review roles concurrently:

package/lib/beads-client.mjs

@@ -28,6 +28,21 @@ import {
   cleanupStaleQueue,
 } from './beads-lock.mjs';
 
+// Anchored bead-ID format. IDs reaching the bd shell boundary must match this;
+// regex-extracted IDs from PR bodies, agent transcripts, or intake packets get
+// re-validated here so a malformed value cannot reach the database. spawnSync
+// uses argv-array form so shell injection isn't the failure mode — log
+// corruption from a bogus ID is.
+
+const BEAD_ID_RE = /^[a-z]+-[a-z0-9]+$/;
+
+export function assertBeadId(id) {
+  if (typeof id !== 'string' || !BEAD_ID_RE.test(id)) {
+    throw new Error(`bd: invalid bead id ${JSON.stringify(id)} — expected prefix-suffix slug`);
+  }
+  return id;
+}
+
 import {
   concurrentRead,
   optimisticWrite,
@@ -253,7 +268,7 @@ async function runWithLegacyLock(args, opts, cwd, commandDesc) {
   if (!lock) {
     // Failed to get lock; add to queue if allowed
     const maxQueueWaitMs = opts.maxQueueWaitSeconds * 1000;
-    if (Date.now() - startWait + maxQueueWaitMs > maxQueueWaitMs) {
+    if (Date.now() - startWait > maxQueueWaitMs) {
       return {
         success: false,
         error: `Timeout waiting for lock after ${opts.timeoutSeconds}s`,
@@ -365,6 +380,7 @@ export async function listIssues(options = {}) {
  * Uses concurrent read (no locking needed).
  */
 export async function showIssue(id, options = {}) {
+  assertBeadId(id);
   return runBdJson(['show', id], { useOptimisticLocking: true, ...options });
 }
 
@@ -373,6 +389,7 @@ export async function showIssue(id, options = {}) {
  * Uses optimistic locking for better concurrency.
  */
 export async function claimIssue(id, options = {}) {
+  assertBeadId(id);
   // Use the specialized optimistic claim function
   const result = await claimBeadOptimistic(id, options);
   
@@ -388,6 +405,7 @@ export async function claimIssue(id, options = {}) {
  * Close an issue.
  */
 export async function closeIssue(id, options = {}) {
+  assertBeadId(id);
   return runBd(['close', id], options);
 }
 

package/lib/comment-lint.mjs

@@ -79,11 +79,15 @@ function requiresHeader(rel) {
 
 const JS_HEADER_RE = /^(?:#![^\n]*\n)?(?:\/\/[^\n]*\n)*\/\*\*[\s\S]*?\*\//;
 const MD_HEADER_RE = /^<!--[\s\S]*?-->/;
+const MD_YAML_HEADER_RE = /^---\n(?:[^\n]*\n)*?description:[\s\S]*?\n---/;
 const SH_HEADER_RE = /^#!.*\n(?:#[^\n]*\n)*/;
 
 function hasHeader(content, type) {
   if (type === 'js') return JS_HEADER_RE.test(content.trimStart());
-  if (type === 'md') return MD_HEADER_RE.test(content.trimStart());
+  if (type === 'md') {
+    const trimmed = content.trimStart();
+    return MD_HEADER_RE.test(trimmed) || MD_YAML_HEADER_RE.test(trimmed);
+  }
   return SH_HEADER_RE.test(content.trimStart());
 }
 

package/lib/context-state.mjs

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 /**
  * lib/context-state.mjs — compact project/session context persistence.
+ *
+ * Writes go through writeContextState, which uses write-to-tmp + atomic
+ * rename so concurrent writers from different hooks (pre-compact, Stop,
+ * context-window-recovery, tracking-surfaces) cannot leave a half-written
+ * JSON or markdown file behind. POSIX rename(2) is atomic for files on
+ * the same filesystem; the .cx directory always lives next to the target.
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 export function contextJsonPath(rootDir) {
@@ -58,6 +64,12 @@ export function inspectContextState(rootDir) {
   };
 }
 
+function atomicWrite(targetPath, content) {
+  const tmpPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmpPath, content, 'utf8');
+  renameSync(tmpPath, targetPath);
+}
+
 export function writeContextState(rootDir, state, { markdown = null } = {}) {
   const cxDir = join(rootDir, '.cx');
   mkdirSync(cxDir, { recursive: true });
@@ -67,10 +79,10 @@ export function writeContextState(rootDir, state, { markdown = null } = {}) {
     savedAt: new Date().toISOString(),
     ...state,
   };
-  writeFileSync(contextJsonPath(rootDir), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  atomicWrite(contextJsonPath(rootDir), `${JSON.stringify(payload, null, 2)}\n`);
 
   if (markdown !== null) {
-    writeFileSync(contextMarkdownPath(rootDir), markdown.endsWith('\n') ? markdown : `${markdown}\n`, 'utf8');
+    atomicWrite(contextMarkdownPath(rootDir), markdown.endsWith('\n') ? markdown : `${markdown}\n`);
   }
 
   return payload;