# Start-project actions

Use exactly one action procedure per invocation. Resolve every project URI through the host adapter and apply the safety and structural invariants in the parent skill throughout.

## `new-paper`

Contract: [protocol/actions/new-paper.json](../../../actions/new-paper.json)

1. Resolve `project://manifest`. If it exists, stop and offer to inspect or repair the project; never silently reinitialize portable state.
2. Scan the authorized project root for existing `project://materials/{artifact}` and `project://paper/{artifact}` resources: manuscripts, bibliographies, figures, data, and notes. Exclude version-control metadata, adapter-owned state, dependency caches, generated output, and the conventional portable-record store. Do not follow a symlink outside the root.
3. If substantial material exists but no source records exist, offer `map-project`. Continue only when the author chooses to initialize first.
4. Gather the foundations in a compact interview:
   - document type and working title;
   - target venue or delivery context;
   - one-sentence core argument or contribution;
   - intended audience and the one thing it should remember;
   - must-have, desirable, and out-of-scope content;
   - deadlines, page or word limits, authorship, data, ethics, and confidentiality constraints;
   - known evidence, open questions, important disagreements, and choices delegated to editorial discretion.
5. Refine a weak argument by asking what is new, what evidence could support it, and what reasonable alternative it must defeat. Preserve the author's decision as a decision record rather than silently replacing it with an agent inference.
6. Verify venue constraints from a project-provided or authoritative source. Mark constraints provisional when verification is unavailable.
7. Propose the exact v1 policy: interaction mode, depth, output format, language, citation style, five approval gates, four workflow checks, mandatory safety flags, and parallelism. Do not introduce legacy model, planning-document, or VCS configuration keys.
8. Preview five schema-valid records and their stable project ID:
   - `project://manifest` for identity, core argument, target, requirements, artifact index, and timestamps;
   - `project://config` for portable workflow policy;
   - `project://state` for lifecycle, current position, progress, checkpoints, and last transition;
   - `project://decisions` for locked, deferred, and discretionary author decisions;
   - `project://structure/outline` for a clearly provisional thesis and initial section structure.
   Require the outline's `sections[*].word_target` values to sum exactly to its
   `target_words`; revise the proposed allocation before presenting the preview
   when they do not.
9. At the initialization gate, explain any existing path collision and the exact records that would be created. Do not offer repository initialization, staging, committing, branching, merging, pushing, or publishing as part of this action.
10. Write the approved records atomically through the adapter. Validate each against its v1 schema, read it back, verify URI containment and cross-record project IDs, and remove partial newly created records if the atomic set cannot be completed safely.
11. Report record URIs, author decisions, provisional constraints, unresolved questions, and whether `map-project` or `create-outline` is the next action.

Completion requires five valid and mutually consistent v1 records; no Markdown control file substitutes for them.

## `map-project`

Contract: [protocol/actions/map-project.json](../../../actions/map-project.json)

1. Establish the project boundary and whether ignored or hidden research material may be scanned. Never upload or externally inspect material as part of local mapping.
2. Inventory relevant materials by media type, size, modification time, stable relative identity, and logical artifact URI:
   - bibliography databases and reference notes;
   - manuscript drafts and reusable fragments;
   - data, analysis outputs, tables, and figures;
   - protocols, venue templates, reviews, and style guidance.
3. Avoid dependency trees, generated builds, archives, adapter state, and duplicate copies unless the author includes them. Record unreadable or unsupported files instead of silently skipping them.
4. Parse structured bibliography metadata only when the action declares an exact contained parser binding. Otherwise record that format as unavailable for structured parsing; never substitute a shell command or infer a missing identity field or scientific result as fact.
5. Create one `project://sources/{source}` record per bibliographic or data-source identity. Use stable IDs, explicit provenance, inspection depth, verification time, and `provisional` status when identity is not fully checked.
6. Create `project://evidence/{evidence}` only for an actual claim-level interpretation. Link it to a source record, state whether it supports, contradicts, or contextualizes the claim, include a locator and limitations, and never copy interpretation into source identity.
7. Preserve manuscript, dataset, figure, table, and prior-draft content as authored `project://materials/{artifact}` or `project://paper/{artifact}` resources. Mapping indexes them; it does not rewrite or move them.
8. Read existing source and evidence records before any update. Merge by stable source identity and contained artifact URI. Preserve curated annotations, detect duplicate identifiers and citation-key collisions, and do not replace a verified record with a weaker scan result.
9. Merge selected material and manuscript URIs into `project://manifest` artifacts.materials and artifacts.manuscripts, deduplicating by contained URI while preserving existing entries, unrelated fields, and authored content. Update the manifest updated_at only when its indexes change. Validate and read back all created or updated inventory records and the manifest before reconciling `project://state` to phase `mapped`. Record the factual transition and retain active checkpoints.
10. Report counts, duplicates, missing metadata, unavailable formats, privacy-sensitive material, evidence gaps, and the exact records created or updated.

Completion requires a non-destructive, provenance-rich inventory whose source and evidence records validate independently.

## `create-outline`

Contract: [protocol/actions/create-outline.json](../../../actions/create-outline.json)

1. Require `project://manifest`, `project://decisions`, and `project://config`. If `project://structure/outline` already contains established sections, present a structural diff and obtain approval before revising it.
2. Load project requirements, verified and provisional source/evidence records, venue constraints, and current state. Identify unresolved argument or evidence questions before outlining.
3. Interview the author about unresolved structural choices before presenting the proposed thesis, major supporting claims, counterarguments, limitations, and likely document shape at `config.gates.confirm_outline`. Treat only an explicit author answer as authority to resolve a deferred choice. For each explicitly resolved item whose current disposition is `deferred`, preserve the prior item unchanged except for setting its disposition to `superseded`; append a new replacement whose ID is fresh and unique in the ledger, whose authority is `author`, whose disposition is `locked`, and whose `supersedes` field names the prior item. Set the replacement's `recorded_at` to the actual resolution time, increment the decision-record revision, set the record's `updated_at` to that same actual resolution time, and preserve every unrelated decision unchanged. Never supersede a locked choice. If the author resolves no choice, do not rewrite the decision record.
4. Build one `project://structure/outline` record in which every major claim has a stable ID and every section has:
   - a stable ID and title;
   - a goal and argument role;
   - an owning set of claim IDs;
   - evidence or research topics still required;
   - target words, dependencies, and execution wave.
5. Express the reader's progression through section goals and argument roles: starting belief, problem or gap, evidence progression, resolution, and implication. Do not create a parallel Markdown argument map, roadmap, or narrative-arc control file.
6. Assign the same wave only to sections that can be drafted independently and do not write the same manuscript artifact. Reject dependency cycles and references to missing section IDs.
7. Create one `project://sections/{section}` record per outline entry. Link its context, research, plans, manuscript, and summary artifact URIs without claiming those authored artifacts already exist.
8. Reconcile `project://state`: phase `outlining` or `planning`, exact totals, target words, current section URI, and a factual transition. Keep author decisions in `project://decisions`, not duplicated into state.
9. Independently validate requirement coverage, claim ownership, evidence obligations, dependency order, wave safety, artifact-link containment, decision-ledger consistency, exact equality between the sum of `sections[*].word_target` and `target_words`, and cross-record project IDs. An outline that contradicts a locked decision cannot change that decision's disposition; it remains locked and unchanged. A choice remains deferred only when it was already deferred and the author did not explicitly resolve it. Either contradiction prevents a passing validation. Write the result to `project://validations/{validation}`.
10. If validation fails, revise checkable defects and return author-owned conflicts as unresolved input without inventing a decision. At final approval, atomically publish the decision update when one is required together with the outline, section records, state, and validation. Do not perform VCS operations.
11. Report the approved outline and decision revisions, section record URIs, validation status, open evidence work, unresolved author choices, and first section eligible for discussion or planning.

Completion requires an executable, validated v1 outline and matching section/state records, not merely a table of contents.