wtf-p 0.7.2 → 0.7.4

package/README.md

@@ -19,7 +19,7 @@ the scientific judgment. The agent keeps the bookkeeping and does bounded jobs.
 
 It ships as one canonical [Agent Plugins 1.0.0](https://agent-plugins.org)
 bundle that a deterministic compiler projects into a native package for seven
-coding-agent hosts. Version `0.7.2` is the current stable release and is
+coding-agent hosts. Version `0.7.4` is the current stable release and is
 what npm `latest` resolves to; v0.5 remains installable by explicit version.
 
 **Optional CiteNexus research backend (since 0.7.0):** `citation-search --backend=cite-nexus`
@@ -56,13 +56,13 @@ registers it with the host's native plugin lifecycle where one exists.
 
 | Host | Install | Native registration the installer performs | Verified with |
 | --- | --- | --- | --- |
-| Clio Coder (0.4.7 or newer) | `npx --yes --package=wtf-p@0.7.2 -- wtf-p install clio` | `clio-coder library install <staged-bundle> --user`, then `clio-coder library inspect wtfp --user --json` | 0.4.9 (local build) |
-| Claude Code | `npx --yes --package=wtf-p@0.7.2 -- wtf-p install claude` | `claude plugin marketplace add <root>/marketplaces/wtfp --scope user`, then `claude plugin install wtfp@wtfp --scope user -y` | 2.1.274 |
-| Codex | `npx --yes --package=wtf-p@0.7.2 -- wtf-p install codex` | `codex plugin marketplace add <root>/marketplaces/wtfp`, then `codex plugin add wtfp@wtfp --json`; agents copied to `$CODEX_HOME/agents/` | 0.153.3 |
-| GitHub Copilot CLI | `npx --yes --package=wtf-p@0.7.2 -- wtf-p install copilot` | `copilot plugin marketplace add <root>/marketplaces/wtfp`, then `copilot plugin install wtfp@wtfp` | 1.0.85 |
-| OpenCode | `npx --yes --package=wtf-p@0.7.2 -- wtf-p install opencode` | Files under the OpenCode config root; OpenCode discovers them by directory | 1.18.31 |
-| Antigravity CLI | `npx --yes --package=wtf-p@0.7.2 -- wtf-p install antigravity` | `agy plugin install <root>/sources/wtfp` | 1.2.5 |
-| Gemini CLI | `npx --yes --package=wtf-p@0.7.2 -- wtf-p install gemini` | Files under `<root>/extensions/wtfp`; Gemini discovers the extension by directory | 0.60.0 |
+| Clio Coder (0.4.7 or newer) | `npx --yes --package=wtf-p@0.7.4 -- wtf-p install clio` | `clio-coder library install <staged-bundle> --user`, then `clio-coder library inspect wtfp --user --json` | 0.4.9 (local build) |
+| Claude Code | `npx --yes --package=wtf-p@0.7.4 -- wtf-p install claude` | `claude plugin marketplace add <root>/marketplaces/wtfp --scope user`, then `claude plugin install wtfp@wtfp --scope user -y` | 2.1.274 |
+| Codex | `npx --yes --package=wtf-p@0.7.4 -- wtf-p install codex` | `codex plugin marketplace add <root>/marketplaces/wtfp`, then `codex plugin add wtfp@wtfp --json`; agents copied to `$CODEX_HOME/agents/` | 0.153.3 |
+| GitHub Copilot CLI | `npx --yes --package=wtf-p@0.7.4 -- wtf-p install copilot` | `copilot plugin marketplace add <root>/marketplaces/wtfp`, then `copilot plugin install wtfp@wtfp` | 1.0.85 |
+| OpenCode | `npx --yes --package=wtf-p@0.7.4 -- wtf-p install opencode` | Files under the OpenCode config root; OpenCode discovers them by directory | 1.18.31 |
+| Antigravity CLI | `npx --yes --package=wtf-p@0.7.4 -- wtf-p install antigravity` | `agy plugin install <root>/sources/wtfp` | 1.2.5 |
+| Gemini CLI | `npx --yes --package=wtf-p@0.7.4 -- wtf-p install gemini` | Files under `<root>/extensions/wtfp`; Gemini discovers the extension by directory | 0.60.0 |
 
 "Verified" means native discovery in a disposable profile on this exact
 envelope, with the commands recorded in
@@ -77,9 +77,9 @@ the old executable instead.
 ## Sixty-second start
 
 ```bash
-npx --yes --package=wtf-p@0.7.2 -- wtf-p install clio
+npx --yes --package=wtf-p@0.7.4 -- wtf-p install clio
 cd /path/to/your-paper-or-proposal
-clio-coder --autonomy suggest
+clio-coder --autonomy full-auto
 ```
 
 ```text
@@ -134,7 +134,11 @@ action returns `WTFP_ACTION_UNAVAILABLE` instead of improvising:
 
 Where the research routes are available, `tool.execute` authorizes exactly one
 command, the bundled `tools/wtfp-tool.js` dispatcher over seven bibliography
-and citation tools. Run it with `--offline` until you approve network use.
+and citation tools. On Clio full-auto, `research-gap` can search free no-key
+public indexes through CiteNexus without another approval for each bounded
+query. An operator-configured read-class CiteNexus MCP connection is preferred
+when the Clio build supports it. Other network routes keep their author gate;
+see [CiteNexus setup](docs/CITE_NEXUS.md).
 
 ## What it will not do
 

package/bin/commands/install-logic.js

@@ -24,8 +24,11 @@ const {
   atomicWriteFile,
   createOwnedDirectory,
   createTargetGuard,
+  isTrustedReceipt,
   materializeTargetGuard,
   readOwnedRegularSnapshot,
+  readReceipt,
+  relativeOwnedPath,
   removeCreatedDirectories,
   sha256Buffer
 } = require('../lib/ownership');
@@ -221,8 +224,9 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
   const c = out.colors;
   let rl = null;
   let globalChoice = null;
-  const stats = { installed: 0, skipped: 0, backed: 0 };
+  const stats = { installed: 0, skipped: 0, backed: 0, unchanged: 0 };
   const plan = [];
+  const retained = [];
   const targetGuard = options.targetGuard || createTargetGuard(targetDir);
 
   assertTargetGuard(targetGuard);
@@ -230,9 +234,21 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
     assertOwnedAbsolutePath(targetDir, file.dest, targetGuard);
   }
 
-  const existingFiles = files.filter(file => Boolean(
-    readOwnedRegularSnapshot(targetDir, file.dest, targetGuard, { allowMissing: true })
-  ));
+  // A trusted receipt proves which existing files this package wrote. A file
+  // whose bytes still match its receipt hash is unmodified package output, so
+  // an upgrade replaces it without treating it as an operator conflict.
+  const { receipt } = readReceipt(targetDir, targetGuard);
+  const ownedHashes = new Map();
+  if (isTrustedReceipt(receipt, targetDir, targetGuard)) {
+    for (const entry of receipt.files) ownedHashes.set(entry.path, entry.sha256);
+  }
+  const ownedUnmodified = (file, snapshot) => Boolean(snapshot) &&
+    ownedHashes.get(relativeOwnedPath(targetDir, file.dest, targetGuard)) === snapshot.sha256;
+
+  const existingFiles = files.filter(file => {
+    const snapshot = readOwnedRegularSnapshot(targetDir, file.dest, targetGuard, { allowMissing: true });
+    return Boolean(snapshot) && !ownedUnmodified(file, snapshot);
+  });
 
   if (existingFiles.length > 0 && !hasForce && !hasBackupAll && isInteractive) {
     const relPath = getPathLabel(targetDir, true);
@@ -275,8 +291,19 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
         }
       }
 
+      const source = readSourceSnapshot(file);
+      const processed = processContent(file.src, pathPrefix, source.bytes);
+      const content = processed === null ? source.bytes : Buffer.from(processed, 'utf8');
+
       let choice = exists ? 'skip' : 'create';
-      if (exists && hasBackupAll) {
+      if (exists && !hasForce && !hasBackupAll && ownedUnmodified(file, existingSnapshot)) {
+        if (sha256Buffer(content) === existingSnapshot.sha256) {
+          stats.unchanged++;
+          retained.push({ dest: file.dest, componentId: file.componentId, action: 'retained', backupPath: null });
+          continue;
+        }
+        choice = 'overwrite';
+      } else if (exists && hasBackupAll) {
         choice = 'backup';
       } else if (exists && hasForce) {
         choice = 'overwrite';
@@ -307,9 +334,6 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
         continue;
       }
 
-      const source = readSourceSnapshot(file);
-      const processed = processContent(file.src, pathPrefix, source.bytes);
-      const content = processed === null ? source.bytes : Buffer.from(processed, 'utf8');
       plan.push({
         ...file,
         exists,
@@ -563,7 +587,10 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
 
   return {
     ...stats,
-    writtenFiles: applied.map(({
+    // Retained files already hold this version's bytes. They join the receipt
+    // at the new version only when the transaction wrote something, so a
+    // no-op reinstall leaves the receipt untouched.
+    writtenFiles: applied.length === 0 ? [] : [...applied.map(({
       previousContent,
       previousMode,
       existed,
@@ -573,7 +600,7 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
       backupHash,
       backupIdentity,
       ...record
-    }) => record),
+    }) => record), ...retained],
     rollback,
     commit() {
       rolledBack = true;

package/bin/lib/adapter-compiler.js

@@ -584,6 +584,8 @@ function inlineProtocolResources(workflowBody) {
   return trailing.length === 0 ? body : `${body}\n\n${trailing.join('\n\n')}`;
 }
 
+// Action commands place this banner after the body. Hosts that title a session
+// from the first text of an expanded command template would otherwise show it.
 function generatedBanner(kind, id) {
   return `<!-- Generated by WTF-P adapter compiler v${GENERATOR_VERSION} from ${kind}/${id}; do not edit. -->`;
 }
@@ -603,6 +605,15 @@ function clioUserGateBody(action) {
   ].join('\n');
 }
 
+function clioResearchConnectionBody(action) {
+  if (action.id !== 'research-gap') return '';
+  return [
+    '## Clio CiteNexus binding',
+    '',
+    'In full-auto, the main agent first calls `gateway(op="find", query="cite-nexus")`. If a CiteNexus server is present and its tools are admitted as read-class through the operator\'s user configuration, call `gateway(op="describe", capability="<search-papers capability>")`, then `gateway(op="call", capability="<search-papers capability>", args={...})` with bounded public metadata queries. Use the capability name and argument schema returned by the gateway, not a guessed name. MCP connections are session-owned and unavailable in delegated workers, so pass the returned candidates and provenance to `wtfp-research-synthesizer` instead of asking that worker to discover the MCP server. This user-configured read connection is prior authorization for those searches; do not call `ask_user` again for each query. If no read-class CiteNexus connection is available and no gateway call has been refused, full-auto may instead run the bundled `citation-search --backend=cite-nexus` through its declared dispatcher with bounded public queries and an explicit `--providers` list containing only `crossref`, `datacite`, `europe_pmc`, or `arxiv`; pass those candidates to the same specialist. An operator-set offline flag, unavailable companion, or host refusal stops this route. Other providers and modes follow the declared user gate. Never bypass a gateway refusal by rerunning the same denied request through `bash`. Record the exact provider IDs, queries, limits, date, and provenance; verify each retained candidate before citing it.'
+  ].join('\n');
+}
+
 // Workflow order for the operator-facing reference. Group membership comes from
 // the catalog; only the reading order of the groups is fixed here.
 const HELP_GROUP_ORDER = Object.freeze([
@@ -679,11 +690,11 @@ function clioHelpCard(model, availabilityById) {
     'display-only: true',
     '---',
     '',
-    generatedBanner('protocol/actions', 'help'),
-    '',
     '```text',
     card,
     '```',
+    '',
+    generatedBanner('protocol/actions', 'help'),
     ''
   ].join('\n');
 }
@@ -699,7 +710,7 @@ function renderMarkdownCommand(action, workflowBody, target, availability) {
     if (target === 'claude' || target === 'copilot' || target === 'antigravity') {
       lines.push('allowed-tools: []');
     }
-    lines.push('---', '', generatedBanner('protocol/actions', action.id), '', blockedActionBody(action, target, availability), '');
+    lines.push('---', '', blockedActionBody(action, target, availability), '', generatedBanner('protocol/actions', action.id), '');
     return lines.join('\n');
   }
   lines.push('argument-hint: "[arguments]"');
@@ -711,13 +722,14 @@ function renderMarkdownCommand(action, workflowBody, target, availability) {
     }
   }
   const nativeBody = nativeCommandBody(action, workflowBody, target);
-  const userGateBody = target === 'clio' ? [clioUserGateBody(action), action.delegation.length ? '## Clio role-result binding\n\nRead the single wtfp.role-result entry in native validations/checks and parse its evidence string as portable role-result JSON. Validate its schema, role and action against the dispatched task. Missing, duplicate or malformed outcomes fail closed. On needs_input ask the author through ask_user and redispatch with the response; on blocked or failed stop and report the issue. Only completed permits downstream work, and it never substitutes for an author gate or artifact readback.' : ''].filter(Boolean).join('\n\n') : '';
+  const clioRoles = action.delegation.map((entry) => `\`wtfp-${entry.role}\``).join(', ');
+  const userGateBody = target === 'clio' ? [clioUserGateBody(action), clioResearchConnectionBody(action), action.delegation.length ? `## Clio role-result binding\n\nDispatch the declared specialist roles using these exact Clio agent IDs: ${clioRoles}. Do not substitute generic coder or verifier agents. If a named agent is unavailable, report that blocker and stop instead of silently changing roles.\n\nRead the single wtfp.role-result entry in native validations/checks and parse its evidence string as portable role-result JSON. Validate its schema, role and action against the dispatched task. Missing, duplicate or malformed outcomes fail closed. On needs_input ask the author through ask_user and redispatch with the response; on blocked or failed stop and report the issue. Only completed permits downstream work, and it never substitutes for an author gate or artifact readback.` : ''].filter(Boolean).join('\n\n') : '';
   lines.push(
     '---',
     '',
-    generatedBanner('protocol/actions', action.id),
-    '',
     userGateBody ? `${nativeBody}\n\n${userGateBody}` : nativeBody,
+    '',
+    generatedBanner('protocol/actions', action.id),
     ''
   );
   return lines.join('\n');
@@ -732,8 +744,8 @@ function renderGeminiCommand(action, workflowBody, availability) {
     `description = ${JSON.stringify(action.description)}`,
     '',
     "prompt = '''",
-    generatedBanner('protocol/actions', action.id),
     body,
+    generatedBanner('protocol/actions', action.id),
     "'''",
     ''
   ].join('\n');
@@ -766,9 +778,9 @@ function renderCopilotCloudPrompt(action, workflowBody, availability) {
     lines.push(
       '---',
       '',
-      generatedBanner('protocol/actions', action.id),
-      '',
       blockedActionBody(action, 'copilot-cloud', availability),
+      '',
+      generatedBanner('protocol/actions', action.id),
       ''
     );
     return lines.join('\n');
@@ -779,9 +791,9 @@ function renderCopilotCloudPrompt(action, workflowBody, availability) {
   lines.push(
     '---',
     '',
-    generatedBanner('protocol/actions', action.id),
-    '',
     nativeCommandBody(action, workflowBody, 'copilot-cloud'),
+    '',
+    generatedBanner('protocol/actions', action.id),
     ''
   );
   return lines.join('\n');
@@ -1699,6 +1711,7 @@ function addToolBundle(plan) {
     rows.push(`- \`${tool.implementation}\` → \`${outputPath}\` (legacy module \`${tool.legacyName}.js\`)`);
   }
   addFile(plan, 'tools/wtfp-tool.js', toolDispatcher(byToolId, effectsByToolId));
+  addFile(plan, 'tools/package.json', '{"type":"commonjs"}\n');
   addFile(plan, 'tools/README.md', [
     '# WTF-P bundled tools',
     '',
@@ -1721,7 +1734,7 @@ function addToolBundle(plan) {
     '',
     ...TOOL_COMMANDS.map((entry) => `- \`${entry.usage}\` → \`${entry.tool}\` (${effectsByToolId.get(entry.tool).length > 0 ? effectsByToolId.get(entry.tool).join(', ') : 'no declared effects'})`),
     '',
-    'For approved scholarly discovery, `citation-search --backend=cite-nexus --query="<topic>"` uses the separately installed `cite-nexus-wtfp` companion and its real MCP stdio server. Defaults are Crossref, DataCite and Europe PMC. Select optional vendors explicitly with `--providers`; include selected providers and query scope in the action approval. CiteNexus supports only balanced provider ordering, so omit `--intent` or use `--intent=balanced`. Results remain candidates: retain `citeNexus.sources`, field attribution, metrics, warnings and `metadata.errors`; do not infer verification or combine citation counts. The result limit is a displayed total; `metadata.total` counts the fetched deduplicated page, not the full corpus. Unavailable enrichment fails explicitly without falling back to another vendor. `WTFP_CITE_NEXUS_COMMAND` may name an absolute installed companion executable; it is operator configuration, never source content. No package is installed, server registered, or user profile changed by a tool call. Offline mode refuses this backend before process launch. Host capability blockers still apply.',
+    'For declared scholarly discovery, `citation-search --backend=cite-nexus --query="<topic>"` uses the separately installed `cite-nexus-wtfp` companion and its real MCP stdio server. Defaults are Crossref, DataCite and Europe PMC. Select providers explicitly with `--providers`. The `research-gap` full-auto route may use only free no-key public indexes (`crossref`, `datacite`, `europe_pmc`, `arxiv`) without another per-query gate; other routes require action approval naming providers and query scope. CiteNexus supports only balanced provider ordering, so omit `--intent` or use `--intent=balanced`. Results remain candidates: retain `citeNexus.sources`, field attribution, metrics, warnings and `metadata.errors`; do not infer verification or combine citation counts. The result limit is a displayed total; `metadata.total` counts the fetched deduplicated page, not the full corpus. Unavailable enrichment fails explicitly without falling back to another vendor. `WTFP_CITE_NEXUS_COMMAND` may name an absolute installed companion executable; it is operator configuration, never source content. No package is installed, server registered, or user profile changed by a tool call. Offline mode refuses this backend before process launch. Host capability blockers still apply.',
     '',
     'Every command prints one JSON document on stdout and reports failures as `{"error": "..."}` on stderr with exit status 1. Queries are capped at 512 characters, file paths at 4096, and result limits at 25. A symlinked file is accepted and read through its resolved target, which must be a regular file. Commands whose effects include `network.*` perform outbound requests to the declared scholarly indexes; pass `--offline` or set `WTFP_TOOL_OFFLINE=1` to refuse them, which is the mechanical form of "do not invoke a network-capable bibliography tool through a filesystem-only permission path". Each network command has a hard wall clock, `--timeout=<seconds>` (default 20, maximum 600); on expiry it reports `{"error": "<command> timed out after N s"}` on stderr and exits 124. `bib-impact` reports batch progress on stderr. `bib-index` flags repeated keys with `duplicate: true` and lists them under `duplicates`; `--key` refuses an ambiguous key. `bib-format` emits a standard BibTeX entry (`@article`, `@inproceedings`, ...) by default; `--style=al-folio` selects the Jekyll al-folio projection, which is not valid BibTeX. Do not execute any other module in this package directly, and do not pass a logical `project://` or `wtfp://` URI as a shell argument.',
     ''

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtf-p",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "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-deliver-research/references/actions.md

@@ -52,7 +52,7 @@ Contract: [protocol/actions/create-slides.json](../../../actions/create-slides.j
 1. Require project identity and enough manuscript or verified results to support a presentation.
 2. Ask for duration, expected slide count, audience, occasion, delivery format, visual style, and desired emphasis.
 3. Derive a timed narrative: audience problem, thesis, minimum background, method, strongest evidence, limitations, implications, and closing takeaway. Allocate time and slides before writing.
-4. Use verified project claims and cite source or manuscript locations in speaker notes or a references slide. Do not introduce novel results to make the story cleaner.
+4. Use verified project claims and cite source or manuscript locations in speaker notes or a references slide. Do not introduce novel results to make the story cleaner. Refuse any claim without a ledger row, never invent speaker or venue metadata, and derive diagrams only from named source files or documents with stated paths.
 5. Prefer one communicative purpose per slide. Use concise text, readable type, high contrast, descriptive titles, accessible color, and alt text or equivalent descriptions for meaningful visuals.
 6. Use existing figures only when provenance and interpretation are known. Mark placeholders and data needs explicitly; never fabricate a chart.
 7. Generate editable slide source and a delivery manifest under `project://deliverables/slides/{artifact}`.
@@ -65,11 +65,11 @@ Completion requires an audience-appropriate editable deck with an honest render
 
 Contract: [protocol/actions/create-poster.json](../../../actions/create-poster.json)
 
-1. Require project identity and verified manuscript findings. Ask for dimensions, orientation, venue rules, audience viewing distance, title, authors, affiliations, contact details, output format, and available visuals.
+1. Require project identity and verified manuscript findings. Ask for dimensions, orientation, venue rules, audience viewing distance, title, authors, affiliations, contact details, output format, and available visuals. Never invent missing metadata; leave a visible placeholder and report it.
 2. Define a non-linear reading hierarchy: one-sentence takeaway, motivation, minimal method, principal evidence, limitations, conclusion, and contact or artifact link.
 3. Budget physical space before writing. Prioritize the title, takeaway, and strongest figure; avoid shrinking prose to preserve excess content.
-4. Use verified claims, values, citations, and figures. Record provenance and include accessible descriptions. Mark missing visuals as placeholders rather than generating false evidence.
-5. Generate editable poster source and a delivery manifest under `project://deliverables/poster/{artifact}`.
+4. Use verified claims, values, citations, and figures, recorded in the claim ledger from `protocol://templates/poster.md`; refuse any statement without a source record, manuscript passage, or named project file. Derive diagrams only from named source files or documents and state their paths. Record provenance and include accessible descriptions. Mark missing visuals as placeholders rather than generating false evidence.
+5. Generate editable, laid-out poster source (the template's HTML grid or the venue's mandated template) and a delivery manifest with the claim ledger under `project://deliverables/poster/{artifact}`.
 6. Check dimensions, orientation, margins, font sizes at final scale, column flow, contrast, image resolution, citation legibility, link or code targets, and overflow.
 7. Render only when requested and a configured host-provided local renderer exists; invoke it under the action's declared `tool.execute` effect and verify the actual artifact dimensions. Distinguish source validity from render success.
 8. Report source and rendered paths, validation results, print-service considerations, and unresolved manual steps.

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/templates/poster.md

@@ -2,65 +2,148 @@
 
 Source structure for `project://deliverables/poster/{artifact}`. A poster is a standing argument read at two distances: the title and headline claim from three metres, the panels from one. It is not a slide deck and not a compressed paper.
 
-Copy the body below, replace every bracketed placeholder from the manuscript and its evidence records, and delete any panel the work does not support. WTF-P writes poster source only; it declares no rendering effect and runs no renderer. If the author wants a rendered PDF, hand back the exact command for their own toolchain.
+The deliverable is a laid-out page, not a text outline. Write it as one self-contained HTML file (for example `project://deliverables/poster/poster.html`) using the skeleton below, which fixes the page size, grid, hierarchy, palette, and type scale in CSS. The author opens it in any browser to see the layout and prints it to PDF at the page size. If the venue mandates a LaTeX or PowerPoint template, use that template instead and carry over the same grid, hierarchy, and type scale. WTF-P writes poster source only; it declares no rendering effect and runs no renderer. If the author wants a rendered PDF, hand back the exact command or print step for their own toolchain.
+
+Follow this scaffold literally. Replace every bracketed placeholder from the manuscript and its evidence records, and delete any panel the work does not support rather than filling it.
 
 ## Confirm before writing
 
-Dimensions and orientation, the venue's template or branding requirement, the session audience, the single claim the poster must land, and which figures already exist as artifacts.
+Dimensions and orientation, the venue's template or branding requirement, the session audience, the single claim the poster must land, which figures already exist as artifacts, and the exact author names, affiliations, contact, funding, and venue line. Ask for any of these the manifest does not record.
+
+## Evidence gate
+
+Complete this gate before writing any poster text, and repeat it on the finished file.
+
+1. Build a claim ledger: one row per claim, number, comparison, or figure the poster will carry, each naming its support as a manuscript passage, a `project://sources/{source}` record, a `project://evidence/{evidence}` record, or a named project file path.
+2. Refuse any row without support. Do not rephrase it into a softer claim; cut it. Statements about other systems, tools, or prior work (for example how another framework divides responsibilities) need a cited source record, never general knowledge.
+3. Never invent author names, affiliations, emails, funding, grant numbers, venue, or dates. When the manifest or the author does not supply one, leave a visible placeholder such as `[AFFILIATION NEEDED]` in the poster and list it under unresolved items in the report.
+4. Keep the ledger in the delivery manifest next to the poster so a reviewer can check every row.
+
+## Diagram provenance
+
+Every diagram is evidence, not decoration.
 
-## Budgets
+- Reuse an existing manuscript figure when one exists, and cite its path.
+- When the subject is software, derive architecture and flow diagrams only from named source files or documentation in the project the author pointed to. Read those files first. Every box and arrow must correspond to a module, component, call, or data path that exists in them.
+- State the source paths under each diagram, for example `Source: src/router/dispatch.ts, docs/ARCHITECTURE.md`.
+- Draw diagrams as inline SVG or Mermaid source so they stay editable. If no grounded source exists, leave a labeled placeholder box stating which files are needed; never draw an invented architecture.
 
-A readable poster carries 400 to 800 words total. Body text sits at 24pt or larger, panel headings at 36pt or larger, the title at 72pt or larger. If a panel exceeds its budget the content belongs in the paper, not the poster.
+## Layout and design
+
+| Element | Rule |
+| --- | --- |
+| Page | Confirmed size; default 48 × 36 in landscape (A0 841 × 1189 mm portrait is the common alternative) |
+| Margins and gutters | 1 in outer margin, 0.75 in gutter between columns |
+| Grid | Landscape uses three columns; portrait uses two. Results may span two columns |
+| Reading order | Title band across the full width, headline claim band beneath it, then panels top to bottom within each column, left to right |
+| Hierarchy | Title 90 to 110 pt bold, headline claim 54 to 60 pt, panel headings 40 to 48 pt, body 26 to 32 pt, captions and references 20 to 24 pt |
+| Palette | One dark ink, one light ground, one primary accent for headings and the claim band, one secondary accent for highlights in figures. Text contrast of at least 4.5:1. Use venue or institution colours only when the author supplies them |
+| Figures | The strongest result figure is the largest element after the title. Each figure carries a one-line reading and its source path |
+| Density | 400 to 800 words total. If a panel exceeds its budget, the content belongs in the paper, not the poster |
 
 | Panel | Words | Purpose |
 | --- | --- | --- |
-| Title block | 25 | Title, authors, affiliations, contact or code link |
+| Title band | 25 | Title, authors, affiliations, contact or code link |
 | Headline claim | 30 | The finding, stated as a sentence a reader can repeat |
 | Motivation | 80 | The problem and why the audience should care |
-| Approach | 120 | What was built or done, with one diagram |
+| Approach | 120 | What was built or done, with one grounded diagram |
 | Results | 150 | Two or three figures, each with a one-line reading |
 | What it means | 80 | The consequence, and the boundary of the claim |
 | References and provenance | 60 | Cited sources, funding, and artifact links |
 
 ---
 
-# [Title: the claim, not the topic]
-
-**[Author names]** · [Affiliations] · [contact or repository link]
-
-## [Headline claim in one sentence]
-
-## Why this matters
-
-- [Problem, in the audience's terms]
-- [What breaks today, with the number that shows it]
-
-## What we did
-
-- [Approach in one sentence]
-- [The one design decision a reader would ask about]
-
-![Approach diagram]([project://paper/{artifact} figure reference])
-
-## What we found
-
-![Primary result]([figure reference])
-
-- [One-line reading of the primary figure, with the measured value]
-- [Second result, with its condition]
-- [What the result does not show]
-
-## What it means
-
-- [Consequence for the audience]
-- [Stated limitation]
-
-## References
-
-[Only sources with a `project://sources/{source}` record. Include the funding acknowledgement and artifact or data links the venue requires.]
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>[Poster title]</title>
+<style>
+  @page { size: 48in 36in; margin: 0; }
+  :root {
+    --ink: #1b1f24; --ground: #fbfaf7; --accent: #1f4e79; --highlight: #c8553d; --muted: #5a6270;
+    --margin: 1in; --gutter: 0.75in;
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; background: var(--ground); color: var(--ink); }
+  body { width: 48in; height: 36in; padding: var(--margin); font: 28pt/1.35 "Source Sans 3", "Helvetica Neue", Arial, sans-serif;
+         display: grid; grid-template-rows: auto auto 1fr auto; gap: var(--gutter); }
+  header h1 { font-size: 100pt; line-height: 1.05; margin: 0 0 0.2in; }
+  header .byline { font-size: 34pt; color: var(--muted); }
+  .claim { background: var(--accent); color: var(--ground); font-size: 56pt; font-weight: 600; padding: 0.4in 0.6in; }
+  main { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gutter); align-items: start; }
+  section h2 { font-size: 44pt; color: var(--accent); border-bottom: 4pt solid var(--accent); margin: 0 0 0.25in; }
+  section + section { margin-top: var(--gutter); }
+  .span-2 { grid-column: span 2; }
+  figure { margin: 0.2in 0; }
+  figure img, figure svg { width: 100%; height: auto; }
+  figcaption, .source { font-size: 22pt; color: var(--muted); }
+  footer { font-size: 22pt; color: var(--muted); display: flex; justify-content: space-between; gap: var(--gutter); }
+  .placeholder { outline: 4pt dashed var(--highlight); padding: 0.3in; color: var(--highlight); }
+</style>
+</head>
+<body>
+  <header>
+    <h1>[Title: the claim, not the topic]</h1>
+    <div class="byline">[Author names from manifest or AUTHORS NEEDED] · [Affiliations or AFFILIATION NEEDED] · [contact or repository link]</div>
+  </header>
+
+  <div class="claim">[Headline claim in one sentence, backed by a ledger row]</div>
+
+  <main>
+    <div class="column">
+      <section>
+        <h2>Why this matters</h2>
+        <ul>
+          <li>[Problem, in the audience's terms]</li>
+          <li>[What breaks today, with the number that shows it and its source]</li>
+        </ul>
+      </section>
+      <section>
+        <h2>What we did</h2>
+        <p>[Approach in one sentence]</p>
+        <figure>
+          [Inline SVG or Mermaid diagram derived from the named files, or a .placeholder box naming the files needed]
+          <figcaption>[What the diagram shows] <span class="source">Source: [paths]</span></figcaption>
+        </figure>
+      </section>
+    </div>
+
+    <div class="column span-2">
+      <section>
+        <h2>What we found</h2>
+        <figure>
+          <img src="[figure path inside the project]" alt="[accessible description]">
+          <figcaption>[One-line reading of the primary figure, with the measured value] <span class="source">Source: [path or record]</span></figcaption>
+        </figure>
+        <ul>
+          <li>[Second result, with its condition]</li>
+          <li>[What the result does not show]</li>
+        </ul>
+      </section>
+      <section>
+        <h2>What it means</h2>
+        <ul>
+          <li>[Consequence for the audience]</li>
+          <li>[Stated limitation]</li>
+        </ul>
+      </section>
+    </div>
+  </main>
+
+  <footer>
+    <div>[References: only sources with a project://sources/{source} record]</div>
+    <div>[Funding acknowledgement or FUNDING NEEDED] · [artifact or data links]</div>
+  </footer>
+</body>
+</html>
+```
+
+For portrait pages, change `@page` and the `body` size to the confirmed dimensions, set `main` to `repeat(2, 1fr)`, and drop the `span-2` class.
 
 ---
 
 ## Attribution rules
 
-Every number, figure, and claim on the poster must trace to a manuscript passage or an evidence record. Carry the source attribution onto the poster itself for any figure reused from another work. Do not introduce a claim, a number, or a citation that appears nowhere in the project's records.
+Every number, figure, and claim on the poster must trace to a row in the claim ledger. Carry the source attribution onto the poster itself for any figure reused from another work. Do not introduce a claim, a number, a citation, or a piece of author metadata that appears nowhere in the project's records or the author's answers.

package/protocol/templates/slides.md

@@ -6,7 +6,11 @@ Copy the body below, replace every bracketed placeholder from the manuscript and
 
 ## Confirm before writing
 
-Talk length, audience, venue format, whether questions are inside or outside the slot, and the single thing the audience should remember.
+Talk length, audience, venue format, whether questions are inside or outside the slot, the single thing the audience should remember, and the exact speaker name, affiliation, and venue line. Ask for any of these the manifest does not record.
+
+## Evidence gate
+
+Before writing, build a claim ledger with one row per claim, number, comparison, or figure, each naming its support as a manuscript passage, a `project://sources/{source}` record, a `project://evidence/{evidence}` record, or a named project file path. Cut any row without support; statements about other systems or prior work need a cited source record, never general knowledge. Never invent speaker names, affiliations, emails, funding, venue, or dates; leave a visible placeholder such as `[AFFILIATION NEEDED]` and report it as unresolved. When the subject is software, derive every diagram from named source files or documentation, state those paths on the slide, and leave a labeled placeholder rather than an invented architecture.
 
 ## Budgets
 
@@ -25,7 +29,7 @@ Backup slides sit after the closing slide and answer the questions the work invi
 
 ## [Title slide]
 
-[Title] · [Speaker] · [Affiliation] · [Venue and date]
+[Title] · [Speaker or SPEAKER NEEDED] · [Affiliation or AFFILIATION NEEDED] · [Venue and date or VENUE NEEDED]
 
 ## [The problem, in one image or one sentence]
 
@@ -42,7 +46,7 @@ Backup slides sit after the closing slide and answer the questions the work invi
 
 ## [Approach]
 
-[One diagram. Speaker note: walk it left to right; do not read the labels aloud.]
+[One diagram derived from named source files or documents. Source: [paths]. Speaker note: walk it left to right; do not read the labels aloud.]
 
 ## [Key design decision]
 
@@ -80,4 +84,4 @@ Backup slides sit after the closing slide and answer the questions the work invi
 
 ## Attribution rules
 
-Every number and figure must trace to a manuscript passage or an evidence record. Reused figures carry their original attribution on the slide. Speaker notes are part of the deliverable and follow the same evidence rule as the slides: do not put a claim in a note that the records do not support.
+Every number, figure, and claim must trace to a row in the claim ledger. Reused figures carry their original attribution on the slide. Speaker notes are part of the deliverable and follow the same evidence rule as the slides: do not put a claim in a note that the records do not support.