@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/mcp/tools/project.mjs

@@ -8,7 +8,8 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { loadRegistry } from '../../registry/loader.mjs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import { resolveWithinRoot } from '../../path-policy.mjs';
 import { loadConstructEnv } from '../../env-config.mjs';
 import { inspectContextState } from '../../context-state.mjs';
 import { loadWorkflow, summarizeWorkflow, inspectWorkflowHealth } from '../../workflow-state.mjs';
@@ -16,8 +17,11 @@ import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory }
 import { buildPublicHealthSurface } from '../../status.mjs';
 import { doctorRoot } from '../../config/xdg.mjs';
 
-export function exec(cmd, cwd) {
-  return execSync(cmd, { stdio: 'pipe', timeout: 10000, cwd }).toString().trim();
+// Model-controlled refs reach these git calls. Run git through argv with no shell so a
+// base_ref like `$(...)` is handed to git as one literal argument, never evaluated.
+
+function runGit(argv, cwd) {
+  return execFileSync('git', argv, { stdio: 'pipe', timeout: 10000, cwd }).toString().trim();
 }
 
 export function readJSON(filePath) {
@@ -140,10 +144,16 @@ export function summarizeDiff(args) {
   const baseRef = args.base_ref ?? 'HEAD~1';
   const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
 
+  // A ref that starts with `-` would be read by git as an option, not a revision;
+  // control characters never belong in a ref. Reject both before argv handoff.
+  if (typeof baseRef !== 'string' || baseRef.startsWith('-') || /[\0\n\r]/.test(baseRef)) {
+    return { error: 'Invalid base_ref' };
+  }
+
   let stat, nameStatus;
   try {
-    stat = exec(`git diff --stat ${baseRef}`, cwd);
-    nameStatus = exec(`git diff --name-status ${baseRef}`, cwd);
+    stat = runGit(['diff', '--stat', baseRef], cwd);
+    nameStatus = runGit(['diff', '--name-status', baseRef], cwd);
   } catch {
     return { error: 'Not a git repository or git not available' };
   }
@@ -184,7 +194,14 @@ export function summarizeDiff(args) {
 }
 
 export function scanFile(args) {
-  const filePath = resolve(args.file_path);
+  const root = args.cwd ? resolve(args.cwd) : process.cwd();
+
+  let filePath;
+  try {
+    filePath = resolveWithinRoot(root, args.file_path);
+  } catch (err) {
+    return { error: err.message };
+  }
 
   let rawBuffer;
   try {
@@ -302,14 +319,14 @@ export function projectContext(args, { ROOT_DIR }) {
   let changed_files = [];
 
   try {
-    const log = exec('git log --oneline -10', cwd);
+    const log = runGit(['log', '--oneline', '-10'], cwd);
     recent_commits = log.split('\n').filter(Boolean);
   } catch {
     // not a git repo or no commits
   }
 
   try {
-    const status = exec('git status --short', cwd);
+    const status = runGit(['status', '--short'], cwd);
     const statusLines = status.split('\n').filter(Boolean);
     changed_files = statusLines.map((l) => l.trim());
     working_tree_status = statusLines.length > 0 ? 'dirty' : 'clean';

package/lib/mcp/tools/provider-write.mjs

@@ -0,0 +1,187 @@
+/**
+ * lib/mcp/tools/provider-write.mjs — provider_write MCP tool (LMCP-I7).
+ *
+ * The only MCP-reachable path from a host agent (Claude Code, OpenCode) to an
+ * external write. Classified destructive in lib/mcp/tool-safety.mjs, so
+ * server.mjs's dispatch-time checkDestructiveGate() call already refuses the
+ * execute path without a valid out-of-band approval_token before this module
+ * ever runs — this file does not re-implement that check, it is downstream
+ * of it.
+ *
+ * Two modes, selected by `dry_run` (default true):
+ *   - dry_run=true: resolves the governed-write adapter for `provider` and
+ *     asks it to render the payload it would submit (adapter.renderDryRun),
+ *     which runs field/shape validation only. Never calls
+ *     lib/writes/envelope.mjs and never reaches adapter.write() — no network
+ *     call, no side effect, regardless of token presence.
+ *   - dry_run=false (execute): the destructive gate has already run in
+ *     server.mjs by the time dispatchToolByName reaches this module, so
+ *     arriving here at all means a token was consumed. Dispatches through
+ *     writeWithEnvelope() (LMCP-J2) — idempotency key, sent-log dedup,
+ *     policy/approval gate, retry, audit — which is the only caller of
+ *     adapter.write(). This module never calls adapter.write() directly.
+ *
+ * E4 respect: when args.specialist_id is present (an embedded-specialist
+ * caller), the proposed provider+writeKind is checked against that
+ * specialist's embedBindings grant via AuthorityGuard before either mode
+ * proceeds. A specialist outside its grant is denied here, before the
+ * adapter is even resolved — independent of and in addition to the
+ * destructive-gate token check server.mjs already performed.
+ */
+
+import { writeWithEnvelope } from '../../writes/envelope.mjs';
+import { WriteSentLog } from '../../writes/sent-log.mjs';
+import { AuthorityGuard } from '../../embed/authority-guard.mjs';
+import { mergedEmbedBindings } from '../../embed/capability-jobs.mjs';
+import { createGovernedJiraProvider } from '../../providers/contract/adapters/jira/governed-write.mjs';
+import { createJiraTransport } from '../../providers/contract/adapters/jira/transport.mjs';
+import { createGovernedConfluenceProvider } from '../../providers/contract/adapters/confluence/governed-write.mjs';
+import { createConfluenceTransport } from '../../providers/contract/adapters/confluence/transport.mjs';
+import { createGovernedGithubProvider } from '../../providers/contract/adapters/github/governed-write.mjs';
+import githubAdapter from '../../providers/contract/adapters/github/index.mjs';
+
+// Real transports read credentials from process.env at construction time
+// (JIRA_URL/JIRA_EMAIL/JIRA_TOKEN, CONFLUENCE_URL/CONFLUENCE_EMAIL/
+// CONFLUENCE_TOKEN); github's transport is the gh CLI, already
+// credential-free at construction. Building the transport lazily per call
+// (rather than once at module load) keeps a missing-credential AuthError
+// scoped to the one call that needed it.
+
+const ADAPTER_FACTORIES = {
+  jira: () => createGovernedJiraProvider({ jiraTransport: createJiraTransport() }),
+  confluence: () => createGovernedConfluenceProvider({ confluenceTransport: createConfluenceTransport() }),
+  github: () => createGovernedGithubProvider({ ghAdapter: githubAdapter }),
+};
+
+/**
+ * Resolve the governed-write adapter for a provider name. Isolated as its
+ * own function so tests can override resolution via the `deps.resolveAdapter`
+ * injection point without touching this module's real-transport wiring.
+ *
+ * @param {string} provider
+ * @returns {{ meta: object, write: Function, search?: Function, renderDryRun?: Function }}
+ */
+function resolveAdapter(provider) {
+  const factory = ADAPTER_FACTORIES[provider];
+  if (!factory) {
+    const known = Object.keys(ADAPTER_FACTORIES).join(', ');
+    throw new Error(`provider_write: unknown provider "${provider}" (known: ${known})`);
+  }
+  return factory();
+}
+
+/**
+ * Check an embedded-specialist caller's proposal against its embedBindings
+ * grant. Returns null (no opinion) when args carries no specialist_id, so
+ * non-embed callers are unaffected — additive enforcement layered in front
+ * of the destructive gate, mirroring lib/embed/capability-jobs.mjs's
+ * checkProposalAuthority for the daemon path.
+ *
+ * @param {object} args
+ * @param {{ rootDir?: string, env?: object, embedBindings?: object }} opts
+ * @returns {Promise<{ allowed: boolean, reason?: string }|null>}
+ */
+async function checkE4Binding(args, { rootDir, env = process.env, embedBindings } = {}) {
+  if (!args.specialist_id) return null;
+
+  const bindings = embedBindings ?? mergedEmbedBindings({ rootDir, env });
+  const guard = new AuthorityGuard({ authority: {} }, null, bindings);
+  const result = await guard.check('externalPost', {
+    proposal: {
+      specialistId: args.specialist_id,
+      providerId: args.provider,
+      writeKind: args.item?.type,
+    },
+  });
+
+  // Only a binding-scoped denial (mode: 'denied' with no queueId) short-circuits
+  // provider_write; a queued/autonomous authority-level outcome is not this
+  // tool's concern — the destructive gate + J2 envelope already own approval.
+  if (result.mode === 'denied' && !result.allowed) {
+    return { allowed: false, reason: result.reason };
+  }
+  return null;
+}
+
+/**
+ * provider_write tool implementation.
+ *
+ * @param {object} args
+ * @param {string} args.provider - 'jira' | 'confluence' | 'github'
+ * @param {object} args.item - write payload, shape depends on provider (see governed-write.mjs per adapter)
+ * @param {boolean} [args.dry_run=true] - render-only when true; never touches adapter.write()
+ * @param {string} [args.specialist_id] - embedded-specialist caller id (LMCP-E4 binding check)
+ * @param {string} [args.idempotency_key] - explicit idempotency key forwarded to the J2 envelope
+ * @param {object} [deps] - injection points for tests
+ * @param {Function} [deps.resolveAdapter] - override adapter resolution
+ * @param {WriteSentLog} [deps.sentLog] - override sent-log instance
+ * @param {object} [deps.embedBindings] - override merged embedBindings map
+ * @param {string} [deps.rootDir]
+ * @param {object} [deps.env]
+ * @returns {Promise<object>}
+ */
+export async function providerWrite(args = {}, deps = {}) {
+  const provider = args.provider;
+  const item = args.item;
+  const dryRun = args.dry_run !== false;
+
+  if (!provider) return { error: 'provider_write: args.provider is required' };
+  if (!item || typeof item !== 'object') return { error: 'provider_write: args.item is required' };
+
+  const bindingDenial = await checkE4Binding(args, {
+    rootDir: deps.rootDir,
+    env: deps.env,
+    embedBindings: deps.embedBindings,
+  });
+  if (bindingDenial) {
+    return { status: 'denied', provider, dryRun, reason: bindingDenial.reason };
+  }
+
+  const resolve = deps.resolveAdapter ?? resolveAdapter;
+  let adapter;
+  try {
+    adapter = resolve(provider);
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+
+  if (dryRun) {
+    if (typeof adapter.renderDryRun !== 'function') {
+      return {
+        status: 'dry-run',
+        provider,
+        dryRun: true,
+        diff: null,
+        note: `provider "${provider}" adapter has no renderDryRun; payload echoed verbatim, no validation performed.`,
+        payload: item,
+      };
+    }
+    try {
+      const diff = adapter.renderDryRun(item);
+      return { status: 'dry-run', provider, dryRun: true, diff };
+    } catch (err) {
+      return { status: 'dry-run-invalid', provider, dryRun: true, error: err.message ?? String(err) };
+    }
+  }
+
+  const sentLog = deps.sentLog ?? new WriteSentLog({ persistPath: WriteSentLog.resolvePersistPath(deps.rootDir ?? process.cwd()) });
+
+  const envelopeResult = await writeWithEnvelope({
+    provider: adapter,
+    config: {},
+    payload: item,
+    dryRun: false,
+    sentLog,
+    idempotencyKey: args.idempotency_key,
+    requestedBy: args.specialist_id ? { role: `cx-${args.specialist_id}` } : {},
+  });
+
+  return {
+    status: envelopeResult.status,
+    provider,
+    dryRun: false,
+    envelope: envelopeResult.envelope,
+  };
+}
+
+export default providerWrite;

package/lib/mcp/tools/scope.mjs

@@ -201,9 +201,6 @@ export function scopeCreate(args = {}) {
 // Mutating, gated, destructive: archive a curated scope.
 
 export function scopeArchive(args = {}) {
-  if (args.confirm !== true) {
-    return { error: 'scope_archive requires confirm=true (destructive: moves files into archive/scopes/)' };
-  }
   if (!args.id || !args.reason || String(args.reason).trim().length < 8) {
     return { error: 'scope_archive requires id:string and reason:string (>=8 chars)' };
   }

package/lib/mcp/tools/skills.mjs

@@ -253,7 +253,7 @@ export async function orchestrationPolicy(args) {
       const { emitTraceEvent, newTraceId } = await import('../../worker/trace.mjs');
       const cwd = process.cwd();
       const queue = createIntakeQueue(cwd, process.env);
-      const intake = queue.read(intakeId);
+      const intake = await queue.read(intakeId);
       if (!intake) {
         intakeError = `intake packet not found: ${intakeId}`;
       } else if (!intake.triage) {

package/lib/mcp/tools/storage.mjs

@@ -2,12 +2,12 @@
  * lib/mcp/tools/storage.mjs — Storage MCP tools: status, sync, reset, and artifact deletion.
  *
  * All functions are async. Wraps lib/storage/admin.mjs and lib/storage/sync.mjs.
- * Requires confirm=true guards on destructive operations (reset, delete).
+ * Destructive operations (reset, delete) require confirm=true plus a one-time out-of-band
+ * approval token, since these tools are reachable only through the model's argument channel.
  */
 import { resolve } from 'node:path';
 import { deleteIngestedArtifacts, getStorageStatus, inferProjectName, purgeExpiredData, resetStorage } from '../../storage/admin.mjs';
 import { syncFileStateToSql } from '../../storage/sync.mjs';
-
 export async function storageStatus(args) {
   const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
   const project = args.project ? String(args.project) : inferProjectName(cwd);

package/lib/mcp/tools/web-search-governance.mjs

@@ -0,0 +1,96 @@
+/**
+ * lib/mcp/tools/web-search-governance.mjs — the single F08 grader for web evidence.
+ *
+ * Every web result any specialist or tool ever sees passes through governWebResults here,
+ * so the F08 governance invariants (ADR-0017) are produced in exactly one place: a
+ * claim-relative class, an Admiralty grade defaulting to C3 with a derived confidence,
+ * a normalized date with a 12-month staleness flag, most-recent-first ordering, and the
+ * OWASP-LLM01 `trust: 'untrusted'` stamp on externally-sourced text. Results without a
+ * verifiable http(s) URL are dropped, never guessed. web-search.mjs (the governed
+ * provider tool), the orchestration worker's provider-native web path, and the remote
+ * orchestration ingress guard all re-use this grader so a citation can never reach a
+ * specialist ungoverned or mislabeled as trusted.
+ */
+
+const COMMUNITY_HOSTS = ['reddit.com', 'stackoverflow.com', 'news.ycombinator.com', 'discord.com', 'github.com'];
+const HIGH_CONFIDENCE_GRADES = new Set(['A1', 'A2', 'B1']);
+const STALE_AFTER_DAYS = 365;
+
+export function normalizeDate(it) {
+  const raw = it.date || it.publishedAt || it.published || it.published_at || it.datePublished || null;
+  if (!raw) return null;
+  const t = Date.parse(raw);
+  return Number.isNaN(t) ? null : new Date(t).toISOString().slice(0, 10);
+}
+
+// Claim-relative class (ADR-0017): community content is admissible primary evidence for
+// sentiment/demand claims under a checklist the tool cannot verify deterministically, so
+// community hosts default to `tertiary` (conservative for factual claims) and everything
+// else to `secondary`, leaving the researcher to promote a community source when the claim
+// is about experience.
+
+export function classifyResult(url) {
+  try {
+    const host = new URL(url).hostname.replace(/^www\./, '');
+    return COMMUNITY_HOSTS.some((h) => host === h || host.endsWith('.' + h)) ? 'tertiary' : 'secondary';
+  } catch {
+    return 'tertiary';
+  }
+}
+
+// Confidence maps from the Admiralty grade; `high` is reserved for A1/A2/B1 (ADR-0017). A
+// grade with reliability A/B or credibility 1/2 is `medium`; anything weaker is `low`.
+
+export function confidenceFromGrade(grade) {
+  if (HIGH_CONFIDENCE_GRADES.has(grade)) return 'high';
+  const reliability = grade?.[0];
+  const credibility = grade?.[1];
+  if (reliability === 'A' || reliability === 'B' || credibility === '1' || credibility === '2') return 'medium';
+  return 'low';
+}
+
+// Grade one raw item into a governed web result, or null when it carries no verifiable
+// http(s) URL. A raw item may come from a governed provider (may carry its own admiralty)
+// or a provider-native citation (never does — defaults to C3 + needsGrading).
+
+export function governWebResult(it, { now = Date.now() } = {}) {
+  if (!it || typeof it.url !== 'string' || !/^https?:\/\//.test(it.url)) return null;
+  const graded = typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty);
+  const admiralty = graded ? it.admiralty : 'C3';
+  const date = normalizeDate(it);
+  const stale = date != null && (now - Date.parse(date)) > STALE_AFTER_DAYS * 86_400_000;
+  return {
+    source: 'web',
+    url: it.url,
+    title: typeof it.title === 'string' && it.title ? it.title : it.url,
+    snippet: typeof it.snippet === 'string' ? it.snippet : '',
+    class: classifyResult(it.url),
+    admiralty,
+    confidence: confidenceFromGrade(admiralty),
+    date,
+    stale,
+    needsGrading: !graded,
+    // OWASP LLM01: web snippets are externally-sourced data — must not be treated as instructions
+    trust: 'untrusted',
+  };
+}
+
+// Order most-recent-first: fresh dated results, then undated (input order kept by the
+// stable sort), then stale ones; newest first within a tier.
+
+function recencyTier(r) {
+  return r.date && !r.stale ? 0 : r.date ? 2 : 1;
+}
+
+export function governWebResults(items, { now = Date.now() } = {}) {
+  const results = (Array.isArray(items) ? items : [])
+    .map((it) => governWebResult(it, { now }))
+    .filter(Boolean);
+  results.sort((a, b) => {
+    const t = recencyTier(a) - recencyTier(b);
+    if (t !== 0) return t;
+    if (a.date && b.date) return Date.parse(b.date) - Date.parse(a.date);
+    return 0;
+  });
+  return results;
+}

package/lib/mcp/tools/web-search.mjs

@@ -8,29 +8,12 @@
  * Admiralty grade with a derived confidence (ADR-0017) — results without a URL are dropped, not
  * guessed; (2) every result is labeled `source: 'web'` and the tool never falls back to repo/source
  * search; (3) when no governed provider is configured or the provider is unreachable, the tool
- * returns a typed degradation and zero results rather than claiming it searched the web.
+ * returns a typed degradation and zero results rather than claiming it searched the web. The grading
+ * itself lives in web-search-governance.mjs, the single chokepoint shared with the orchestration
+ * worker's provider-native web path (ADR-0050).
  */
 
-const COMMUNITY_HOSTS = ['reddit.com', 'stackoverflow.com', 'news.ycombinator.com', 'discord.com', 'github.com'];
-const HIGH_CONFIDENCE_GRADES = new Set(['A1', 'A2', 'B1']);
-
-// Recency enforcement (rules/common/research.md §1, research-execution-policy
-// recencyRule). The researcher is told to search most-recent-first and treat
-// sources older than 12 months as stale, but the provider returns relevance- and
-// authority-ranked results with the date dropped, so older established sources
-// surface over newer ones. Normalize a date from whatever field the provider
-// supplies, flag staleness against the 12-month window, and reorder
-// most-recent-first. Admiralty-derived `confidence` is left intact (ADR-0017);
-// recency rides alongside it as `date` + `stale` rather than folded into it.
-
-const STALE_AFTER_DAYS = 365;
-
-function normalizeDate(it) {
-  const raw = it.date || it.publishedAt || it.published || it.published_at || it.datePublished || null;
-  if (!raw) return null;
-  const t = Date.parse(raw);
-  return Number.isNaN(t) ? null : new Date(t).toISOString().slice(0, 10);
-}
+import { governWebResults } from './web-search-governance.mjs';
 
 function providerConfig(env) {
   const url = env.WEB_SEARCH_URL;
@@ -38,31 +21,6 @@ function providerConfig(env) {
   return { url, key: env.WEB_SEARCH_KEY || null };
 }
 
-// Claim-relative class (ADR-0017): community content is admissible primary evidence for sentiment/
-// demand claims under a checklist the tool cannot verify deterministically, so it defaults community
-// hosts to `tertiary` (conservative for factual claims) and everything else to `secondary`, leaving
-// the researcher to promote a community source to primary when the claim is about experience.
-
-function classifyResult(url) {
-  try {
-    const host = new URL(url).hostname.replace(/^www\./, '');
-    return COMMUNITY_HOSTS.some((h) => host === h || host.endsWith('.' + h)) ? 'tertiary' : 'secondary';
-  } catch {
-    return 'tertiary';
-  }
-}
-
-// Confidence maps from the Admiralty grade; `high` is reserved for A1/A2/B1 (ADR-0017). A grade with
-// reliability A/B or credibility 1/2 is `medium`; anything weaker is `low`.
-
-function confidenceFromGrade(grade) {
-  if (HIGH_CONFIDENCE_GRADES.has(grade)) return 'high';
-  const reliability = grade?.[0];
-  const credibility = grade?.[1];
-  if (reliability === 'A' || reliability === 'B' || credibility === '1' || credibility === '2') return 'medium';
-  return 'low';
-}
-
 function degraded(reason, note) {
   return { source: 'web', degraded: true, degradationReason: reason, results: [], note };
 }
@@ -92,36 +50,7 @@ export async function webSearch(args = {}, { env = process.env, fetchImpl = glob
   }
 
   const items = Array.isArray(payload?.results) ? payload.results : [];
-  const results = items
-    .filter((it) => it && typeof it.url === 'string' && /^https?:\/\//.test(it.url))
-    .map((it) => {
-      const admiralty = typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty) ? it.admiralty : 'C3';
-      const date = normalizeDate(it);
-      const stale = date != null && (now - Date.parse(date)) > STALE_AFTER_DAYS * 86_400_000;
-      return {
-        source: 'web',
-        url: it.url,
-        title: typeof it.title === 'string' && it.title ? it.title : it.url,
-        snippet: typeof it.snippet === 'string' ? it.snippet : '',
-        class: classifyResult(it.url),
-        admiralty,
-        confidence: confidenceFromGrade(admiralty),
-        date,
-        stale,
-        needsGrading: !(typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty)),
-      };
-    });
-
-  // Order most-recent-first: fresh dated results, then undated (provider order
-  // kept by the stable sort), then stale ones; newest first within a tier.
-
-  const tier = (r) => (r.date && !r.stale ? 0 : r.date ? 2 : 1);
-  results.sort((a, b) => {
-    const t = tier(a) - tier(b);
-    if (t !== 0) return t;
-    if (a.date && b.date) return Date.parse(b.date) - Date.parse(a.date);
-    return 0;
-  });
+  const results = governWebResults(items, { now });
 
   return { source: 'web', degraded: false, query, claim, results, dropped: items.length - results.length };
 }