# cs-paper-harness Full AI Digest

## Description

`cs-paper-harness` is an agent-first, evidence-bound harness for Computer
Science graduate paper workflows. It helps a student work in Codex or Claude
Code while preserving context, evidence boundaries, claim maturity, paper-sync
state, and handoff state.

CPH is not a paper-writing bot, not a LaTeX formatter, not a venue database,
and not an autonomous research system. The student and agent still make
semantic research decisions. The `cph` runtime performs deterministic checks
and workspace operations only.

## Target User

The target user is a CS graduate student working on a paper with Codex or
Claude Code. The student may start with:

- no paper workspace yet
- an unclear idea only
- a confirmed idea but no experiments
- experiment folders or result artifacts
- partial `sections/*.md`
- an existing `paper.md`
- an existing draft with no `.cs-paper/`
- stale handoff state
- unreconciled direct `paper.md` edits

## Supported Agents

- Codex: generated installable package layout under
  `agent-packages/codex/skills/cph-paper-harness/`
- Claude Code: generated installable package layout under
  `agent-packages/claude-code/skills/cph-paper-harness/`

The generated agent package layouts are instruction-only. They do not add
hidden tool permissions, hooks, MCP configuration, plugin manifests,
marketplace metadata, or runtime behavior.

## Installation

Install the runtime:

```bash
pipx install cs-paper-harness==1.0.0
cph --help
```

Configure one paper workspace without writing normal user agent discovery
paths:

```bash
cph-install --scope project --agent codex --project /path/to/paper-workspace
```

Install Codex and Claude Code agent surfaces into normal user discovery paths:

```bash
cph-install --scope global --agent all
```

Perform both actions explicitly:

```bash
cph-install --scope both --agent all --project /path/to/paper-workspace
```

The shell one-shot installer is only a convenience layer. It installs the
canonical package with pipx when needed, then delegates to `cph-install`.

## Runtime Commands

The only approved top-level runtime commands are:

- `cph init`: create or repair deterministic workspace basics and local guidance
- `cph doctor`: report deterministic workspace, handoff, manifest, and paper-sync health
- `cph manifest`: register, list, and check artifact freshness without semantic approval
- `cph assemble`: assemble `paper.md` from `sections/*.md` and block unreconciled direct edits
- `cph handoff`: create, validate, and archive hidden handoff state

The runtime must not judge novelty, paper quality, evidence support, final
audit quality, or direct-edit reconciliation decisions.

## Workflow Stages

V1 stage map:

1. Initialization
2. Direction confirmation
3. Idea planning
4. Experiment artifact analysis
5. Evidence-core writing
6. Storyline planning
7. Introduction draft and framing audit
8. Discussion and limitations
9. Related Work and citation pass
10. Conclusion
11. Assembly, polish, and final audit

Each stage has completion gates, blockers, stale-state triggers, and handoff
requirements. A stage is not complete unless the handoff is current.

## Evidence And Claims

Strong paper claims require explicit support. Agent inference can guide
planning but cannot alone support strong factual claims in the paper.

Before evidence gates pass, use hypothesis wording such as "we investigate",
"we hypothesize", or "we evaluate whether". Supported wording such as "we
show", "we find", "we observe", and "results indicate" is allowed only after
evidence support is accepted.

Terms such as "state-of-the-art", "outperform", "novel", "robust",
"general", and "demonstrates" require evidence and audit support.

## Direct `paper.md` Edit Recovery

`sections/*.md` are the preferred prose source. `paper.md` is assembled output.
If direct `paper.md` edits are unreconciled, CPH must stop writing, audit,
assembly, polish, and final-audit work until the student chooses exactly one:

- keep: map confirmed edits into section sources, mark affected audits stale, then run `cph assemble`
- discard: require current-turn student approval, restore from accepted section sources, then run `cph assemble`
- defer: leave files unchanged, preserve the blocker, and stop paper work

There is no `cph reconcile` command.

## Privacy Boundary

Real paper workspaces should keep these private and gitignored:

```text
.cs-paper/
AGENTS.md
CLAUDE.md
```

These files can expose agent traces, local paths, unfinished claims,
reviewer-sensitive notes, or private workflow state. Only
`examples/self-referential-demo/.cs-paper/` is committed, and it is synthetic
demo state.

## Public Docs

Student path:

- docs/student/install.md
- docs/student/first-paper.md
- docs/student/continue-existing-paper.md
- docs/student/experiment-artifacts.md
- docs/student/direct-paper-edit-recovery.md
- docs/student/privacy.md
- docs/student/codex.md
- docs/student/claude-code.md
- docs/student/troubleshooting.md

Maintainer path:

- docs/maintainer/architecture.md
- docs/maintainer/release-operations.md
- docs/maintainer/release-candidate-evidence.md
- docs/maintainer/manual-acceptance.md

Protocol and release records:

- docs/protocol-overview.md
- docs/stage-contracts.md
- docs/manifest-contract.md
- docs/handoff-state.md
- docs/paper-sync-reconciliation.md
- docs/v1-release-contract.md
- docs/v1-development-roadmap.md

## Non-Goals

Not in v1.0.0:

- runtime semantic paper judgment
- runtime novelty judgment
- runtime paper-quality scoring
- runtime evidence approval
- automatic keep/discard/defer decisions
- `cph reconcile`
- automatic experiment execution
- venue deadline tracking
- complete venue database
- required LaTeX, Word, PDF, or submission packaging
- guaranteed paper quality
- guaranteed novelty
- autonomous research capability
- real-world effectiveness claims beyond evidence

## Release Evidence

Maintainer release evidence is recorded under
`docs/maintainer/release-candidate-evidence.md` and release operations are
recorded under `docs/maintainer/release-operations.md`. These records are for
maintainers and are not required before a student starts the first workflow.
