wtf-p 0.7.3 → 0.8.0

package/bin/lib/clio-registration.js

@@ -5,9 +5,9 @@ const path = require('path');
 const { createTargetGuard, resolveOwnedPath, sha256Buffer } = require('./ownership');
 
 // Clio owns integrity, provenance, drift and enable/disable for an installed
-// plugin. WTF-P owns two much smaller things: the exact bytes it publishes
-// (its v2 receipt) and the guarantee that the tree handed to Clio is the
-// generated bundle and nothing else.
+// plugin or extension. WTF-P owns two much smaller things: the exact bytes it
+// publishes (its v2 receipt) and the guarantee that each tree handed to Clio
+// is the generated package and nothing else.
 function treeFiles(root) {
   const files = new Map();
   function visit(directory) {
@@ -37,10 +37,11 @@ function scopeOptions(targetDir, options) {
   return { ...options, cwd, scope: project ? 'project' : 'user' };
 }
 
-function generatedBundle(root) {
+function generatedBundle(root, target = 'portable-plugin') {
   const inventoryPath = path.join(root, '.wtfp-generated.json');
+  if (!fs.existsSync(inventoryPath)) return null;
   const inventory = JSON.parse(fs.readFileSync(inventoryPath, 'utf8'));
-  if (inventory.schema !== 'wtfp.generated-adapter/v1' || inventory.target !== 'portable-plugin') {
+  if (inventory.schema !== 'wtfp.generated-adapter/v1' || inventory.target !== target) {
     return null;
   }
   const expected = new Map(inventory.files.map(file => [file.path, file.sha256]));
@@ -108,42 +109,110 @@ function installedListEntry(stdout, targetDir, native, scope) {
   return matches[0];
 }
 
-// Registration is what WTF-P is responsible for. Whether the operator has the
-// plugin switched on is Clio's state and their decision, so it is reported,
+function installedExtensionEntry(stdout, targetDir, native, scope) {
+  const listing = JSON.parse(stdout);
+  if (!listing || !Array.isArray(listing.extensions)) {
+    throw new Error('Clio extensions list did not return an extensions array');
+  }
+  for (const entry of listing.extensions) {
+    if (!installedRecord(entry)) throw new Error('Clio extensions list returned a malformed installed extension');
+  }
+  const matches = listing.extensions.filter(entry => entry.id === native.id && entry.scope === scope &&
+    sameRoot(entry.rootPath, path.join(targetDir, native.source)));
+  if (matches.length > 1) throw new Error('Clio extensions list returned duplicate installed extension identities');
+  return matches[0];
+}
+
+// The two Clio packages WTF-P installs, plugin first. Each is its own Clio
+// install with its own lifecycle command, generated inventory and checks.
+function clioPackages(native) {
+  const plugin = {
+    noun: 'plugin', command: 'library', id: native.id, source: native.source, inventory: 'portable-plugin',
+    deferral: 'Clio activation requires an intact generated bundle without extra or modified files',
+    list: () => ['library', 'list', '--kind', 'plugin', '--json'],
+    listed: (stdout, targetDir, scope) => installedListEntry(stdout, targetDir, native, scope),
+    // `inspect` returns the installed record for the explicitly selected scope.
+    verify: scope => ['library', 'inspect', native.id, `--${scope}`, '--json'],
+    verified: (stdout, targetDir, scope) => verifiedEntry(stdout, targetDir, native, scope)
+  };
+  if (!native.extension) return [plugin];
+  const extension = native.extension;
+  const listed = (stdout, targetDir, scope) => installedExtensionEntry(stdout, targetDir, extension, scope);
+  return [plugin, {
+    noun: 'extension', command: 'extensions', id: extension.id, source: extension.source, inventory: 'clio-extension',
+    deferral: 'Clio extension activation requires an intact generated extension without extra or modified files',
+    list: scope => ['extensions', 'list', `--${scope}`, '--json'],
+    listed,
+    verify: scope => ['extensions', 'list', `--${scope}`, '--json'],
+    verified: listed
+  }];
+}
+
+// Registration is what WTF-P is responsible for. Whether the operator has a
+// package switched on is Clio's state and their decision, so it is reported,
 // never asserted and never changed.
 function registered(entry) {
   return Boolean(entry) && entry.valid === true &&
     Array.isArray(entry.diagnostics) && entry.diagnostics.length === 0;
 }
 
-function disabledNotice(native, scope) {
-  return `Clio reports ${native.id} as installed but disabled. WTF-P does not change that preference; run clio-coder library enable ${native.id} --${scope} to switch it back on.`;
+function disabledNotice(pkg, scope) {
+  return `Clio reports ${pkg.id} as installed but disabled. WTF-P does not change that preference; run clio-coder ${pkg.command} enable ${pkg.id} --${scope} to switch it back on.`;
 }
 
+// Install the plugin, then the extension. A failure in the second compensates
+// the first, and the returned compensator undoes both in reverse order.
 function activateClio(targetDir, native, suppliedOptions) {
   const options = scopeOptions(targetDir, suppliedOptions);
+  const activated = [];
+  try {
+    for (const pkg of clioPackages(native)) {
+      const result = activatePackage(targetDir, pkg, options);
+      activated.push(result);
+      if (result.status !== 'registered') break;
+    }
+  } catch (error) {
+    const failures = activated.reverse().flatMap(result => typeof result.rollback === 'function' ? result.rollback() : []);
+    if (failures.length) error.nativeRollbackFailures = [...(error.nativeRollbackFailures || []), ...failures];
+    throw error;
+  }
+  if (activated.length === 1) return activated[0];
+  const last = activated[activated.length - 1];
+  const notices = activated.map(result => result.notice).filter(Boolean);
+  return {
+    status: last.status, executable: 'clio-coder',
+    ...(last.reason ? { reason: last.reason } : {}),
+    results: activated.flatMap(result => result.results),
+    ...(notices.length ? { notice: notices.join(' ') } : {}),
+    rollback() {
+      return [...activated].reverse().flatMap(result => typeof result.rollback === 'function' ? result.rollback() : []);
+    },
+    commit() {
+      const warnings = activated.map(result => typeof result.commit === 'function' ? result.commit() : undefined).filter(Boolean);
+      return warnings.length ? warnings.join('; ') : undefined;
+    }
+  };
+}
+
+function activatePackage(targetDir, pkg, options) {
   const { execute, environment } = options;
   const guard = createTargetGuard(targetDir);
-  const root = resolveOwnedPath(targetDir, native.source, guard);
+  const root = resolveOwnedPath(targetDir, pkg.source, guard);
   const publishedFiles = treeFiles(root);
-  const expected = generatedBundle(root);
+  const expected = generatedBundle(root, pkg.inventory);
   if (!expected || !sameTree(expected, publishedFiles)) {
-    return {
-      status: 'deferred',
-      reason: 'Clio activation requires an intact generated bundle without extra or modified files',
-      results: []
-    };
+    return { status: 'deferred', reason: pkg.deferral, results: [] };
   }
 
   const results = [];
-  const priorList = execute('clio-coder', ['library', 'list', '--kind', 'plugin', '--json'], environment, options);
+  const priorList = execute('clio-coder', pkg.list(options.scope), environment, options);
   if (priorList.status === 'unavailable') return { status: 'unavailable', executable: 'clio-coder', results };
   results.push(priorList);
-  const priorEntry = installedListEntry(priorList.stdout, targetDir, native, options.scope);
+  const priorEntry = pkg.listed(priorList.stdout, targetDir, options.scope);
   if (registered(priorEntry)) {
     return {
       status: 'registered', executable: 'clio-coder', results,
-      ...(priorEntry.enabled === false ? { notice: disabledNotice(native, options.scope) } : {})
+      ...(priorEntry.enabled === false ? { notice: disabledNotice(pkg, options.scope) } : {})
     };
   }
 
@@ -152,7 +221,7 @@ function activateClio(targetDir, native, suppliedOptions) {
   // until the receipt is durable lets a failed registration put the previous
   // installation back before the file transaction rolls it back.
   const staging = fs.mkdtempSync(path.join(path.dirname(root), '.wtfp-staged-'));
-  const source = path.join(staging, 'wtfp');
+  const source = path.join(staging, pkg.id);
   fs.renameSync(root, source);
   let finished = false;
 
@@ -163,15 +232,15 @@ function activateClio(targetDir, native, suppliedOptions) {
         if (!sameTree(publishedFiles, treeFiles(root))) {
           throw new Error('Clio content changed concurrently; recovery tree preserved');
         }
-        const removal = execute('clio-coder', ['library', 'remove', native.id, `--${options.scope}`, '--json'], environment,
+        const removal = execute('clio-coder', [pkg.command, 'remove', pkg.id, `--${options.scope}`, '--json'], environment,
           { ...options, allowAlreadyAbsent: true });
         results.push(removal);
         if (removal.status === 'unavailable') throw new Error('Clio became unavailable during rollback');
       }
       if (fs.existsSync(root)) throw new Error('Clio rollback did not remove the replacement');
-      const after = execute('clio-coder', ['library', 'list', '--kind', 'plugin', '--json'], environment, options);
+      const after = execute('clio-coder', pkg.list(options.scope), environment, options);
       results.push(after);
-      if (after.status === 'unavailable' || installedListEntry(after.stdout, targetDir, native, options.scope)) {
+      if (after.status === 'unavailable' || pkg.listed(after.stdout, targetDir, options.scope)) {
         throw new Error('Clio rollback did not clear the replacement registration');
       }
       fs.renameSync(source, root);
@@ -184,22 +253,22 @@ function activateClio(targetDir, native, suppliedOptions) {
   }
 
   try {
-    const installation = execute('clio-coder', ['library', 'install', source, `--${options.scope}`, '--json'], environment, options);
+    const installation = execute('clio-coder', [pkg.command, 'install', source, `--${options.scope}`, '--json'], environment, options);
     results.push(installation);
     if (installation.status === 'unavailable') throw new Error('Clio became unavailable during installation');
-    const inspected = execute('clio-coder', ['library', 'inspect', native.id, `--${options.scope}`, '--json'], environment, options);
+    const inspected = execute('clio-coder', pkg.verify(options.scope), environment, options);
     results.push(inspected);
     if (inspected.status === 'unavailable') throw new Error('Clio became unavailable during verification');
-    const entry = verifiedEntry(inspected.stdout, targetDir, native, options.scope);
+    const entry = pkg.verified(inspected.stdout, targetDir, options.scope);
     if (!registered(entry) || !sameTree(publishedFiles, treeFiles(root))) {
-      throw new Error('Clio did not report the exact WTF-P plugin as installed and valid with zero diagnostics');
+      throw new Error(`Clio did not report the exact WTF-P ${pkg.noun} as installed and valid with zero diagnostics`);
     }
     if (priorEntry && priorEntry.enabled !== entry.enabled) {
-      throw new Error('Clio installation changed the existing WTF-P enabled preference');
+      throw new Error(`Clio installation changed the existing WTF-P ${pkg.noun} enabled preference`);
     }
     return {
       status: 'registered', executable: 'clio-coder', results, rollback,
-      ...(entry.enabled === false ? { notice: disabledNotice(native, options.scope) } : {}),
+      ...(entry.enabled === false ? { notice: disabledNotice(pkg, options.scope) } : {}),
       commit() {
         // Only the private held copy is removed; Clio owns its installed tree.
         finished = true;
@@ -217,27 +286,49 @@ function activateClio(targetDir, native, suppliedOptions) {
   }
 }
 
+// Remove the extension, then the plugin, each only when the receipt proves it.
+// `ownedFiles` maps receipt paths below the target to their published hashes.
 function deactivateClio(targetDir, native, suppliedOptions) {
   const options = scopeOptions(targetDir, suppliedOptions);
+  const removed = [];
+  for (const pkg of clioPackages(native).reverse()) {
+    const prefix = `${pkg.source}/`;
+    const ownedFiles = options.ownedFiles && new Map([...options.ownedFiles]
+      .filter(([file]) => file.startsWith(prefix))
+      .map(([file, hash]) => [file.slice(prefix.length), hash]));
+    const result = deactivatePackage(targetDir, pkg, { ...options, ownedFiles });
+    if (result.status === 'unavailable') return result;
+    removed.push(result);
+  }
+  if (removed.length === 1) return removed[0];
+  const deferred = removed.find(result => result.status === 'deferred');
+  const results = removed.flatMap(result => result.results);
+  if (deferred) return { status: 'deferred', reason: deferred.reason, results };
+  return removed.some(result => result.status === 'unregistered')
+    ? { status: 'unregistered', executable: 'clio-coder', results }
+    : { status: 'not-required', results };
+}
+
+function deactivatePackage(targetDir, pkg, options) {
   const { execute, environment } = options;
   const guard = createTargetGuard(targetDir);
-  const listing = execute('clio-coder', ['library', 'list', '--kind', 'plugin', '--json'], environment, options);
+  const listing = execute('clio-coder', pkg.list(options.scope), environment, options);
   if (listing.status === 'unavailable') return { status: 'unavailable', executable: 'clio-coder', results: [] };
-  if (!installedListEntry(listing.stdout, targetDir, native, options.scope)) {
+  if (!pkg.listed(listing.stdout, targetDir, options.scope)) {
     return { status: 'not-required', results: [listing] };
   }
 
   // Native removal is recursive. Run it only when the receipt proves that every
   // file below the installed root is one WTF-P published and nobody changed.
-  const root = resolveOwnedPath(targetDir, native.source, guard);
+  const root = resolveOwnedPath(targetDir, pkg.source, guard);
   const ownedFiles = options.ownedFiles;
   if (!ownedFiles || !sameTree(treeFiles(root), ownedFiles)) {
-    return { status: 'deferred', reason: 'Clio native removal would include unowned or modified plugin files', results: [listing] };
+    return { status: 'deferred', reason: `Clio native removal would include unowned or modified ${pkg.noun} files`, results: [listing] };
   }
-  const result = execute('clio-coder', ['library', 'remove', native.id, `--${options.scope}`, '--json'], environment, options);
+  const result = execute('clio-coder', [pkg.command, 'remove', pkg.id, `--${options.scope}`, '--json'], environment, options);
   if (result.status === 'unavailable') return { status: 'unavailable', executable: 'clio-coder', results: [listing] };
-  const after = execute('clio-coder', ['library', 'list', '--kind', 'plugin', '--json'], environment, options);
-  if (after.status === 'unavailable' || fs.existsSync(root) || installedListEntry(after.stdout, targetDir, native, options.scope)) {
+  const after = execute('clio-coder', pkg.list(options.scope), environment, options);
+  if (after.status === 'unavailable' || fs.existsSync(root) || pkg.listed(after.stdout, targetDir, options.scope)) {
     throw new Error('Clio removal did not clear WTF-P content and registration');
   }
   return { status: 'unregistered', executable: 'clio-coder', results: [listing, result, after] };

package/bin/lib/manifest.js

@@ -67,8 +67,9 @@ const MANIFEST = {
       source: 'marketplaces/wtfp'
     }
   },
-  // Clio consumes the canonical Agent Plugins bundle through its own plugin
-  // lifecycle. There is no second WTF-P packaging for this host.
+  // Clio consumes the canonical Agent Plugins bundle through its plugin
+  // lifecycle and the desk through its extension lifecycle: two packages, two
+  // Clio installs, one WTF-P receipt.
   clio: {
     name: 'Clio Coder',
     configDirEnv: 'CLIO_CODER_CONFIG_DIR',
@@ -80,6 +81,12 @@ const MANIFEST = {
         src: path.join(ROOT, 'vendors', 'plugin'),
         dest: 'plugins/wtfp',
         type: 'dir'
+      },
+      {
+        id: 'extension',
+        src: path.join(ROOT, 'vendors', 'clio-extension'),
+        dest: 'extensions/wtfp',
+        type: 'dir'
       }
     ],
     discovery: {
@@ -89,7 +96,8 @@ const MANIFEST = {
     native: {
       kind: 'clio-plugin',
       id: 'wtfp',
-      source: 'plugins/wtfp'
+      source: 'plugins/wtfp',
+      extension: { id: 'wtfp', source: 'extensions/wtfp' }
     }
   },
   codex: {

package/bin/uninstall.js

@@ -780,9 +780,10 @@ async function uninstall(runtime, options, out) {
       vendorConfig.native,
       { ...(vendorKey === 'clio' && plan.receipt.scope === 'project'
         ? { scope: 'project', cwd: path.dirname(targetDir) } : {}),
+      // Receipt paths below the target; Clio checks each package root against them.
       ownedFiles: new Map(plan.items
-        .filter(item => item.path.startsWith(`${vendorConfig.native.source}/`) && item.state === 'unchanged')
-        .map(item => [item.path.slice(vendorConfig.native.source.length + 1), item.entry.sha256])) }
+        .filter(item => item.state === 'unchanged')
+        .map(item => [item.path, item.entry.sha256])) }
     );
     if (nativeRemoval.status === 'unavailable' && !options.hasQuiet) {
       out.warn(`${nativeRemoval.executable} is unavailable; removing the WTF-P-owned staging files without changing the client's native registry.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtf-p",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Portable, evidence-grounded academic writing workflows (papers, proposals, posters, presentations) for Clio Coder, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Antigravity CLI, and Gemini CLI.",
   "bin": {
     "wtfp": "bin/install.js",

package/protocol/actions/research-gap.json

@@ -96,7 +96,7 @@
     },
     {
       "id": "user.gate",
-      "scope": "the external providers, bounded query set, and research scope and depth"
+      "scope": "unapproved or paid external providers and bounded query set, plus author-owned research scope and depth decisions"
     }
   ]
 }

package/protocol/roles/research-synthesizer.md

@@ -42,7 +42,7 @@ Investigate the literature needed to plan and write a specific section well. The
 ## Boundaries
 
 - This is a `mutation-report` role. It may write only the research and suggestion artifacts authorized by the invoking action.
-- When external literature search is approved, `citation-search` may run with `--backend=cite-nexus` and an explicit `--providers` list after the gate. Returned results stay candidates, and this role never performs a bibliography write.
+- An operator-configured, trusted read-only CiteNexus MCP connection may search bounded public scholarly metadata without a second per-query gate. In an explicitly selected full-auto host session for this research action, `citation-search --backend=cite-nexus` may also search `crossref`, `datacite`, `europe_pmc`, or `arxiv` without another gate. Other providers or modes require explicit network approval naming providers and query bounds. Honor offline flags and host refusals. Returned results stay candidates, and this role never performs a bibliography write.
 - Never fabricate a citation, identifier, quotation, metadata field, source conclusion, or claim of exhaustive coverage.
 - Never overwrite an existing `project://sources/{source}` record. Additions remain provisional until identity and provenance are verified by an authorized action.
 - Do not explore alternatives that author decisions explicitly deferred or rejected.

package/protocol/skills/wtfp-plan-section/references/actions.md

@@ -46,7 +46,7 @@ Contract: [protocol/actions/plan-section.json](../../../actions/plan-section.jso
 2. Read the complete planning context before decomposing work: manifest, config, state, decisions, outline, section record, context, research, source/evidence records, relevant prior summaries, and the bounded `project://validations/*` collection.
 3. Before any specialist dispatch, filter the validation records to candidates whose `subject_uri` is exactly `project://structure/outline` and whose `action_id` is exactly `create-outline`. A candidate is current only when `executed_at >= outline.updated_at`. Because the v1 validation schema carries no outline revision or content hash, disclose that this timestamp test is a conservative freshness proxy.
 4. Require exactly one current candidate and require its `status` to be `passed`. Separately verify that the current outline and target section are consistent with all current locked and deferred author choices: honor locked choices and do not treat deferred choices as resolved. A missing, stale, ambiguous, or non-passing candidate, or a decision contradiction, blocks all specialist dispatch and every plan, section, state, or validation write. Only a recovery checkpoint may be proposed on this blocked path, and it may be written only after a complete record preview and explicit author approval.
-5. If the section is literature-heavy and research obligations remain empty, offer `research-gap`; do not manufacture citations to keep planning moving.
+5. If the section is literature-heavy, require a section-specific research artifact and resolvable source/evidence records for its planned claims before dispatch or approval. Run `research-gap` with the configured CiteNexus backend when available; if coverage remains insufficient, record a research checkpoint and stop. Search candidates alone are not verified citations. Do not manufacture citations to keep planning moving.
 6. Summarize the section goal, claims, evidence, manuscript artifact, dependencies, and open decisions at `config.gates.confirm_plan`.
 7. After the prerequisites pass, require `section-planner` in a bounded delegated pass to create one or more immutable Markdown `project://sections/{section}/plans/{plan}` artifacts. Each plan must declare:
    - stable section and plan identifiers;

package/protocol/skills/wtfp-research-literature/references/actions.md

@@ -14,7 +14,7 @@ Contract: [protocol/actions/research-gap.json](../../../actions/research-gap.jso
    - `standard`: run a focused, reproducible search across the most relevant categories;
    - `deep`: map foundational, recent, competing, gap-defining, and methodological work, including important disagreements and intellectual lineage.
 5. Form search questions and inclusion criteria before searching. Record databases or corpora, query strings, date, filters, and stopping rule.
-6. Search authoritative scholarly sources only after disclosing and receiving approval for the external providers and bounded query set. When using the bundled dispatcher, `citation-search` may run with `--backend=cite-nexus` and an explicit `--providers` list after this gate. Returned results stay candidates, and this action performs no bibliography write. Deduplicate candidates by persistent identifier, then normalized title.
+6. Search authoritative scholarly sources with bounded queries. Two routes need no second per-query author gate: a host connection the operator already configured and authorized for read-only public scholarly metadata search, or the bundled CiteNexus dispatcher in a host session explicitly set to full-auto for this research action when every selected provider is a free, no-key public index (`crossref`, `datacite`, `europe_pmc`, or `arxiv`). Record provider IDs, query strings, date, and result limits in the research artifact. Do not send unpublished manuscript text, private notes, or credentials as search terms. Outside those routes, first disclose the providers and bounded query set and obtain explicit author approval. The dispatcher runs only `citation-search --backend=cite-nexus` with an explicit `--providers` list; honor an operator-set offline flag or any host refusal. Returned results stay candidates, and this action performs no bibliography write. Deduplicate candidates by persistent identifier, then normalized title.
 7. Verify each retained source from its primary record or publication. Create a `project://sources/{source}` record with title, creators, year, source kind, identifiers, citation key, status, provenance, inspection depth, and verification time.
 8. Read enough of each source to distinguish its actual claim, method, population, result, and limitation. Do not cite an abstract-only impression as full-paper evidence.
 9. Create `project://evidence/{evidence}` separately for each retained claim-level interpretation, with relation, locator, limitations, confidence, and inspection depth. Synthesize by question rather than listing papers; identify consensus, disagreement, methodological differences, missing evidence, and defensible positioning.

package/protocol/skills/wtfp-write-section/references/actions.md

@@ -8,7 +8,7 @@ Contract: [protocol/actions/write-section.json](../../../actions/write-section.j
 
 1. Require an exact `project://sections/{section}/plans/{plan}` artifact linked from `project://sections/{section}` and verify its declared inputs, outputs, dependencies, validation, and approval state.
 2. If a corresponding summary or manuscript output exists, show the overwrite or merge impact and require explicit re-execution approval.
-3. Read the plan, `project://manifest`, `project://state`, `project://decisions`, `project://structure/outline`, section context and research, relevant source/evidence records, and enough neighboring prose to maintain continuity.
+3. Read the plan, `project://manifest`, `project://state`, `project://decisions`, `project://structure/outline`, section context and research, relevant source/evidence records, and enough neighboring prose to maintain continuity. For a literature-heavy section, require research and verified source/evidence coverage of the plan's factual claims before drafting. Route missing coverage through `research-gap` and a checkpoint; do not substitute model memory or search candidates for source records.
 4. Present the plan objective, output path, target words, evidence obligations, and checkpoints at the configured writing gate.
 5. Execute tasks in order against the exact `project://paper/{artifact}` output. For each task:
    - establish the paragraph or subsection's rhetorical job;

package/protocol/workflows/plan-section.md

@@ -24,8 +24,9 @@ Manuscript prose and supporting context, research, plan, review, summary, handof
 1. Resolve one section record, load its linked context, research, evidence, decisions, and outline constraints, and enumerate the bounded `project://validations/*` collection before any specialist dispatch.
 2. Filter those records to candidates whose `subject_uri` is exactly `project://structure/outline` and whose `action_id` is exactly `create-outline`. A candidate is current only when `executed_at >= outline.updated_at`. Because the v1 validation schema carries no outline revision or content hash, disclose that this timestamp test is a conservative freshness proxy.
 3. Require exactly one current candidate and require its `status` to be `passed`. Separately verify that the current outline and target section are consistent with all current locked and deferred author choices: honor locked choices and do not treat deferred choices as resolved. A missing, stale, ambiguous, or non-passing candidate, or a decision contradiction, blocks all specialist dispatch and every plan, section, state, or validation write. Only a recovery checkpoint may be proposed on this blocked path, and it may be written only after a complete record preview and explicit author approval.
-4. Only after those prerequisites pass, delegate a bounded plan to `section-planner`, then require a fresh `plan-checker` pass over claim coverage, dependencies, file scope, citations, and decision fidelity.
-5. At confirm_plan, preview the plan and validation; on approval link the plan, update section status to planned, and reconcile state. Create a checkpoint for unresolved judgment instead of bypassing the required checker.
+4. For a literature-heavy section, first require a section-specific research artifact plus resolvable source/evidence records that cover the planned claims. If they are absent or insufficient, run `research-gap` with the configured CiteNexus backend when available, verify candidate metadata against the returned records, and stop planning with an explicit research checkpoint if evidence remains insufficient. Never invent citations or treat search candidates as verified sources.
+5. Only after those prerequisites pass, delegate a bounded plan to `section-planner`, then require a fresh `plan-checker` pass over claim coverage, dependencies, file scope, citations, and decision fidelity. Dispatch the exact WTF-P specialist roles; generic coder and verifier roles do not satisfy this workflow.
+6. At confirm_plan, preview the plan and validation; on approval link the plan, update section status to planned, and reconcile state. Create a checkpoint for unresolved judgment instead of bypassing the required checker.
 
 ## Safety and completion
 

package/protocol/workflows/research-gap.md

@@ -22,7 +22,7 @@ Manuscript prose and supporting context, research, plan, review, summary, handof
 ## Procedure
 
 1. Resolve the research question and section scope against locked/deferred decisions; agree on depth and source constraints.
-2. Search declared scholarly services only after the gate names the providers and bounded query set. When using the bundled dispatcher, `citation-search` may run with `--backend=cite-nexus` and an explicit `--providers` list after this gate. Returned results stay candidates, and this action performs no bibliography write. Verify source identity and inspection depth, and separate source records from claim-level evidence.
+2. Prefer an operator-configured, trusted read-only CiteNexus MCP connection for bounded public metadata searches when the host has already authorized it. In an explicitly selected full-auto host session for this research action, the bundled CiteNexus dispatcher may also search the free no-key public indexes `crossref`, `datacite`, `europe_pmc`, and `arxiv` without a second per-query author gate; use only selected relevant indexes with an explicit `--providers` list. Record provider IDs, queries, date, and result limits; never send unpublished manuscript text or private notes as search terms. For any other route, first obtain explicit author approval naming the providers and bounded query set. Results remain candidates and this action performs no bibliography write. Verify source identity and inspection depth, and separate source records from claim-level evidence.
 3. Synthesize supported, conflicting, and missing evidence into a Markdown research artifact; link new records and disclose limitations.
 
 ## Bundled tool execution
@@ -33,7 +33,7 @@ The declared `tool.execute` effect authorises exactly one command, run from the
 node protocol://tools/wtfp-tool.js [--offline] <command> [arguments]
 ```
 
-Run it with `list` first to read the declared commands, their arguments, their bounds, and the effects each one applies; `protocol://tools/README.md` carries the same table. A command whose effects include `network.*` performs outbound requests. Until network use has been approved for this run, pass `--offline` (or set `WTFP_TOOL_OFFLINE=1`), which makes the dispatcher refuse those commands instead of relying on prose restraint. Never execute another module in this package, never pass a logical `project://` or `wtfp://` URI as a shell argument, and treat every returned record as candidate evidence until it is verified and written to a source or evidence record.
+Run it with `list` first to read the declared commands, their arguments, their bounds, and the effects each one applies; `protocol://tools/README.md` carries the same table. A command whose effects include `network.*` performs outbound requests. Pass `--offline` (or set `WTFP_TOOL_OFFLINE=1`) until the provider/query gate is approved, except for this action's explicit full-auto public-index route. On that route omit `--offline` only for `citation-search --backend=cite-nexus` with bounded queries and `--providers` drawn from `crossref,datacite,europe_pmc,arxiv`; never override an operator-set offline flag or a host refusal. Never execute another module in this package, never pass a logical `project://` or `wtfp://` URI as a shell argument, and treat every returned record as candidate evidence until it is verified and written to a source or evidence record.
 
 ## Safety and completion
 

package/protocol/workflows/write-section.md

@@ -22,7 +22,7 @@ Manuscript prose and supporting context, research, plan, review, summary, handof
 ## Procedure
 
 1. Require one approved plan and resolve all linked context, research, source/evidence records, decisions, prior summary, existing target, and necessary neighboring prose before choosing create or update.
-2. Draft only the declared manuscript artifact; cite only resolvable sources, preserve author constraints, and stop at blocking decisions.
+2. Before drafting a literature-heavy section, verify that its linked research artifact and source/evidence records cover the plan's factual claims. If coverage is missing, use the declared research workflow and pause at a checkpoint until verified records exist. Draft only the declared manuscript artifact; cite only resolvable sources, preserve author constraints, and stop at blocking decisions. A plausible bibliography entry, search candidate, or model memory is not a verified citation.
 3. Read the persisted manuscript text back and calculate its actual body word count with one deterministic method; never copy a worker self-report, plan target, or summary count into project records. Validate the persisted draft against its plan and word budget.
 4. Create or update the required Markdown summary with that measured count, then read back both manuscript and summary. Missing, empty, or inconsistent output is a failed completion condition, not permission to link a path that does not exist.
 5. Persist the validation, synchronize the manuscript URI in `manifest.artifacts.manuscripts`, and reconcile section/state records only after manuscript, summary, and validation readback succeeds. If blocked, create the declared checkpoint and stop; do not commit or merge automatically.

package/vendors/antigravity/.wtfp-generated.json

@@ -2,7 +2,7 @@
   "schema": "wtfp.generated-adapter/v1",
   "generatorVersion": 5,
   "target": "antigravity",
-  "sourceHash": "dac5b9dd1327d76dd4f80be73efcb4b9ccc4afc0e740103b33b7bdd34fc3da63",
+  "sourceHash": "c2e93ea50f26a53402f100fe9157834a3841748eebd8cc212648cd615738278d",
   "files": [
     {
       "path": "actions/add-todo.json",
@@ -118,7 +118,7 @@
     },
     {
       "path": "actions/research-gap.json",
-      "sha256": "80659531e18fb60dd46620c8b35aa27ce0f966c467f0d3073ae8c6519084153e"
+      "sha256": "0c26fa663f1d2526cbefcc9750b0a176ddf1ca538a46585a1de48c763fbb1a13"
     },
     {
       "path": "actions/resume-writing.json",
@@ -178,7 +178,7 @@
     },
     {
       "path": "agents/wtfp-research-synthesizer.md",
-      "sha256": "2adec7aab0cad7e9cc66312b14f8ee8824d269ad499319ad47094cfe4936f04a"
+      "sha256": "e50c44188d1f655268c35044760a1a314d8d7bf9ece2e9595778c1560b779114"
     },
     {
       "path": "agents/wtfp-section-planner.md",
@@ -286,7 +286,7 @@
     },
     {
       "path": "commands/wtfp-plan-section.md",
-      "sha256": "919ba047726a4c454329c054c415613a1aefdf904ddca13f0bc56426ec6798ae"
+      "sha256": "f36084563180ac559b8e5ff792565a8db6ea9a7c2031bd06ad57ad54f0be94ba"
     },
     {
       "path": "commands/wtfp-polish-prose.md",
@@ -342,7 +342,7 @@
     },
     {
       "path": "commands/wtfp-write-section.md",
-      "sha256": "82dae8583d3d300e64e68157b10c13ef9b8ba37d9c7bf947770cefe76874ef21"
+      "sha256": "100af3ef4be44fe3981023ec5f46bd7a8a3c5a956bb2ec50835ef3a823047275"
     },
     {
       "path": "compatibility/action-availability.json",
@@ -362,7 +362,7 @@
     },
     {
       "path": "plugin.json",
-      "sha256": "c6260cf5a7455c7c684661ad8704fc7a37c7034ee99b9c34a3d6c2c5bffd82cd"
+      "sha256": "9898153f5524eeea64715c41f2c6fe68f90a312e7f2c2ed08485a448da5ff989"
     },
     {
       "path": "project/README.md",
@@ -486,7 +486,7 @@
     },
     {
       "path": "roles/research-synthesizer.md",
-      "sha256": "011feaa1fdb967c267713f4fa4b0c45b27e66a62f71d1f24c4f44360442aef57"
+      "sha256": "7aa6922f5f819918374b1a87dbda5c12fa6d424be64fc13b4019c380e011306c"
     },
     {
       "path": "roles/section-planner.md",
@@ -558,7 +558,7 @@
     },
     {
       "path": "skills/wtfp-plan-section/references/actions.md",
-      "sha256": "5732b2faf9640e6663f1342ebce264a877f813570765c847216ff0e40b8ba6e6"
+      "sha256": "11d5d27f450857d9a2cd2e06184ba66b4d581e56f6530bd97c82404c8eb06e99"
     },
     {
       "path": "skills/wtfp-plan-section/SKILL.md",
@@ -570,7 +570,7 @@
     },
     {
       "path": "skills/wtfp-research-literature/references/actions.md",
-      "sha256": "83cb1dbc27563a02bb35fbb995fe54d37e5afe523821b5cb5b6c3baf2fa72d50"
+      "sha256": "7d2137fa9638782444d88cccf7161ee3afbb5ce9c95bd85fcad57e61b8265d79"
     },
     {
       "path": "skills/wtfp-research-literature/SKILL.md",
@@ -606,7 +606,7 @@
     },
     {
       "path": "skills/wtfp-write-section/references/actions.md",
-      "sha256": "367b9144ce76b4e6116d9a2566c02070e80bbb57325a43bf5aa22447e6cb83f5"
+      "sha256": "1fe6f8d50a1abd7a0b338772560317404942874ddd67be458ca24182ea20f7a4"
     },
     {
       "path": "skills/wtfp-write-section/SKILL.md",
@@ -664,9 +664,13 @@
       "path": "tools/citation/semantic-scholar.js",
       "sha256": "df4c1f3d69a28e06dd5285ba46c116bb2731aa940e16b9438c822846f38646f5"
     },
+    {
+      "path": "tools/package.json",
+      "sha256": "dbf8353f77358bc12169b7bb7301e1978d5b503e002ee927229a8993672818fc"
+    },
     {
       "path": "tools/README.md",
-      "sha256": "997889703a61599a3d6267b1ddbd571ac354b55e7fe3a9dc2ebbf00b6c6d2106"
+      "sha256": "eb99d2ef30209b409e8c0dbfccaabdf301b6bc50f17013cd8fa381c3c1d69ae2"
     },
     {
       "path": "tools/support/cite-nexus-client.js",
@@ -762,7 +766,7 @@
     },
     {
       "path": "workflows/plan-section.md",
-      "sha256": "02311226aa784dea4a6a5219ef59fcea6c904f92566318e3327aa4e883228446"
+      "sha256": "831c20c8afd147a8ba149a46f54591b6f07732983ee916a56c66701c8c701aa2"
     },
     {
       "path": "workflows/polish-prose.md",
@@ -790,7 +794,7 @@
     },
     {
       "path": "workflows/research-gap.md",
-      "sha256": "a1736edb7e739708a92e5ef11c2d7c7a87fe8e6e4d6586e8ce9b1db3ae5bb428"
+      "sha256": "02ffe236ba7de12e4b3abbac308c0e1cfc409147147d509616b95baec3fef012"
     },
     {
       "path": "workflows/resume-writing.md",
@@ -818,7 +822,7 @@
     },
     {
       "path": "workflows/write-section.md",
-      "sha256": "cfb3a0f9c61830d62cebdf8be5dacd17cef996d99cbab1df18267313ca05aacc"
+      "sha256": "5a2f0efcd11d7f41d941f54b80798ad481773820907fee68bea47f28b7af7bc3"
     }
   ]
 }

package/vendors/antigravity/actions/research-gap.json

@@ -96,7 +96,7 @@
     },
     {
       "id": "user.gate",
-      "scope": "the external providers, bounded query set, and research scope and depth"
+      "scope": "unapproved or paid external providers and bounded query set, plus author-owned research scope and depth decisions"
     }
   ]
 }

package/vendors/antigravity/agents/wtfp-research-synthesizer.md

@@ -48,7 +48,7 @@ Investigate the literature needed to plan and write a specific section well. The
 ## Boundaries
 
 - This is a `mutation-report` role. It may write only the research and suggestion artifacts authorized by the invoking action.
-- When external literature search is approved, `citation-search` may run with `--backend=cite-nexus` and an explicit `--providers` list after the gate. Returned results stay candidates, and this role never performs a bibliography write.
+- An operator-configured, trusted read-only CiteNexus MCP connection may search bounded public scholarly metadata without a second per-query gate. In an explicitly selected full-auto host session for this research action, `citation-search --backend=cite-nexus` may also search `crossref`, `datacite`, `europe_pmc`, or `arxiv` without another gate. Other providers or modes require explicit network approval naming providers and query bounds. Honor offline flags and host refusals. Returned results stay candidates, and this role never performs a bibliography write.
 - Never fabricate a citation, identifier, quotation, metadata field, source conclusion, or claim of exhaustive coverage.
 - Never overwrite an existing `project://sources/{source}` record. Additions remain provisional until identity and provenance are verified by an authorized action.
 - Do not explore alternatives that author decisions explicitly deferred or rejected.

package/vendors/antigravity/commands/wtfp-plan-section.md

@@ -32,8 +32,9 @@ Manuscript prose and supporting context, research, plan, review, summary, handof
 1. Resolve one section record, load its linked context, research, evidence, decisions, and outline constraints, and enumerate the bounded `project://validations/*` collection before any specialist dispatch.
 2. Filter those records to candidates whose `subject_uri` is exactly `project://structure/outline` and whose `action_id` is exactly `create-outline`. A candidate is current only when `executed_at >= outline.updated_at`. Because the v1 validation schema carries no outline revision or content hash, disclose that this timestamp test is a conservative freshness proxy.
 3. Require exactly one current candidate and require its `status` to be `passed`. Separately verify that the current outline and target section are consistent with all current locked and deferred author choices: honor locked choices and do not treat deferred choices as resolved. A missing, stale, ambiguous, or non-passing candidate, or a decision contradiction, blocks all specialist dispatch and every plan, section, state, or validation write. Only a recovery checkpoint may be proposed on this blocked path, and it may be written only after a complete record preview and explicit author approval.
-4. Only after those prerequisites pass, delegate a bounded plan to `section-planner`, then require a fresh `plan-checker` pass over claim coverage, dependencies, file scope, citations, and decision fidelity.
-5. At confirm_plan, preview the plan and validation; on approval link the plan, update section status to planned, and reconcile state. Create a checkpoint for unresolved judgment instead of bypassing the required checker.
+4. For a literature-heavy section, first require a section-specific research artifact plus resolvable source/evidence records that cover the planned claims. If they are absent or insufficient, run `research-gap` with the configured CiteNexus backend when available, verify candidate metadata against the returned records, and stop planning with an explicit research checkpoint if evidence remains insufficient. Never invent citations or treat search candidates as verified sources.
+5. Only after those prerequisites pass, delegate a bounded plan to `section-planner`, then require a fresh `plan-checker` pass over claim coverage, dependencies, file scope, citations, and decision fidelity. Dispatch the exact WTF-P specialist roles; generic coder and verifier roles do not satisfy this workflow.
+6. At confirm_plan, preview the plan and validation; on approval link the plan, update section status to planned, and reconcile state. Create a checkpoint for unresolved judgment instead of bypassing the required checker.
 
 ## Safety and completion
 

package/vendors/antigravity/commands/wtfp-write-section.md

@@ -30,7 +30,7 @@ Manuscript prose and supporting context, research, plan, review, summary, handof
 ## Procedure
 
 1. Require one approved plan and resolve all linked context, research, source/evidence records, decisions, prior summary, existing target, and necessary neighboring prose before choosing create or update.
-2. Draft only the declared manuscript artifact; cite only resolvable sources, preserve author constraints, and stop at blocking decisions.
+2. Before drafting a literature-heavy section, verify that its linked research artifact and source/evidence records cover the plan's factual claims. If coverage is missing, use the declared research workflow and pause at a checkpoint until verified records exist. Draft only the declared manuscript artifact; cite only resolvable sources, preserve author constraints, and stop at blocking decisions. A plausible bibliography entry, search candidate, or model memory is not a verified citation.
 3. Read the persisted manuscript text back and calculate its actual body word count with one deterministic method; never copy a worker self-report, plan target, or summary count into project records. Validate the persisted draft against its plan and word budget.
 4. Create or update the required Markdown summary with that measured count, then read back both manuscript and summary. Missing, empty, or inconsistent output is a failed completion condition, not permission to link a path that does not exist.
 5. Persist the validation, synchronize the manuscript URI in `manifest.artifacts.manuscripts`, and reconcile section/state records only after manuscript, summary, and validation readback succeeds. If blocked, create the declared checkpoint and stop; do not commit or merge automatically.