spec-kitty-charter-doctrine

# spec-kitty-charter-doctrine

Manage the charter lifecycle: interview, generate, context-load, sync,
and status. Access doctrine artifacts programmatically via `DoctrineService`.
Resolve agent profiles for role-scoped behavior. Load governance context
iteratively at action boundaries rather than dumping everything upfront.

`.kittify/charter/charter.md` is the Spec Kitty runtime governance
source for a project. A repository may also keep public governance docs
outside `.kittify/`; those docs are human-facing authority unless the
runtime charter summarizes or references them. All structured config
(`governance.yaml`, `directives.yaml`, `references.yaml`) is derived from
the runtime charter. The doctrine layer (`src/doctrine/`) provides the
reusable knowledge artifacts (directives, tactics, paradigms, styleguides,
toolguides, procedures, agent profiles, step contracts) that the charter
references.

---

## ⛔ ARCHITECTURAL INVARIANT: spec-kitty NEVER calls LLMs

**spec-kitty is a CLI tool invoked BY an LLM harness (Claude Code, Codex, Cursor,
Gemini, etc.). The LLM harness IS the inference engine. spec-kitty must NEVER
call any LLM API itself.**

This is not a preference. It is a hard architectural rule with no exceptions.

### Why this rule exists

| What you are reading this in | What that means |
|------------------------------|-----------------|
| Claude Code | Claude IS already running. It should generate doctrine. |
| Codex CLI | Codex IS already running. It should generate doctrine. |
| Cursor / Gemini / Kiro / ... | Same — the harness IS the inference engine. |

If spec-kitty called the Anthropic SDK internally:
- It would need a separate `ANTHROPIC_API_KEY` — a second API key alongside the one
  the harness already uses.
- It would bypass the harness entirely, making the agent's reasoning invisible.
- It would make spec-kitty Anthropic-specific, breaking all other harnesses.
- It would be a hidden inference call the user never authorized or configured.
- It would duplicate what the harness can already do better, with full context.

### What this means for charter synthesis

**Charter synthesis is an LLM reasoning task. YOU (the agent running this skill)
are the LLM that should do it.**

The synthesis workflow is:

```
answers.yaml   (the interview answers — what the user told spec-kitty about the project)
     +
doctrine schemas  (the YAML shapes expected for directives, tactics, styleguides)
     +
THIS SKILL  (the instructions you are reading right now)
     ↓
YOU generate the doctrine YAML files
     ↓
spec-kitty CLI commands  (validate, stage, and promote the files you wrote)
```

spec-kitty's CLI provides validation, schema-checking, DRG validation, neutrality
gating, staging, and atomic promotion. It does NOT provide generation — that is
your job as the agent.

### If you see code that calls `anthropic.Anthropic()` or imports the `anthropic` SDK
inside spec-kitty source files, that is a bug. Remove it immediately.

Canonical locations that must NEVER contain `import anthropic` or any Anthropic SDK call:
- `src/charter/` — any file
- `src/specify_cli/` — any file
- `pyproject.toml` — must not list `anthropic` as a runtime dependency

---

## How to Synthesize Doctrine Artifacts (Agent-Driven)

When a user says "synthesize charter doctrine", "generate project doctrine", or
"run charter synthesize", you do the following — you do NOT call any CLI command
that triggers an LLM. You ARE the LLM.

### Step 1 — Read the interview answers

```bash
cat .kittify/charter/interview/answers.yaml
```

This file contains the user's responses: project intent, languages, testing
requirements, quality gates, etc.

### Step 2 — Read the doctrine schemas for the target artifact kinds

The current synthesis scope is: `directive`, `tactic`, `styleguide`.

Read shipped examples to understand the expected YAML shape:
```bash
spec-kitty doctrine list --kind directive
spec-kitty doctrine show <a-directive-id>

spec-kitty doctrine list --kind tactic
spec-kitty doctrine show <a-tactic-id>

spec-kitty doctrine list --kind styleguide
spec-kitty doctrine show <a-styleguide-id>
```

### Step 3 — Read the interview mapping to know what to generate

The interview fields map to target artifact kinds:
- `project_intent`, `quality_gates`, `risk_boundaries` → directives
- `testing_requirements` → directives + tactics (TDD flavour)
- `languages_frameworks` → styleguides (language-specific)
- `performance_targets`, `deployment_constraints` → directives

For each synthesis target, derive: `kind`, `slug` (kebab-case, project-specific),
`title`, and `body` (the full artifact content as YAML matching the shipped schema).

### Step 4 — Write the doctrine YAML to `.kittify/charter/generated/`

The harness writes artifact inputs here; `spec-kitty charter synthesize`
validates, stages, and promotes them into the live doctrine tree.

```
.kittify/charter/generated/
  directives/
    <NNN>-<slug>.directive.yaml
  tactics/
    <slug>.tactic.yaml
  styleguides/
    <slug>.styleguide.yaml
```

Use the shipped artifact YAML structure as your template. Make the content
**specific to the project** based on the interview answers. Do not write
generic filler.

### Step 5 — Run the full validation stack without promoting

```bash
spec-kitty charter synthesize --dry-run
```

This is a real stage-and-validate pass. It writes the agent-authored artifacts
into the staging tree, runs schema validation, project DRG validation, and the
neutrality gate, then wipes the staging directory on success.

### Step 6 — Promote the validated artifact set

```bash
spec-kitty charter synthesize
```

By default this reads from `.kittify/charter/generated/` via the generated
adapter and promotes the validated outputs into:
- `.kittify/doctrine/` for artifact content and project `graph.yaml`
- `.kittify/charter/provenance/` plus `synthesis-manifest.yaml` for bookkeeping

### Step 7 — Commit the promoted charter synthesis state

```bash
git add .kittify/do