create-academic-research 0.1.17 → 0.1.18

package/README.md

@@ -41,7 +41,7 @@ npx --yes github:VincenzoImp/create-academic-research my-project
 | Sources | PDFs, derived Markdown, metadata, BibTeX, conversion ledger, source ledger. |
 | Literature Review | Search strategy, screening decisions, literature matrix, SOTA synthesis, gaps, PRISMA flow. |
 | Agent Memory | `AGENTS.md`, capability profile, MCP setup docs, generated MCP snippets, wiki index/log/templates. |
-| Reproducibility | Python package scaffold, tests, experiment registry, output folders, artifact checklist. |
+| Reproducibility | Python package scaffold, tests, experiment registry, autonomous campaign ledgers, output folders, artifact checklist. |
 | Skills | Project-local installation flow for `VincenzoImp/academic-research-skills`. |
 | MCP | Conservative default records for scholarly discovery plus documented optional integrations. |
 
@@ -117,6 +117,7 @@ npm run doctor
 npm run update
 npm run update -- --apply
 npm run setup -- --env-file .env.local
+npm run workflow:literature
 npm run rename -- --title "New Title" --slug new-title --package new_title
 npm run agents:list
 npm run skills:presets
@@ -174,6 +175,23 @@ Safe migrations are tracked in `.academic-research/managed-files.json`. The
 manifest stores non-secret checksums for generator-owned files. If a file was
 edited locally, update reports `skip` instead of overwriting it.
 
+### Migration 0.1.17 -> 0.1.18
+
+Projects created with `0.1.17` can migrate in place:
+
+```bash
+npm run update
+npm run update -- --apply
+npm run doctor
+```
+
+The migration adds the project-quality contract, badge evidence ledger, SOTA
+reading and citation-chasing ledgers, paper synthesis folders, linear reading
+copies, autonomous experiment campaign files, claim-audit and reproduction
+templates, and `workflow:literature`. Locally edited managed files are skipped;
+new research record templates are created as user-owned where the project is
+expected to fill them over time.
+
 `academic-research init` initializes an existing repository without overwriting
 existing files. It adds the research contract, merges lifecycle package scripts,
 and preserves existing README, `.gitignore`, and custom package scripts.
@@ -216,6 +234,11 @@ MCP commands are split by side-effect:
 | `mcp doctor` | Validate enabled MCP records, generated snippets, required env vars, and documented manual prerequisites. Pass `--env-file .env.local` to read explicit local secrets. |
 | `mcp probe` | Opt-in runtime check. Local stdio servers get a JSON-RPC handshake; remote endpoints are reported as configured without a network probe. |
 
+Workflow commands are scenario-level shortcuts over skills and MCP records.
+Use `npm run workflow:literature` when starting a serious SOTA, survey, or
+related-work pass: it selects a practical literature stack with arXiv, DBLP,
+Semantic Scholar, and OpenAlex remote graph search, then prints the next checks.
+
 ## Companion Skills
 
 The generated project works best with:
@@ -269,6 +292,17 @@ a generated safe dotenv-loading wrapper after `mcp setup`.
 Crossref and broad paper-search aggregators are kept as fallback/manual entries
 until a project explicitly needs them.
 
+For SOTA work, the recommended low-friction path is:
+
+```bash
+npm run workflow:literature
+npm run skills:install -- --preset literature
+npm run mcp:status
+npm run mcp:smoke -- --env-file .env.local
+```
+
+Then use `$sota-literature-review` with a declared review scale and seed set.
+
 Codex automatic registration supports custom remote endpoints when the URL is
 stored in project config with `--url`. If the endpoint URL is kept private via
 `--url-env`, Codex automatic registration is not available because the Codex CLI

package/dist/src/cli.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { assertKnownMcpServers, clientAddMcpServer, clientRemoveMcpServer, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, getMcpLifecycleStatus, installMcpTools, installSkillIds, installSkills, formatMcpDotenv, listInstalledSkills, listMcpEnvironmentEntries, mergeMcpEnvironment, mcpToolCommandTexts, probeMcpServers, readCapabilities, readMcpEnvironmentFile, removeSkills, resolveMcpServerForState, setupMcpServer, uninstallMcpTools, updateSkills } from "./capabilities.js";
+import { assertKnownMcpServers, clientAddMcpServer, clientRemoveMcpServer, disableMcpServers, doctorMcpServers, enableMcpServers, DEFAULT_AGENT, getMcpLifecycleStatus, installMcpTools, installSkillIds, installSkills, formatMcpDotenv, listInstalledSkills, listMcpEnvironmentEntries, mergeMcpEnvironment, mcpToolCommandTexts, probeMcpServers, readCapabilities, readMcpEnvironmentFile, removeSkills, resolveMcpServerForState, setupMcpServer, uninstallMcpTools, updateSkills, writeCapabilities } from "./capabilities.js";
 import { createProject, doctorProject, initProject, renameProject, updateProject } from "./project.js";
 import { askCreateOptions } from "./prompts.js";
 import { AGENT_STACK, mcpModeLabel, mcpRecommendedMode, mcpServerModeKeys, mcpSupportedModeLabels, presetMcpServers, resolveMcpServer } from "./stack.js";
@@ -20,6 +20,7 @@ const CREATE_FLAGS = flagSchema([
 ], ["title", "slug", "package", "preset", "profile", "agent"]);
 const ROOT_FLAGS = flagSchema(["help"], ["root"]);
 const SETUP_FLAGS = flagSchema(["help"], ["root", "env-file"]);
+const WORKFLOW_FLAGS = flagSchema(["help"], ["root", "agent", "env-file"]);
 const UPDATE_FLAGS = flagSchema(["help", "dry-run", "apply"], ["root"]);
 const INIT_FLAGS = flagSchema(["help", "install-skills"], ["root", "title", "slug", "package", "preset", "profile", "agent"]);
 const RENAME_FLAGS = flagSchema(["help"], ["root", "title", "slug", "package"]);
@@ -130,6 +131,8 @@ async function lifecycleMain(argv) {
         return skillsCommand(argv.slice(1));
     if (command === "mcp")
         return mcpCommand(argv.slice(1));
+    if (command === "workflow")
+        return workflowCommand(argv.slice(1));
     printLifecycleHelp();
     return command === "help" ? 0 : 1;
 }
@@ -624,6 +627,49 @@ async function mcpCommand(argv) {
     }
     throw new Error(`unknown mcp command: ${subcommand}`);
 }
+async function workflowCommand(argv) {
+    const subcommand = argv[0] ?? "help";
+    const parsed = parseFlags(argv.slice(1), WORKFLOW_FLAGS);
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h" || flagBool(parsed.flags, "help")) {
+        printWorkflowHelp();
+        return 0;
+    }
+    if (subcommand !== "literature")
+        throw new Error(`unknown workflow command: ${subcommand}`);
+    assertNoArguments(parsed.positionals, "workflow literature");
+    const root = resolve(flagString(parsed.flags, "root") ?? ".");
+    const state = await readCapabilities(root);
+    const agent = flagString(parsed.flags, "agent") ?? state.agent;
+    const literatureServers = ["arxiv", "dblp", "semantic-scholar", "openalex"];
+    await writeCapabilities(root, {
+        ...state,
+        agent,
+        preset: "literature",
+        mcp_servers: literatureServers,
+        mcp_server_modes: {
+            ...state.mcp_server_modes,
+            openalex: "remote"
+        },
+        mcp_server_remote: state.mcp_server_remote
+    });
+    const env = await mcpCommandEnvironment(root, parsed.flags);
+    const lifecycle = await getMcpLifecycleStatus(root, { env });
+    const selected = lifecycle.servers.filter((server) => server.selected);
+    console.log("Literature Workflow");
+    console.log(`root\t${root}`);
+    console.log("preset\tliterature");
+    console.log(`mcp_selected\t${literatureServers.join(",")}`);
+    for (const item of selected) {
+        console.log(`mcp\t${item.id}\t${item.mode}\t${item.state}\t${friendlyNext(item.next)}`);
+    }
+    console.log("");
+    console.log("Next Commands");
+    console.log("npm run skills:install -- --preset literature");
+    console.log("npm run mcp:status");
+    console.log("npm run mcp:smoke -- --env-file .env.local");
+    console.log("Use $sota-literature-review with a declared scale, seed set, and citation-chasing budget.");
+    return 0;
+}
 async function mcpClientCommand(parsed) {
     const action = parsed.positionals[0];
     const server = parsed.positionals[1];
@@ -947,7 +993,7 @@ function printMissingTargetHelp() {
 }
 function printLifecycleHelp() {
     console.log([
-        "Usage: academic-research <doctor|update|init|setup|rename|agents|skills|mcp>",
+        "Usage: academic-research <doctor|update|init|setup|rename|agents|skills|mcp|workflow>",
         "",
         "Manage a generated academic research repository after creation.",
         "",
@@ -956,6 +1002,22 @@ function printLifecycleHelp() {
         "  -v, --version            Show package version."
     ].join("\n"));
 }
+function printWorkflowHelp() {
+    console.log([
+        "Usage: academic-research workflow <literature> [options]",
+        "",
+        "Prepare scenario-level research workflows without manually stitching every skill and MCP command.",
+        "",
+        "Workflows:",
+        "  literature                Configure the practical SOTA stack for arXiv, DBLP, Semantic Scholar citation graph, and OpenAlex graph search.",
+        "",
+        "Options:",
+        "  --root <path>             Project root. Default: current directory.",
+        "  --agent <id>              Agent target for generated MCP snippets.",
+        "  --env-file <path>         Read local env values for readiness reporting.",
+        "  -h, --help                Show this help."
+    ].join("\n"));
+}
 function printUpdateHelp() {
     console.log([
         "Usage: academic-research update [options]",

package/dist/src/project.js

@@ -49,6 +49,16 @@ const REQUIRED_CSV_COLUMNS = {
         "expected_fix",
         "checked_on"
     ],
+    "artifacts/badge-evidence-ledger.csv": [
+        "badge_target",
+        "evidence_id",
+        "evidence_path",
+        "claim_or_result_id",
+        "artifact_component",
+        "command_or_procedure",
+        "validation_status",
+        "checked_on"
+    ],
     "sota/literature-matrix.csv": [
         "source_id",
         "title",
@@ -62,10 +72,38 @@ const REQUIRED_CSV_COLUMNS = {
         "metric_or_result",
         "limitations",
         "relevance",
+        "full_text_status",
+        "reading_status",
+        "synthesis_path",
         "citation_count_or_signal",
-        "identifiers"
+        "identifiers",
+        "bib_key",
+        "role"
     ],
     "sota/screening-decisions.csv": ["stage", "source_id", "title", "decision", "reason", "screened_by", "date"],
+    "sota/reading-log.csv": [
+        "source_id",
+        "role",
+        "reading_copy_path",
+        "start_location",
+        "end_location",
+        "status",
+        "reader",
+        "started_on",
+        "completed_on"
+    ],
+    "sota/citation-chasing-log.csv": [
+        "round",
+        "seed_source_id",
+        "direction",
+        "tool_or_database",
+        "query_or_graph_call",
+        "found_count",
+        "new_after_dedup",
+        "promoted_to_seed_count",
+        "screening_status",
+        "date"
+    ],
     "experiments/registry.csv": [
         "run_id",
         "date",
@@ -83,6 +121,16 @@ const REQUIRED_CSV_COLUMNS = {
         "record_path"
     ]
 };
+const REQUIRED_TSV_COLUMNS = {
+    "experiments/campaigns/frontier-results.tsv": [
+        "run_id",
+        "git_commit",
+        "metric_value",
+        "resource_value",
+        "status",
+        "description"
+    ]
+};
 export async function createProject(options) {
     const target = resolve(options.target);
     if (await isNonEmptyDirectory(target)) {
@@ -188,10 +236,28 @@ export async function doctorProject(root) {
         "docs/agent/capability-profile.md",
         "docs/agent/mcp-setup.md",
         "docs/agent/mcp-client-setup.md",
+        "docs/agent/output-contracts.md",
+        "docs/agent/project-quality.md",
+        "docs/agent/repo-migration-playbook.md",
         "docs/agent/generated",
+        "docs/reproducibility/commands.md",
         "scripts/README.md",
+        "analysis_outputs/claim-audit.md",
+        "artifacts/badge-evidence-ledger.csv",
+        "experiments/campaigns/autonomous-campaign-template.md",
+        "experiments/campaigns/frontier-results.tsv",
+        "repro_outputs/SUMMARY.md",
+        "repro_outputs/COMMANDS.md",
+        "repro_outputs/LOG.md",
+        "repro_outputs/PATCHES.md",
+        "repro_outputs/status.json",
+        "sources/markdown-linear",
         "sources/source-ledger.csv",
+        "sota/reading-log.csv",
+        "sota/citation-chasing-log.csv",
         "sota/literature-matrix.csv",
+        "sota/paper-syntheses",
+        "reports/paper/sota-survey.tex",
         "wiki/index.md",
         "wiki/log.md",
         "wiki/templates/source-page.md",
@@ -304,6 +370,9 @@ export async function doctorProject(root) {
     for (const [relative, requiredColumns] of Object.entries(REQUIRED_CSV_COLUMNS)) {
         await validateCsvHeader(target, relative, requiredColumns, errors);
     }
+    for (const [relative, requiredColumns] of Object.entries(REQUIRED_TSV_COLUMNS)) {
+        await validateDelimitedHeader(target, relative, requiredColumns, "\t", errors);
+    }
     return { ok: errors.length === 0, errors, warnings };
 }
 async function personalizeInitializedProject(root, { title, slug, packageName, profile }, created) {
@@ -429,6 +498,69 @@ async function managedFileSpecs(root) {
         { path: ".env.example", policy: "managed", content: formatMcpDotenv(Object.keys(AGENT_STACK.mcp_servers)) },
         { path: "configs/agent-stack.yaml", policy: "managed", content: YAML.stringify(AGENT_STACK) },
         { path: "docs/getting-started.md", policy: "managed", content: await templateText("docs/getting-started.md") },
+        {
+            path: "docs/agent/output-contracts.md",
+            policy: "managed",
+            content: await templateText("docs/agent/output-contracts.md")
+        },
+        {
+            path: "docs/agent/project-quality.md",
+            policy: "managed",
+            content: await templateText("docs/agent/project-quality.md")
+        },
+        {
+            path: "docs/agent/repo-migration-playbook.md",
+            policy: "user-owned",
+            content: await templateText("docs/agent/repo-migration-playbook.md")
+        },
+        {
+            path: "docs/reproducibility/commands.md",
+            policy: "user-owned",
+            content: await templateText("docs/reproducibility/commands.md")
+        },
+        {
+            path: "analysis_outputs/claim-audit.md",
+            policy: "user-owned",
+            content: await templateText("analysis_outputs/claim-audit.md")
+        },
+        {
+            path: "sources/markdown-linear/.gitkeep",
+            policy: "managed",
+            content: await templateText("sources/markdown-linear/.gitkeep")
+        },
+        { path: "sota/reading-log.csv", policy: "managed", content: await templateText("sota/reading-log.csv") },
+        {
+            path: "sota/citation-chasing-log.csv",
+            policy: "managed",
+            content: await templateText("sota/citation-chasing-log.csv")
+        },
+        {
+            path: "sota/paper-syntheses/.gitkeep",
+            policy: "managed",
+            content: await templateText("sota/paper-syntheses/.gitkeep")
+        },
+        { path: "reports/paper/sota-survey.tex", policy: "managed", content: await templateText("reports/paper/sota-survey.tex") },
+        { path: "artifacts/artifact-checklist.md", policy: "managed", content: await templateText("artifacts/artifact-checklist.md") },
+        {
+            path: "artifacts/badge-evidence-ledger.csv",
+            policy: "managed",
+            content: await templateText("artifacts/badge-evidence-ledger.csv")
+        },
+        {
+            path: "experiments/campaigns/autonomous-campaign-template.md",
+            policy: "managed",
+            content: await templateText("experiments/campaigns/autonomous-campaign-template.md")
+        },
+        {
+            path: "experiments/campaigns/frontier-results.tsv",
+            policy: "managed",
+            content: await templateText("experiments/campaigns/frontier-results.tsv")
+        },
+        { path: "repro_outputs/SUMMARY.md", policy: "user-owned", content: await templateText("repro_outputs/SUMMARY.md") },
+        { path: "repro_outputs/COMMANDS.md", policy: "user-owned", content: await templateText("repro_outputs/COMMANDS.md") },
+        { path: "repro_outputs/LOG.md", policy: "user-owned", content: await templateText("repro_outputs/LOG.md") },
+        { path: "repro_outputs/PATCHES.md", policy: "user-owned", content: await templateText("repro_outputs/PATCHES.md") },
+        { path: "repro_outputs/status.json", policy: "user-owned", content: await templateText("repro_outputs/status.json") },
         {
             path: "docs/agent/mcp-client-setup.md",
             policy: "managed",
@@ -470,6 +602,7 @@ function generatedLifecycleScripts(packageSpec) {
         doctor: `${command} doctor`,
         update: `${latestCommand} update`,
         setup: `${command} setup`,
+        "workflow:literature": `${command} workflow literature`,
         rename: `${command} rename`,
         "agents:list": `${command} agents list`,
         "skills:install": `${command} skills install`,
@@ -955,11 +1088,14 @@ function toPosix(value) {
     return value.split(/[\\/]/).join("/");
 }
 async function validateCsvHeader(root, relative, requiredColumns, errors) {
+    await validateDelimitedHeader(root, relative, requiredColumns, ",", errors);
+}
+async function validateDelimitedHeader(root, relative, requiredColumns, delimiter, errors) {
     const path = join(root, relative);
     if (!(await exists(path)))
         return;
     const header = (await readFile(path, "utf8")).split(/\r?\n/, 1)[0] ?? "";
-    const columns = new Set(header.split(",").map((column) => column.trim()).filter(Boolean));
+    const columns = new Set(header.split(delimiter).map((column) => column.trim()).filter(Boolean));
     for (const column of requiredColumns) {
         if (!columns.has(column))
             errors.push(`${relative} missing column ${column}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-academic-research",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Scaffold agent-ready academic research repositories with SOTA, source ledgers, wiki memory, MCP setup, and project-local skills.",
   "type": "module",
   "license": "MIT",

package/template/AGENTS.md

@@ -20,8 +20,9 @@ scholarly record.
 2. `configs/default.yaml`
 3. `configs/capabilities.yaml`
 4. `docs/agent/capability-profile.md`
-5. `docs/agent/research-program.md`
-6. `wiki/index.md`
+5. `docs/agent/project-quality.md`
+6. `docs/agent/research-program.md`
+7. `wiki/index.md`
 
 ## Standard Workflow
 
@@ -31,6 +32,14 @@ scholarly record.
 4. Add tests or validation for code and structural changes.
 5. Update `wiki/log.md` and affected wiki/docs pages before finishing.
 
+## Project Quality
+
+- Keep every user request inside the project quality contract in `docs/agent/project-quality.md`.
+- Put each artifact in its correct work zone: exploratory, debug, analysis, reproduction, final output, report, source, or release.
+- Promote outputs only when inputs, command/procedure, validation, limitations, and linked claims are recorded.
+- Update `artifacts/badge-evidence-ledger.csv` whenever a task creates evidence for artifact availability, functionality, reusability, reproduction, or replication.
+- The user guides the research direction; agents preserve internal order, provenance, and validation discipline.
+
 ## Memory Contract
 
 - `wiki/log.md` is chronological and append-only.
@@ -45,9 +54,21 @@ scholarly record.
 
 - Native PDFs and reports go in `sources/pdfs/`.
 - Derived Markdown goes in `sources/markdown/`.
+- Linear reading copies go in `sources/markdown-linear/`.
 - Metadata goes in `sources/metadata/`.
 - Bibliography records go in `sources/bib/references.bib`.
 - Citation issues go in `sources/bib/citation-audit.csv`.
 - SOTA records go in `sota/`.
+- Core/supporting paper syntheses go in `sota/paper-syntheses/`.
+- Full-text reading progress goes in `sota/reading-log.csv`.
+- Citation graph expansion goes in `sota/citation-chasing-log.csv`.
 - Curated experiment records go in `experiments/`.
 - Repeatable command entrypoints go in `scripts/`.
+
+## SOTA Discipline
+
+- Run `npm run workflow:literature` before serious SOTA, survey, or related-work work.
+- Declare the review scale: quick-scan, focused-sota, or full-survey.
+- Use citation chasing in both directions from seeds; record rounds and stopping conditions.
+- Do not use abstract-only records for durable claims.
+- For core/supporting papers, acquire full text, read linearly, create a per-paper synthesis, normalize the BibTeX entry, then cite.

package/template/README.md

@@ -40,8 +40,10 @@ npm run update
 - `sota/`: search strategy, screening, literature matrix, synthesis, and gaps.
 - `wiki/`: LLM-maintained durable research memory.
 - `docs/agent/`: active agent workflows, capability profile, and MCP setup.
+- `docs/agent/project-quality.md`: cross-project quality, hygiene, and badge-readiness contract.
 - `docs/methodology/`: research design, evaluation plan, and validity threats.
 - `experiments/`: curated experiment registry and run records.
+- `experiments/campaigns/`: autonomous campaign templates and frontier result ledgers.
 - `scripts/`: thin repeatable entrypoints that call reusable code in `src/`.
 - `notebooks/`: optional exploratory and narrative notebooks.
 - `outputs/`: final figures, tables, models, and paper-supporting derived assets.
@@ -63,6 +65,7 @@ npm run skills:list
 npm run skills:status
 npm run update
 npm run setup
+npm run workflow:literature
 npm run mcp:dotenv
 npm run mcp:list
 npm run mcp:modes
@@ -104,6 +107,22 @@ npm exec --yes --package=create-academic-research@latest -- academic-research up
 npm exec --yes --package=create-academic-research@latest -- academic-research update --root . --apply
 ```
 
+### Migration 0.1.17 -> 0.1.18
+
+Projects created with `0.1.17` can migrate in place:
+
+```bash
+npm run update
+npm run update -- --apply
+npm run doctor
+```
+
+The migration adds the project-quality contract, badge evidence ledger, SOTA
+reading and citation-chasing ledgers, paper synthesis folders, linear reading
+copies, autonomous experiment campaign files, claim-audit and reproduction
+templates, and `workflow:literature`. Locally edited managed files are skipped;
+new research record templates are created for the project to fill over time.
+
 `.env.example` is the committed MCP environment reference. Regenerate it with
 `npm run mcp:dotenv`. Copy it to `.env.local`, your shell profile, or your MCP
 client secret store when secrets are needed. Filled `.env` files are ignored by
@@ -137,3 +156,17 @@ and Overleaf should be enabled only after reading `docs/agent/mcp-setup.md` and
 checking their prerequisites with `mcp env`.
 
 See `docs/getting-started.md` for the recommended first session workflow.
+
+For a serious SOTA or survey, start with:
+
+```bash
+npm run workflow:literature
+npm run skills:install -- --preset literature
+npm run mcp:status
+npm run mcp:smoke -- --env-file .env.local
+```
+
+This configures arXiv, DBLP, Semantic Scholar, and OpenAlex remote graph search
+as the practical citation-discovery stack. MCP output still becomes evidence
+only after source ingestion, full-text reading, bibliography normalization, and
+claim audit.

package/template/_gitignore

@@ -30,12 +30,18 @@ outputs/**
 analysis_outputs/**
 !analysis_outputs/
 !analysis_outputs/.gitkeep
+!analysis_outputs/claim-audit.md
 debug_outputs/**
 !debug_outputs/
 !debug_outputs/.gitkeep
 repro_outputs/**
 !repro_outputs/
 !repro_outputs/.gitkeep
+!repro_outputs/COMMANDS.md
+!repro_outputs/LOG.md
+!repro_outputs/PATCHES.md
+!repro_outputs/SUMMARY.md
+!repro_outputs/status.json
 train_outputs/**
 !train_outputs/
 !train_outputs/.gitkeep

package/template/analysis_outputs/claim-audit.md

@@ -0,0 +1,7 @@
+# Claim Audit
+
+Use this file for claim-by-claim verification notes before promoting text into
+papers, reports, README claims, or durable wiki synthesis.
+
+| claim_id | claim | class | cited_source | evidence_path | support_span | verdict | fix |
+|---|---|---|---|---|---|---|---|

package/template/artifacts/artifact-checklist.md

@@ -1,7 +1,59 @@
 # Artifact Checklist
 
+# ACM Artifact Review And Badging
+
+Use this file to prepare for ACM artifact review and related open-science
+expectations. Badge families are independent: availability, artifact
+evaluation, and result validation.
+
+## Artifact Scope
+
 - Code release scope:
 - Data release scope:
-- Environment instructions:
+- Model/checkpoint scope:
+- Paper claims supported:
+- Excluded private or restricted material:
+
+## Artifacts Available
+
+- Archival repository:
+- DOI or stable identifier:
 - License:
-- Reproduction command:
+- Citation:
+- Public access restrictions:
+- Version/tag matching the paper:
+
+## Artifacts Evaluated: Functional
+
+- Install command:
+- Smoke test:
+- Expected smoke-test output:
+- Hardware and OS:
+- Runtime:
+- Required data:
+- Known limitations:
+
+## Artifacts Evaluated: Reusable
+
+- Documented structure:
+- Configuration files:
+- Small example dataset or synthetic fixture:
+- Extension points:
+- Parameter/seed documentation:
+- Maintenance notes:
+
+## Results Validated
+
+- Results Reproduced by same artifact:
+- Results Replicated by independent artifact:
+- Full reproduction command:
+- Expected outputs:
+- Comparison tolerance:
+- Result-to-claim mapping:
+
+## Governance
+
+- Ethics/license constraints:
+- Sensitive data handling:
+- External dependency risks:
+- Credentials excluded from release:

package/template/artifacts/badge-evidence-ledger.csv

@@ -0,0 +1 @@
+badge_target,evidence_id,evidence_path,claim_or_result_id,artifact_component,command_or_procedure,validation_status,checked_on,notes

package/template/docs/agent/mcp-client-setup.md

@@ -97,14 +97,15 @@ snippet, a supported client registration path, and the next setup action.
 
 ## Workflow
 
-1. Enable only the MCP servers needed for the current research task.
-2. Inspect prerequisites with `npm run mcp:env -- <server>`.
-3. Put required secrets in the MCP client secret store, shell, or `.env.local`.
-4. Run `npm run mcp:smoke -- --env-file .env.local`.
-5. Run `npm run mcp:status`.
-6. Register the selected server with the active client, or load the generated
+1. For SOTA or survey work, run `npm run workflow:literature` before manual MCP selection.
+2. Enable only the MCP servers needed for the current research task.
+3. Inspect prerequisites with `npm run mcp:env -- <server>`.
+4. Put required secrets in the MCP client secret store, shell, or `.env.local`.
+5. Run `npm run mcp:smoke -- --env-file .env.local`.
+6. Run `npm run mcp:status`.
+7. Register the selected server with the active client, or load the generated
    snippet manually.
-7. Run `npm run mcp:probe -- <server>` only when you want to start
+8. Run `npm run mcp:probe -- <server>` only when you want to start
    the server and verify a real stdio handshake.
-8. Treat MCP output as retrieval metadata until it is ingested into repository
+9. Treat MCP output as retrieval metadata until it is ingested into repository
    source records.

package/template/docs/agent/mcp-setup.md

@@ -19,6 +19,18 @@ local app, and manual setup.
 Use `npm run mcp:status -- --verbose` when you need technical mode names,
 snippet state, client registration state, and probe details.
 
+For literature review work, prefer the scenario command before manual MCP
+selection:
+
+```bash
+npm run workflow:literature
+npm run mcp:status
+npm run mcp:smoke -- --env-file .env.local
+```
+
+This selects arXiv, DBLP, Semantic Scholar, and OpenAlex remote graph search as
+the default SOTA discovery stack.
+
 `configs/capabilities.yaml` records intended project capability state.
 `docs/agent/capability-lock.json` records non-secret observed setup facts for
 MCP setup/client/probe actions and project-local skill operations. The scaffold

package/template/docs/agent/output-contracts.md

@@ -1,8 +1,52 @@
 # Output Contracts
 
-- `repro_outputs/`: trusted reproduction evidence.
-- `train_outputs/`: training run evidence.
-- `explore_outputs/`: exploratory variants.
-- `analysis_outputs/`: analysis reports and claim audits.
-- `debug_outputs/`: diagnosis artifacts.
+Use this file with `docs/agent/project-quality.md` before writing generated or
+derived material. The Project Quality Contract decides when an output can move
+from exploratory work to trusted project evidence.
+
+## Trust Levels
+
+- `explore_outputs/`: exploratory variants, early hypotheses, and caveated runs.
+- `debug_outputs/`: diagnosis artifacts for failures, data issues, or scientific bugs.
+- `analysis_outputs/`: analysis reports, audits, intermediate tables, and draft figures.
+- `repro_outputs/`: trusted reproduction evidence for external or internal results.
+- `train_outputs/`: trusted training run evidence when model training is part of the research.
 - `outputs/`: curated paper-facing figures, tables, models, and exportable derived assets.
+
+## Research Records
+
+- `sources/`: immutable source evidence, metadata, derived Markdown, and BibTeX.
+- `sources/markdown-linear/`: cover-to-cover reading copies for core/supporting papers.
+- `sota/`: search strategies, screening, literature matrix, syntheses, gaps, and logs.
+- `sota/paper-syntheses/`: structured full-text syntheses for core/supporting papers.
+- `sota/reading-log.csv`: full-text reading progress.
+- `sota/citation-chasing-log.csv`: backward/forward citation expansion rounds.
+- `experiments/`: curated experiment registry and human-readable run records.
+- `experiments/campaigns/`: autonomous or overnight campaign plans and frontier ledgers.
+- `experiments/campaigns/frontier-results.tsv`: machine-readable frontier ledger for `keep`, `discard`, and `crash` campaign outcomes.
+- `reports/paper/sota-survey.tex`: survey-scale LaTeX draft when the task asks for a SOTA chapter or survey.
+- `artifacts/badge-evidence-ledger.csv`: badge evidence paths, linked claims/results, procedures, and validation status.
+
+## Promotion Rules
+
+Do not promote an output into `outputs/`, `repro_outputs/`, `train_outputs/`,
+`reports/`, or `artifacts/` until it names:
+
+- input sources, datasets, or run records
+- command, script, notebook, or manual procedure
+- environment or dependency notes
+- expected output or validation criterion
+- linked claim, research question, experiment, source, or artifact checklist row
+- known limitations
+
+If any item is missing, keep the material in `explore_outputs/`,
+`analysis_outputs/`, or `debug_outputs/` and record the gap in the relevant
+wiki page, ledger, or checklist.
+
+## Badge Evidence
+
+When an output supports artifact availability, functionality, reusability,
+reproduction, or replication, update both:
+
+- `artifacts/artifact-checklist.md`
+- `artifacts/badge-evidence-ledger.csv`

package/template/docs/agent/project-quality.md

@@ -0,0 +1,80 @@
+# Project Quality Contract
+
+This repository should stay usable for an entire academic research project, not
+only for the current task. Every agent action should leave durable state,
+evidence, and outputs in the right place.
+
+## Request Intake
+
+Before acting, classify the user's request:
+
+- idea, question, or positioning
+- source, PDF, bibliography, or SOTA work
+- experiment, reproduction, analysis, or artifact work
+- manuscript, LaTeX, review, rebuttal, or venue work
+- project maintenance, MCP, skills, or repository hygiene
+
+Route through the narrowest matching skill. If multiple workflows are involved,
+update the durable records for each workflow instead of relying on chat history.
+
+## Clean Work Zones
+
+- `sources/`: immutable source evidence and derived reading copies.
+- `sota/`: search protocol, screening, matrix, syntheses, gaps, and citation-chasing logs.
+- `experiments/`: curated run registry and human-readable experiment records.
+- `experiments/campaigns/`: bounded autonomous campaign plans and frontier ledgers.
+- `explore_outputs/`: exploratory work that is not trusted evidence.
+- `debug_outputs/`: diagnostic artifacts.
+- `analysis_outputs/`: analysis reports and audit outputs.
+- `repro_outputs/`: trusted reproduction evidence.
+- `outputs/`: final paper-facing tables, figures, models, and exports.
+- `reports/`: proposal, manuscript, slides, reviews, rebuttal, and LaTeX.
+- `artifacts/`: release package, badge evidence, public artifact preparation.
+- `wiki/`: durable project memory, claims, decisions, contradictions, questions.
+
+Do not mix exploratory, trusted, raw, and final outputs. Promote artifacts only
+when provenance, command, input, and validation are recorded.
+
+## Trusted Outputs
+
+An output becomes trusted only when it has:
+
+- input sources or datasets
+- command, script, notebook, or manual procedure
+- environment or dependency notes
+- expected output or validation criterion
+- linked claim, research question, experiment, or source record
+- known limitations
+
+If any of these are missing, keep the output in `explore_outputs/`,
+`analysis_outputs/`, or `debug_outputs/` and record the gap.
+
+## Project Hygiene Gate
+
+Before finishing a task:
+
+- update the relevant ledger, matrix, wiki page, or checklist
+- keep raw sources immutable
+- keep reusable logic in `src/` and thin commands in `scripts/`
+- keep generated caches, secrets, private data, and bulky outputs out of git
+- reconcile bibliography keys, source IDs, run IDs, and claim IDs
+- mark unresolved questions in `wiki/open_questions.md`
+- append durable changes to `wiki/log.md`
+- run the smallest meaningful validation command
+
+## Badge Readiness
+
+Badge evidence should accumulate throughout the project. When a task affects
+code, data, benchmarks, models, experiments, reproduction, or release material,
+update `artifacts/badge-evidence-ledger.csv` and `artifacts/artifact-checklist.md`.
+
+Map work to these targets:
+
+- Artifacts Available
+- Artifacts Evaluated: Functional
+- Artifacts Evaluated: Reusable
+- Results Reproduced
+- Results Replicated
+
+Do not wait for submission week to recover install commands, expected outputs,
+data access notes, or result-to-claim mappings.

package/template/docs/agent/repo-migration-playbook.md

@@ -0,0 +1,20 @@
+# Repo Migration Playbook
+
+Use this playbook when migrating an existing archive, notebook pile, external
+research repository, or ad hoc project into this scaffold.
+
+## Source Inventory
+
+| source_path | type | destination | preserve_as_raw | notes |
+|---|---|---|---|---|
+
+## Migration Plan
+
+| step | action | target_path | validation | status |
+|---|---|---|---|---|
+
+## Decisions
+
+Record structure decisions, skipped files, incompatible assumptions, and
+follow-up checks here. Keep original evidence immutable until provenance is
+recorded.

package/template/docs/getting-started.md

@@ -29,6 +29,10 @@ npm exec --yes --package=create-academic-research@latest -- academic-research up
 npm exec --yes --package=create-academic-research@latest -- academic-research update --root . --apply
 ```
 
+Read `docs/agent/project-quality.md` before substantive work. It defines where
+each class of source, SOTA record, experiment, analysis, LaTeX file, artifact,
+and final output belongs.
+
 ## 2. Install Project-Local Skills
 
 Install the default academic research skill package:
@@ -66,13 +70,30 @@ npm run mcp:smoke -- --env-file .env.local
 npm run mcp:probe -- arxiv --timeout-ms 5000
 ```
 
-## 4. Start Source Work
+## 4. Prepare The Literature Workflow
+
+For SOTA, survey, or related-work tasks, configure the practical citation graph
+stack before broad searching:
+
+```bash
+npm run workflow:literature
+npm run skills:install -- --preset literature
+npm run mcp:status
+npm run mcp:smoke -- --env-file .env.local
+```
+
+This selects arXiv, DBLP, Semantic Scholar, and OpenAlex remote graph search.
+Use `$sota-literature-review` with a declared scale: `quick-scan`,
+`focused-sota`, or `full-survey`.
+
+## 5. Start Source Work
 
 Put source originals and metadata in the source layer before synthesis.
 
 ```text
 sources/pdfs/       native PDFs
 sources/markdown/   derived Markdown
+sources/markdown-linear/ cover-to-cover reading copies
 sources/metadata/   downloaded metadata or query exports
 sources/bib/        BibTeX and citation audits
 ```
@@ -80,16 +101,20 @@ sources/bib/        BibTeX and citation audits
 Update `sources/source-ledger.csv` whenever a paper, report, dataset, or web
 source becomes evidence for the project.
 
-## 5. Build The First SOTA Pass
+## 6. Build The First SOTA Pass
 
 Use `sota/search-strategy.md` to record search terms, databases, dates, and
-inclusion criteria. Put screened sources in `sota/literature-matrix.csv`, then
-summarize stable conclusions in `sota/synthesis.md`.
+inclusion criteria. Record full-text reading in `sota/reading-log.csv` and
+citation expansion in `sota/citation-chasing-log.csv`. Put screened sources in
+`sota/literature-matrix.csv`, create per-paper syntheses in
+`sota/paper-syntheses/`, then summarize stable conclusions in
+`sota/synthesis.md`.
 
 Do not treat MCP output as final evidence until the relevant source has been
-ingested, deduplicated, and tied to a source record.
+ingested, deduplicated, read in full when core/supporting, and tied to a source
+record and bibliography key.
 
-## 6. Keep Durable Memory Current
+## 7. Keep Durable Memory Current
 
 Update the wiki when project knowledge changes:
 

package/template/docs/reproducibility/commands.md

@@ -0,0 +1,12 @@
+# Reproducibility Commands
+
+Record commands that a reviewer or future researcher can run without relying on
+chat history.
+
+| command_id | purpose | command | working_dir | inputs | expected_output | last_checked |
+|---|---|---|---|---|---|---|
+
+## Environment Notes
+
+Record dependency files, hardware assumptions, external services, data access
+steps, and known runtime limits here.

package/template/experiments/campaigns/autonomous-campaign-template.md

@@ -0,0 +1,68 @@
+# Autonomous Experiment Campaign
+
+Use this template for bounded autonomous or overnight experiment loops. The goal
+is to let an agent iterate without losing scientific comparability.
+
+## Research Question
+
+<fill: question or optimization target>
+
+## Mutability Envelope
+
+- Editable files or modules:
+- Read-only files or modules:
+- Allowed dependency changes:
+- Forbidden changes:
+
+## Frozen Harness
+
+- Dataset and split:
+- Evaluation script or function:
+- Metric and direction:
+- Resource measure:
+- Time or compute budget:
+- Hardware or runtime constraints:
+
+## Baseline Run
+
+- Baseline commit:
+- Command:
+- Metric value:
+- Resource value:
+- Output path:
+
+## Frontier Tracking
+
+Record every candidate in `experiments/campaigns/frontier-results.tsv`.
+
+Statuses: keep, discard, crash.
+
+- `keep`: candidate improves the agreed metric or simplifies without degrading.
+- `discard`: candidate runs but does not improve enough to keep.
+- `crash`: candidate fails, times out, or exceeds resource limits.
+
+Keep `explore_outputs/` for raw exploratory logs, `debug_outputs/` for crash
+diagnosis, and promote only trusted evidence to `train_outputs/`,
+`repro_outputs/`, or `outputs/`.
+
+## Loop Procedure
+
+1. Check git state and current best result.
+2. Make one candidate change inside the mutability envelope.
+3. Commit or otherwise snapshot the candidate before running.
+4. Run the exact command with bounded output capture.
+5. Extract metric, resource value, runtime, and status.
+6. Append the result to `frontier-results.tsv`.
+7. Keep, discard, or diagnose according to the campaign policy.
+8. Stop only at the declared stop condition or when scientific meaning changes.
+
+## Stop Conditions
+
+- Maximum runs:
+- Maximum wall-clock time:
+- Minimum meaningful improvement:
+- Human approval required when:
+
+## Notes
+
+<fill: interpretation, surprising findings, or next hypotheses>

package/template/experiments/campaigns/frontier-results.tsv

@@ -0,0 +1 @@
+run_id	git_commit	metric_value	resource_value	status	description

package/template/package.json

@@ -6,6 +6,7 @@
     "doctor": "npm exec --yes --package=create-academic-research@latest -- academic-research doctor",
     "update": "npm exec --yes --package=create-academic-research@latest -- academic-research update",
     "setup": "npm exec --yes --package=create-academic-research@latest -- academic-research setup",
+    "workflow:literature": "npm exec --yes --package=create-academic-research@latest -- academic-research workflow literature",
     "rename": "npm exec --yes --package=create-academic-research@latest -- academic-research rename",
     "agents:list": "npm exec --yes --package=create-academic-research@latest -- academic-research agents list",
     "skills:install": "npm exec --yes --package=create-academic-research@latest -- academic-research skills install",
@@ -35,6 +36,6 @@
     "mcp:probe": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp probe"
   },
   "devDependencies": {
-    "create-academic-research": "0.1.14"
+    "create-academic-research": "0.1.18"
   }
 }

package/template/reports/paper/sota-survey.tex

@@ -0,0 +1,29 @@
+\section{State of the Art}
+\label{sec:sota}
+
+\subsection{Search Protocol}
+\label{sec:sota-search-protocol}
+Describe the review scale, seed sources, databases, exact queries, date ranges,
+filters, citation-chasing depth, inclusion criteria, exclusion criteria, and
+known blind spots recorded in \texttt{sota/search-strategy.md}.
+
+\subsection{Methodological Families}
+\label{sec:sota-method-families}
+Synthesize methods by family. Cite only entries present in
+\texttt{sources/bib/references.bib} and \texttt{sota/literature-matrix.csv}.
+
+\subsection{Evidence And Findings}
+\label{sec:sota-findings}
+Report established findings, contested findings, datasets, metrics, baselines,
+and limitations. Do not promote abstract-only or unaudited claims.
+
+\subsection{Implications For This Project}
+\label{sec:sota-project-implications}
+Connect the literature to the current research idea, nearest prior work,
+publishable deltas, failure conditions, and evidence still needed.
+
+\subsection{Open Directions}
+\label{sec:sota-open-directions}
+List research directions derived from \texttt{sota/gaps.md}. Each direction
+should name the supporting evidence, nearest prior work, method, risk, and
+artifact or evaluation requirement.

package/template/repro_outputs/COMMANDS.md

@@ -0,0 +1,4 @@
+# Reproduction Commands
+
+| command_id | purpose | command | working_dir | expected_output | status |
+|---|---|---|---|---|---|

package/template/repro_outputs/LOG.md

@@ -0,0 +1,6 @@
+# Reproduction Log
+
+Append dated reproduction attempts here.
+
+| date | command_id | status | output_path | notes |
+|---|---|---|---|---|

package/template/repro_outputs/PATCHES.md

@@ -0,0 +1,7 @@
+# Reproduction Patches
+
+Record any patches needed to run an external artifact. Keep patch notes separate
+from scientific claims.
+
+| patch_id | file_or_component | reason | effect | status |
+|---|---|---|---|---|

package/template/repro_outputs/SUMMARY.md

@@ -0,0 +1,21 @@
+# Reproduction Summary
+
+Use this summary for trusted reproduction attempts only. Exploratory debugging
+belongs in `debug_outputs/` or `explore_outputs/`.
+
+## Target
+
+- Artifact:
+- Paper or claim:
+- Repository or dataset:
+
+## Status
+
+- Overall status: not-started
+- Last checked:
+- Main blocker:
+
+## Result Mapping
+
+| claim_or_result_id | command_id | observed_output | verdict | notes |
+|---|---|---|---|---|

package/template/repro_outputs/status.json

@@ -0,0 +1,9 @@
+{
+  "status": "not-started",
+  "target": "",
+  "checked_on": "",
+  "summary": "repro_outputs/SUMMARY.md",
+  "commands": "repro_outputs/COMMANDS.md",
+  "log": "repro_outputs/LOG.md",
+  "patches": "repro_outputs/PATCHES.md"
+}

package/template/sota/citation-chasing-log.csv

@@ -0,0 +1 @@
+round,seed_source_id,direction,tool_or_database,query_or_graph_call,found_count,new_after_dedup,promoted_to_seed_count,screening_status,date,notes

package/template/sota/literature-matrix.csv

@@ -1 +1 @@
-source_id,title,authors,year,venue,method,dataset_or_sample,task_or_problem,key_claim,metric_or_result,limitations,relevance,citation_count_or_signal,identifiers,notes
+source_id,bib_key,role,title,authors,year,venue,method,dataset_or_sample,task_or_problem,key_claim,metric_or_result,limitations,relevance,full_text_status,reading_status,synthesis_path,citation_count_or_signal,identifiers,notes

package/template/sota/paper-syntheses/.gitkeep

@@ -0,0 +1 @@
+

package/template/sota/reading-log.csv

@@ -0,0 +1 @@
+source_id,role,reading_copy_path,start_location,end_location,status,reader,started_on,completed_on,notes

package/template/sota/search-strategy.md

@@ -4,11 +4,40 @@
 
 <fill: research question or review objective>
 
+## Review Scale
+
+- Scale: quick-scan | focused-sota | full-survey
+- Target included papers:
+- Core paper budget:
+- Supporting paper budget:
+- Citation-chasing hop budget:
+- Stopping rule:
+
+## Seed Set
+
+| Seed ID | Source | Why It Is A Seed | Initial Role | Expansion Status |
+|---|---|---|---|---|
+
+## Concepts And Keywords
+
+| Concept | Synonyms | Exclusion Terms | Notes |
+|---|---|---|---|
+
 ## Sources Queried
 
 | Source | Query | Date | Filters | Results | Notes |
 |---|---|---:|---|---:|---|
 
+## Citation Chasing
+
+Record rounds in `sota/citation-chasing-log.csv`. Include backward references,
+forward citations, promoted seeds, and saturation notes.
+
 ## Screening Notes
 
 <fill: screening workflow, ambiguity, or reviewer notes>
+
+## Blind Spots
+
+<fill: databases not searched, inaccessible full text, language limits, venue
+limits, missing citation graph coverage, or unresolved metadata issues>

package/template/sources/markdown-linear/.gitkeep

@@ -0,0 +1 @@
+

package/template/tests/test_project_structure.py

@@ -8,18 +8,36 @@ def test_core_research_structure_exists() -> None:
         "configs/default.yaml",
         "configs/capabilities.yaml",
         "docs/agent/capability-profile.md",
+        "docs/agent/output-contracts.md",
+        "docs/agent/project-quality.md",
+        "docs/agent/repo-migration-playbook.md",
+        "docs/reproducibility/commands.md",
         "scripts/README.md",
         "notebooks/README.md",
         "outputs/figures",
         "outputs/tables",
         "data/raw",
         "analysis_outputs",
+        "analysis_outputs/claim-audit.md",
         "artifacts/cache",
         "artifacts/data",
         "artifacts/models",
         "artifacts/releases",
+        "artifacts/badge-evidence-ledger.csv",
+        "experiments/campaigns/autonomous-campaign-template.md",
+        "experiments/campaigns/frontier-results.tsv",
+        "repro_outputs/SUMMARY.md",
+        "repro_outputs/COMMANDS.md",
+        "repro_outputs/LOG.md",
+        "repro_outputs/PATCHES.md",
+        "repro_outputs/status.json",
+        "sources/markdown-linear",
         "sources/source-ledger.csv",
+        "sota/reading-log.csv",
+        "sota/citation-chasing-log.csv",
         "sota/literature-matrix.csv",
+        "sota/paper-syntheses",
+        "reports/paper/sota-survey.tex",
         "wiki/index.md",
         "wiki/log.md",
         "wiki/templates/source-page.md",