Scoring

ktext validate scores your CONTEXT.yaml out of 100 across eight sections. Each section is evaluated independently for presence, completeness, and quality of language. The output shows a score per section, a pass/fail status, and a prioritized list of fixes.

Section weights

Sections are weighted by how much impact they have on context quality:

Section	Max	What it covers
constraints	20	Hard rules. The highest-value context for anyone working in the codebase.
identity	15	What the project is, its purpose, type, and status
decisions	15	Architectural choices and their rationale
conventions	15	Coding and process rules
risks	10	Known fragile areas and mitigations
dependencies	10	External systems and why they're used
working	10	Build commands, directory layout, and dev notes
ownership	5	Team and escalation path

How sections are scored

Each section awards points in layers:

• Presence — base points for including the section at all
• Completeness — additional points for optional fields like why, status, date, and mitigation
• Quality — points for the quality of language, checked per entry

Quality checks

Quality is evaluated by section:

Section	Quality check
constraints	Must contain actionable language: must, never, always, require, prohibit, ensure, avoid, etc.
conventions	Must contain an action verb: use, run, write, call, return, test, format, name, etc.
decisions	Rationale must be substantive (at least 3 words), scored for depth
risks	High-severity risks without a mitigation are penalized
identity.purpose	Must be at least 3 words

The intent is to distinguish "be careful with auth" from "never store raw credentials in application logs, use structured redaction middleware". The first is noise. The second is useful.

Section status

Each section reports a status based on its score relative to its maximum:

Status	Threshold
✓ pass	≥ 70% of section max
⚠ warn	30–69% of section max
✗ fail	< 30% of section max

Threshold

The default passing threshold is 80/100. Override it with -threshold:

• ktext validate passes if score ≥ 80
• ktext validate -threshold 90 stricter bar for mature projects
• ktext validate -threshold 0 always passes; useful to see the score without gating

JSON output

Use -json for machine-readable output. Useful in CI for posting scores as PR comments or feeding into dashboards.

{
  "score": 86,
  "sections": [
    { "name": "identity",     "score": 15, "max": 15, "status": "pass" },
    { "name": "constraints",  "score": 18, "max": 20, "status": "pass",
      "fixes": ["constraints[1]: add actionable language"] },
    ...
  ],
  "fixes": ["constraints[1]: add actionable language"]
}