Metadata-Version: 2.4
Name: cs-paper-harness
Version: 1.0.0
Summary: Evidence-bound harness for agent-assisted CS paper drafting.
Author: cs-paper-harness maintainers
License: MIT License
        
        Copyright (c) 2026 cs-paper-harness contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: academic-writing,agent-workflow,codex,computer-science,paper,research
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# cs-paper-harness

Language: English | [中文](README.zh-CN.md)

`cs-paper-harness` is an evidence-bound, agent-first harness for Computer
Science graduate paper workflows in Codex and Claude Code.

The project is not a paper-writing bot, a LaTeX formatter, or a prompt
collection. It gives the agent a protocol for preserving context, evidence
boundaries, direct-edit recovery, and handoff state while the student works
toward a credible `paper.md` draft.

## Install

Install the runtime:

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

Configure a paper workspace, global agent surfaces, or both:

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

`project` scope writes only workspace-local guidance and `.cs-paper/` private
state setup. `global` scope installs Codex and Claude Code skill surfaces into
normal user discovery paths. `both` performs both actions explicitly.

## Student Path

Start here if you want to use CPH for a paper:

- [Install CPH](docs/student/install.md)
- [First Paper From Zero](docs/student/first-paper.md)
- [Continue An Existing Paper](docs/student/continue-existing-paper.md)
- [Bring Experiment Artifacts](docs/student/experiment-artifacts.md)
- [Direct Paper Edit Recovery](docs/student/direct-paper-edit-recovery.md)
- [Privacy And Local State](docs/student/privacy.md)
- [Use CPH In Codex](docs/student/codex.md)
- [Use CPH In Claude Code](docs/student/claude-code.md)
- [Troubleshooting](docs/student/troubleshooting.md)

AI-readable project assets are available at [llms.txt](llms.txt),
[llms-full.txt](llms-full.txt), and
[docs/project-knowledge.md](docs/project-knowledge.md).

## Core Idea

Models should think, discuss, analyze, and write. The harness should preserve
state, evidence, gates, and handoff.

In plain terms:

- The model is the runner.
- The agent is the running interface and tool surface.
- CPH is the guardrail, checkpoint, and relay protocol.

CPH does not replace the agent interface. A student still works inside Claude
Code or Codex. CPH constrains the process so the agent does not skip evidence,
forget decisions after context compaction, or write claims stronger than the
available artifacts.

## V1 Outcome

V1 starts when a student says something like:

- I want to do research about X.
- I want to write a CS paper, but I am not sure about the direction.
- I already have an idea, experiment folder, or partial draft.

V1 ends with:

- `paper.md`
- `references.bib`
- `references.md`

V1 does not include formatting, LaTeX, Word, submission packaging, automatic
experiment execution, or a full venue database.

## Workflow

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

The writing order is evidence-first. For most empirical CS papers,
method/system and experiments/findings should be written before Introduction,
because Introduction is where unsupported over-framing is most likely to
appear.

## Runtime Boundary

The `cph` runtime exposes only deterministic protocol operations:

- `cph init`
- `cph doctor`
- `cph manifest`
- `cph assemble`
- `cph handoff`

The runtime does not judge research novelty, paper quality, evidence support,
final audit quality, or whether to keep, discard, or defer direct `paper.md`
edits. Those decisions stay with the student and the agent workflow.

## Local Verification

From the repository root:

```bash
env UV_CACHE_DIR=/tmp/uv-cache uv lock --offline
env UV_CACHE_DIR=/tmp/uv-cache uv run cph --help
env UV_CACHE_DIR=/tmp/uv-cache uv run cph doctor
jq empty schemas/*.schema.json
env UV_CACHE_DIR=/tmp/uv-cache uv run pytest
```

The committed synthetic demo workspace has its own deterministic gate:

```bash
cd examples/self-referential-demo
env UV_CACHE_DIR=/tmp/uv-cache uv run cph doctor
env UV_CACHE_DIR=/tmp/uv-cache uv run cph manifest list
env UV_CACHE_DIR=/tmp/uv-cache uv run cph manifest check
env UV_CACHE_DIR=/tmp/uv-cache uv run cph assemble
env UV_CACHE_DIR=/tmp/uv-cache uv run cph handoff
```

For a copyable toy workspace flow, see
[docs/getting-started-walkthrough.md](docs/getting-started-walkthrough.md).

## Privacy

Real paper workspaces should keep these files private and ignored by git:

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

Only [examples/self-referential-demo](examples/self-referential-demo) may commit
synthetic `.cs-paper/` state.

## Maintainer References

- [Documentation Index](docs/README.md)
- [Protocol Overview](docs/protocol-overview.md)
- [Command Boundary](docs/command-boundary.md)
- [Stage Contracts](docs/stage-contracts.md)
- [Evidence And Claims](docs/evidence-and-claims.md)
- [Manifest Contract](docs/manifest-contract.md)
- [Handoff State](docs/handoff-state.md)
- [Paper Sync Reconciliation](docs/paper-sync-reconciliation.md)
- [Maintainer Architecture](docs/maintainer/architecture.md)
- [Release Operations](docs/maintainer/release-operations.md)
- [Release Evidence Ledger](docs/maintainer/release-candidate-evidence.md)
- [Manual Acceptance](docs/maintainer/manual-acceptance.md)
- [Release Contract](docs/v1-release-contract.md)
- [Development Roadmap](docs/v1-development-roadmap.md)
- [Changelog](CHANGELOG.md)
- [Security Policy](SECURITY.md)
- [Support](SUPPORT.md)

The project is licensed under the [MIT License](LICENSE).
