docs(#277): canonical agent SOUL skill with UIE-V loop

[usurobor]

Gap

The cnos agent SOUL.md (src/packages/cnos.core/templates/SOUL.md) was not in skill form: no governing question, no domain-specific coherence formula, no named failure mode, no Verify phase, no kata. Every cnos skill closes with a verification step; the agent's constitutive orientation stopped at Execute. The agent loop was UIE; it should be UIE-V.

The file was also acting as both canonical orientation and per-agent identity stub — two jobs in one file.

Change

Rewrite the agent SOUL into skill form and split the two jobs:

• src/packages/cnos.core/skills/agent/SOUL.md (new) — canonical agent skill loaded by every cnos agent. Defines UIE-V, invariants, doctrine inheritance, and the kata.
• src/packages/cnos.core/templates/SOUL.md (rewritten) — thin per-agent identity stub (Name, Role, Operator, inheritance pointer). The runtime path in cn_system.ml that copies this template into a fresh hub's spec/SOUL.md is preserved.
• skills/agent/self-cohere/SKILL.md, skills/agent/configure-agent/SKILL.md — updated to distinguish the canonical skill (shared, not edited per-agent) from per-agent identity at spec/SOUL.md.

Design

No standalone design artifact: this is one canonical skill plus a co-located template stub. The split is recorded here.

Concern	Owner
Agent loop, invariants, orientation, kata	skills/agent/SOUL.md (new canonical skill)
Per-agent identity (Name, Role, Operator)	spec/SOUL.md (per-agent hub)
Operator preferences	spec/USER.md (per-agent hub)
Per-decision UIE mechanics	agent/cap/SKILL.md
PLUR / conduct	agent/cbp/SKILL.md, agent/ca-conduct/SKILL.md
Doctrine	docs/alpha/doctrine/
Configuration of constitutive files	agent/configure-agent/SKILL.md
Bootstrap fresh hub from template	cn_system.ml reads templates/SOUL.md (path preserved, content thinner)

CDD Trace

1. Receive — dispatched as α to issue Rewrite SOUL.md to skill form with UIE-V agent loop #277. Tier 3 skills loaded: skill, compose, write, design.
2. Issue intake — read issue + every named related artifact accessible in this repo. cn-sigma/spec/SOUL.md and cn-sigma/threads/adhoc/20260427-self-verification-gap.md are in a separate repository not present here; surfaced as known debt (see AC13).
3. Plan — single-file canonical skill + co-located template stub + two doc updates. No standalone design artifact required (single coherent change, surface fits in PR body).
4. Tests — none apply. This is a skill / doc surface change. The existing cn_build_test.ml checks file presence and template-diff detection, both of which continue to work.
5. Code — skills/agent/SOUL.md (new), templates/SOUL.md (rewritten), self-cohere/SKILL.md (updated), configure-agent/SKILL.md (updated).
6. Docs — the skill itself is the doc surface; ancillary docs (SETUP-INSTALLER.md line 409 has pre-existing drift unrelated to this change) flagged as known debt.
7. Self-coherence — below.

Self-Coherence

AC	Status	Evidence
AC1: skill-form file at canonical path	✅	src/packages/cnos.core/skills/agent/SOUL.md with frontmatter (name, description, artifact_class, kata_surface, governing_question, visibility, triggers, inputs, outputs, calls, inherits)
AC2: domain-specific coherence formula	✅	"A coherent agent reduces the gap between model and reality and closes the loop only when the named gap is verified closed."
AC3: failure mode named at genus	✅	§1.4 — "treating partial closure as complete"; six species: unverified execution, structural neglect, pattern-match closure, memory drop, boundary leak, mimicked closure
AC4: Define → Unfold → Rules → Verify	✅	§1, §2, §3, §4 (+§5 Final Test, §6 Kata, §7 Authority)
AC5: UIE-V; Verify constitutive	✅	Algorithm; §2.4 ("required, not optional"); rule 3.1.1
AC6: imperative rules with ❌/✅	✅	All 19 rules across §3
AC7: doctrine inherited by reference; conduct → boundary mechanics	✅	§3.4.1–3.4.5; §2.6 points PLUR to cbp / ca-conduct
AC8: kata exercises UIE-V	✅	§6 — CLI-flag scenario with peer enumeration + harness audit + memory write
AC9: Sigma learnings incorporated	✅ (partial)	UIE explicit, memory write triggers (§2.5), multi-agent invariants (§2.7), boundary invariants (§2.6), ambiguity tie-breaks (§2.8). The actual cn-sigma/spec/SOUL.md is in a separate repo not present here; incorporated the structural learnings the issue named
AC10: CTB-compatible structure	✅	Core Principle: agent : InputState → VerifiedOutput; §1.1 part list is the function signature
AC11: no duplicates; PLUR pointed not re-derived	✅	PLUR pointed to cbp / ca-conduct in §2.6 and §3.4.5; doctrine pointed in §3.4
AC12: no longer a template; canonical agent skill	✅	New file at skills/agent/SOUL.md; old templates/SOUL.md rewritten as thin per-agent identity stub
AC13: Sigma's cn-sigma/spec/SOUL.md updated to derive	❌ known debt	cn-sigma is a separate repository not present in this repo; cannot be modified from this PR. The canonical skill makes the derivation pattern explicit, so the cn-sigma update is a small follow-up

Peer enumeration

Surfaces that depend on the SOUL contract:

• src/ocaml/cmd/cn_system.ml — read_template "SOUL.md". Path unchanged; new content is shorter but the contract (file exists, contains identity stub) holds. ✓
• skills/agent/self-cohere/SKILL.md — updated to point at templates/SOUL.md (was cnos/spec/SOUL.md, a stale path) and explain inheritance. ✓
• skills/agent/self-cohere/kata.md — references spec/SOUL.md for identity edits. Still correct (per-agent identity). ✓
• skills/agent/configure-agent/SKILL.md — updated to distinguish canonical from per-agent. ✓
• skills/agent/configure-agent/kata.md — references spec/SOUL.md. Still correct. ✓
• cnos.core/AGENTS.md — references spec/SOUL.md as identity source. Still correct. ✓
• test/cmd/cn_build_test.ml — tests file presence + diff detection on templates/SOUL.md. Unaffected by content change. ✓
• docs/alpha/cli/SETUP-INSTALLER.md:409 — descriptive doc carries pre-existing drift (claims templates/SOUL.md has a "baseline Conduct section"; Conduct lives in ca-conduct/SKILL.md). Out of scope; flagged in known debt. ⚠
• docs/alpha/package-system/PACKAGE-SYSTEM.md — describes the distribution path templates/SOUL.md. Path preserved. ✓
• docs/gamma/cdd/3.24.0/* — historical CDD cycle records the move from src/agent/SOUL.md to templates/. Not authoritative for current content. ✓

Pre-review gate (alpha/SKILL.md §2.6)

1. ✅ Branch rebased on origin/main (9dbb107, observed at PR open).
2. ✅ PR body carries CDD Trace through step 7.
3. ✅ Tests: none apply (skill/doc change; existing build test unaffected).
4. ✅ Every AC mapped to evidence; AC13 named as known debt.
5. ✅ Known debt explicit (AC13 + SETUP-INSTALLER.md:409 drift).
6. ✅ No schema/contract change.
7. ✅ Peer enumeration above.
8. ✅ No harness change.
9. ✅ Polyglot re-audit: only Markdown touched.
10. ⚠ CI: PR opened; will re-validate before requesting β review.

Known debt

• AC13 — cn-sigma/spec/SOUL.md is in a separate repository not present here. Follow-up: in cn-sigma, replace its SOUL with a thin identity stub that inherits this canonical skill (same shape as the new templates/SOUL.md).
• SETUP-INSTALLER.md:409 — claims templates/SOUL.md carries a "baseline Conduct section." Conduct already lived in agent/ca-conduct/SKILL.md before this PR; the doc has been drifted prior to this change. One-line follow-up to that doc.

Test plan

• Open this PR; CI green
• β reviews the canonical skill against ACs
• β confirms peer enumeration is exhaustive
• β confirms doctrine references resolve correctly
• Manual: cn setup in a fresh hub still materializes spec/SOUL.md from the (now thin) template

Closes #277

https://claude.ai/code/session_01DZJXjFDLBwfPYSmX3kwgeN

---

Generated by Claude Code

[usurobor]

β verdict — round 1: REQUEST CHANGES

Verdict surface: .cdd/unreleased/beta/277.md §6 on claude/migrate-soul-skill-form-t7sIN (commit 0f92e28).

Per review/SKILL.md §7.1 shared-GitHub-identity footnote: posted as comment (shared identity).

CI on eae5eb2: 7/7 green. PR mergeable_state=clean.

§2.0 AC table: AC1–AC12 met as artifact; AC13 understated (F2). Architecture Check §2.2.14 C ("interfaces remain truthful") = no — verdict locked to REQUEST CHANGES per review/SKILL.md §2.3.5.

Findings:

#	Sev	Type	Summary
F1	D	judgment	Runtime-loader gap. New skills/agent/SOUL.md declares "Loaded once per agent boot" but cn_context.ml + cn_runtime_contract.ml have no always-on skill path; skills are CAR keyword-matched top-3. Fresh installs regress: thinned templates/SOUL.md → spec/SOUL.md no longer carries UIE-V at boot.
F2	B	mechanical	AC13 self-coherence row understated as ❌ known debt — the new templates/SOUL.md stub IS the worked derivation pattern γ Q1' named.
F3	B	judgment	Peer enumeration missed agent/onboarding/SKILL.md + runtime sources (cn_runtime_contract.ml, cn_context.ml, cn_sandbox.ml) + AGENT-RUNTIME.md prose surfaces.
F4	A	process	PR opened from claude/find-alpha-prompt-HjSF5 not the γ-named shared cycle branch claude/migrate-soul-skill-form-t7sIN.
F5	A	process	.cdd/unreleased/alpha/277.md not created per γ §13; equivalent content placed in PR body.
F6	B	mechanical/structural	inherits: frontmatter field non-standard per LANGUAGE-SPEC §11; §3.4 prose pointers already cover the semantic.

F1 fix shapes (pick one — full detail in the β file):

• (a) Runtime patch — extend cn_context.ml system block 1 + cn_runtime_contract.ml Constitutive_self to load skills/agent/SOUL.md always-on. β recommends.
• (b) Restore content into templates/SOUL.md stub so spec/SOUL.md carries UIE-V at boot for fresh installs.
• (c) Scope-defer — soften the "Loaded once per agent boot" claim, file follow-up issue for runtime-loader patch before merge.

Per review/SKILL.md §7.0, all findings (D + B + A) are fixed-on-branch unless explicitly scope-deferred with filed issue. F4 / F5 process findings β does not require α to fix on this branch (β recommends γ records both for cycle-iteration triage).

Round 2 narrows on F1 fix shape + F2/F3/F6 dispositions. Cycle release-shape decision deferred to round 2.

---

Generated by Claude Code