Writ Commands Reference

Every CLI command and HTTP endpoint.

Three groups: CLI commands (via the writ binary), writ-session.py subcommands (state management used by the hooks), and HTTP API endpoints (the FastAPI service on localhost:8765). Type in the box to filter; click a category chip to scope the search.

CLI 16 Session 19 HTTP 37 16 entries

CLI Commands

Invoked as writ <command>. The bin/writ shim forwards to the skill's venv python. Typer entrypoint: writ/cli.py.

writ serve

starts the FastAPI service on localhost:8765 and pre-warms BM25, ANN, and adjacency indexes into memory.

CLI
writ query

runs a natural-language rule retrieval against the live pipeline and prints ranked rules for relevance testing.

CLI
writ add

interactively adds a new rule to the graph with redundancy, conflict, and relationship-suggestion checks.

CLI
writ edit <rule_id>

interactively edits an existing rule and revalidates the result against the schema before write.

CLI
writ propose

submits an AI-generated rule through the structural gate (specificity, redundancy, conflict) before ingestion.

CLI
writ review [rule_id]

lists or inspects AI-provisional rules; flags --promote, --reject, --downweight, --stats.

CLI
writ import-markdown <path>

ingests rules from markdown files in a directory into the Neo4j graph, validating each.

CLI
writ export <path>

regenerates markdown rule files from the graph into a target directory (round-trippable).

CLI
writ migrate

runs the one-time migration script for legacy rule formats into the current schema.

CLI
writ compress

clusters domain rules into abstraction nodes (HDBSCAN vs k-means with silhouette comparison).

CLI
writ validate

runs integrity checks for conflicts, orphans, staleness, redundancy, and graduation candidates.

CLI
writ feedback <rule_id> <positive|negative>

records a feedback signal that feeds the empirical-confidence tracker.

CLI
writ analyze-friction

summarizes workflow-friction.log; supports per-rule, per-skill, per-playbook analyzers.

CLI
writ audit-session <session_id>

per-session timeline of phases, rule loads, gate denials, subagents, and token budgets.

CLI
writ role-prompt <role>

prints the graph-canonical prompt template for a subagent role (writ-explorer, writ-planner, etc.).

CLI
writ status

pings /health on the running service and prints rule count, index state, and startup latency.

CLI

writ-session.py Subcommands

Invoked as python3 bin/lib/writ-session.py <subcommand> <session_id> [options]. The hook scripts shell out to this for all state changes.

mode get <session_id>

returns the current session mode (conversation, debug, review, work).

Session
mode set <mode> <session_id> [--orchestrator]

sets the session mode; --orchestrator suppresses broad RAG inject in the master session.

Session
mode switch <mode> <session_id>

alias for mode set that preserves paused-work state across mode changes.

Session
read <session_id>

dumps the full session cache as JSON to stdout.

Session
update <session_id>

mutates session cache fields; accepts --add-rules JSON, --cost N, --context-percent N.

Session
format

emits the always-active rules block for UserPromptSubmit injection (mandatory rules only).

Session
should-skip <session_id> [--threshold N]

exits 0 if context pressure is above the threshold, signaling RAG to skip.

Session
coverage <session_id>

prints rule coverage statistics for the current session (loaded, capacity, remaining).

Session
can-write <session_id> [--skill-dir PATH]

checks whether the current phase allows file writes and returns the verdict.

Session
advance-phase <session_id>

advances the phase gate (planning to testing to implementation to verify); records confirmation_source.

Session
current-phase <session_id>

prints the active phase name from the session's phase state machine.

Session
auto-feedback <session_id>

scans the transcript for self-correction signals and emits feedback events.

Session
detect-compaction <session_id> <context_percent>

detects context-compaction events and triggers post-compact recovery.

Session
add-pending-violation <session_id>

records a pending violation (rule, file, line, evidence) for the verification phase.

Session
clear-pending-violations <session_id>

clears the pending-violation list for the session.

Session
pending-violations <session_id>

lists pending violations recorded against the session.

Session
invalidate-gate <session_id> <gate>

marks a previously approved gate as invalid (forces re-approval).

Session
check-escalation <session_id>

returns whether the session should escalate to a stricter enforcement tier.

Session
metrics

prints aggregate session metrics computed from the friction log (clean-run rate, phase times, mode mix).

Session

HTTP API Endpoints

JSON in, JSON out. Source: writ/server.py. GET endpoints are green-badged; POST endpoints are amber.

Retrieval and rule operations
POST /query

ranked rule retrieval through the five-stage pipeline; returns rules within the token budget.

POST
POST /analyze

analyzes a code blob against active rules and returns compliance findings.

POST
GET /rule/{rule_id}

returns one rule node plus its one-hop graph neighbors.

GET
POST /propose

submits an AI rule proposal through the structural gate; returns accepted or reasons.

POST
POST /feedback

records a positive or negative signal for the rule's frequency counter.

POST
POST /conflicts

returns CONFLICTS_WITH edges across a supplied set of rule IDs.

POST
GET /always-on

returns the set of always-on (mandatory) rules to inject every prompt.

GET
GET /subagent-role/{name}

returns the graph-canonical SubagentRole prompt template.

GET
POST /pre-write-check

pre-write enforcement check; returns allow or deny plus the offending rule.

POST
GET /health

service status, rule count, index state, and startup latency.

GET
GET /dashboard

HTML dashboard rendering the current state of the friction log.

GET
Session lifecycle
GET /session/{session_id}

reads the full session cache (mode, phase, loaded rules, budget).

GET
POST /session/{session_id}/update

mutates session cache fields atomically.

POST
GET /session/{session_id}/should-skip

returns whether context pressure warrants skipping RAG this turn.

GET
GET /session/{session_id}/mode

returns the current session mode.

GET
POST /session/{session_id}/mode

sets the session mode with an optional orchestrator flag.

POST
POST /session/{session_id}/can-write

pre-write permission check based on the current phase.

POST
POST /session/{session_id}/advance-phase

advances the phase gate and records confirmation_source to the audit trail.

POST
GET /session/{session_id}/current-phase

returns the active phase name.

GET
POST /session/format

returns the always-active rules block for prompt injection.

POST
GET /session/{session_id}/coverage

returns rule coverage statistics for the session.

GET
GET /session/{session_id}/check-escalation

returns whether the session should escalate to a stricter tier.

GET
POST /session/{session_id}/auto-feedback

scans the transcript for self-correction signals.

POST
POST /session/{session_id}/clear-pending-violations

clears the pending-violation list.

POST
POST /session/{session_id}/add-pending-violation

appends a pending violation for the verification phase.

POST
POST /session/{session_id}/invalidate-gate

marks a previously approved gate as invalid (forces re-approval).

POST
GET /session/{session_id}/pending-violations

lists pending violations for the session.

GET
POST /session/{session_id}/context-percent

records a context-pressure snapshot for this turn.

POST
POST /session/{session_id}/detect-compaction

detects compaction and triggers recovery state.

POST
POST /session/{session_id}/clear-rules-for-compaction

clears injected rules ahead of compaction to free budget.

POST
POST /session/{session_id}/reset-after-compaction

resets session state after a context compaction completes.

POST
GET /session/{session_id}/active-playbook

returns the active playbook and current step.

GET
POST /session/{session_id}/active-playbook

sets or advances the active playbook step.

POST
POST /session/{session_id}/verification-evidence

records evidence supporting a verification claim.

POST
GET /session/{session_id}/verification-evidence

returns evidence collected so far.

GET
POST /session/{session_id}/quality-judgment

records a quality judgment for a rule rubric.

POST
GET /session/{session_id}/quality-judgment

returns quality judgments recorded for the session.

GET
No commands match that filter. Clear the search or pick a different category.