Module harness 

Harness packaging for ctx harness (Claude Code integration).

This module scaffolds hook scripts, settings, skills, and plugin manifests from templates embedded in the binary (templates), stamps every generated file with a version header and checksum (checksum), guards generated hooks against version skew (compat), and diagnoses the whole integration (doctor).

Ownership model

init records a checksum for every file it writes – in the file itself (comment header) where the format allows comments, and always in the .ctx/harness.lock manifest. On re-run, each planned file is classified:

• Missing: written.
• Owned, unmodified (checksum matches): regenerated in place.
• Owned, modified (checksum mismatch): warned about and skipped; --force overwrites.
• Foreign (exists but no ctx checksum anywhere): warned about and skipped; --force overwrites.

Exception: .ctx/rules.toml encodes user policy and is never overwritten once it exists, not even with --force.

Modules

checksum

Generated-file headers and content checksums for ctx harness.

compat

Version compatibility check for ctx harness compat.

doctor

ctx harness doctor – integration diagnostics.

templates

Embedded templates for ctx harness init.

Structs

GeneratedFile

One file init plans to write: final content (header + checksum already applied) plus write metadata.

LockEntry

One manifest entry: the checksum and generator version of a file.

LockFile

The .ctx/harness.lock manifest: rel_path -> entry.

Enums

FileAction

What write_plan did with one planned file.

Mode

Scaffolding mode.

SettingsWireAction

Outcome of merging the ctx snippet into .claude/settings.json.

Target

Harness targets (mirrors the CLI enum; only Claude Code for now).

Constants

HOOK_NAMES

The three hook script basenames (shared by local and plugin modes).

LOCAL_HOOKS_DIR

Directory holding the local-mode hook scripts.

LOCK_PATH

Relative path of the harness manifest.

RULES_PATH

Relative path of the starter rules file.

Functions

plan_codex_local

plan_codex_plugin

plan_local

Plan the files for --mode local: hook scripts under .claude/hooks/ctx/ plus a starter .ctx/rules.toml.

plan_plugin

Plan the files for --mode plugin: a full Claude Code plugin scaffold.

read_lock

Read and parse the manifest; None when missing or unparseable (a broken manifest falls back to in-file checksum verification).

render_agents_md_block

render_claude_md_block

Render the CLAUDE.md guidance block printed to stdout in local mode.

render_settings_snippet

Render the settings snippet printed to stdout in local mode.

wire_local_settings

Merge the ctx hooks + permissions snippet into .claude/settings.json.

write_plan

Write a plan to disk, honoring the ownership model, and update .ctx/harness.lock.