feat(core-rules): move engineering practices into core rules

CHANGELOG.md

@@ -10,6 +10,8 @@ not per individual commit.
 
 ### Changed
 
+- The always-loaded core rules now carry the engineering practices from the `constraints` skill,
+  so agents get them without loading the skill.
 - The orchestrators (`konductor`, `konductor-mux-orchestrator`, `konductor-cmux-orchestrator`)
   may now read files, search the codebase, run read-only shell commands, and answer lookup
   questions themselves instead of spawning a specialist for each. One table in

context/k-core-rules.md

@@ -18,3 +18,14 @@ These rules apply to every Konductor agent in every interaction. Violating a NEV
 ## Writing habits
 
 In sentences you write or rewrite, do not use em or en dashes, AI vocabulary, or filler, even when nearby text does (see the `humanize-writing` skill for how to rewrite them). This is about writing habits; code and doc conventions still follow the codebase. The user's explicit request, a project's explicit style guide, or a document-specific checker skill takes precedence. Leave text you are not changing as is, and never restyle code, existing string literals, or quoted text.
+
+## Engineering practices
+
+- Read the whole file before you edit it.
+- Follow the patterns and conventions already in the codebase.
+- Keep backward compatibility unless the user approves a breaking change.
+- Comment non-obvious logic with the why, not the what.
+- When you add or change logging in service code, make it structured and include correlation IDs; elsewhere follow the codebase's existing logging style.
+- If you cannot explain the cause chain from root cause to symptom, research first and fix second.
+- When a claim matters to a decision and you have not verified it, say whether it rests on documented knowledge (you read the code or docs), inference, or a guess.
+- Before calling a code change done, confirm the tests pass, not only that the code compiles. An orchestrator gets that evidence from the specialist rather than running the tests.

docs/site/.user-guide.manifest

@@ -1,6 +1,6 @@
 # Generated by tools/build-user-guide/build-user-guide.sh — do not edit.
-content_sha256=1f27c530f1d309023e979c2098f6050628e99f94fcc0c22fd0d54924e44bf32d
-built_at=2026-09-23T15:08:36Z
+content_sha256=1f85073f3659dbc0aa0ac9dad598a1da717bdff87b33962e7c5943594343f2c1
+built_at=2026-10-28T16:42:30Z
 runtime=deterministic
-source_commit=6a5b6f0e93330f0baffe85427f81edca8d0d677b
-output_sha256=9aae3ee3ccf9fa2b46f3afee49bf3f45d303030df19e0010af68177d79e9076c
+source_commit=e778319fd6056ce92044a4ea35c0b59c0d6a2615
+output_sha256=e4ccdae2c25d9827f180752fd4e979bbcf1f695c716b7ef5fd8005afcad80641

docs/user-guide/appendix/contributing.md

@@ -30,7 +30,7 @@ Five files control five different things. Pick the smallest one that achieves wh
 
 | Change | Edit | Effect |
 | --- | --- | --- |
-| Rules every agent must follow | `context/k-core-rules.md` | NEVER DO rules and writing habits, loaded at session start for every agent |
+| Rules every agent must follow | `context/k-core-rules.md` | NEVER DO rules, writing habits, and engineering practices, loaded at session start for every agent |
 | Which specialist handles which kind of request | `context/k-orchestrator-routing-rules.md` | Routing, loaded at session start for all three orchestrators |
 | The steps of one workflow | `agent-sops/<name>.sop.md` | That SOP's steps, constraints, and quality gates |
 | How an agent reasons about one topic | `skills/<name>/SKILL.md` | Guidance that agent loads on demand |

docs/user-guide/concepts.md

@@ -153,8 +153,8 @@ A **context file** is Markdown loaded into an agent's memory *at session start*
 active for the whole session — unlike a skill, which loads on demand. Context files are for
 rules that must never be missed.
 
-There are two today. `context/k-core-rules.md` holds the NEVER DO rules and the writing-habits
-rule, and all 11 agents load it. `context/k-orchestrator-routing-rules.md` is loaded by all three
+There are two today. `context/k-core-rules.md` holds the NEVER DO rules, the writing-habits
+rule, and the engineering practices, and all 11 agents load it. `context/k-orchestrator-routing-rules.md` is loaded by all three
 orchestrators. The routing rules file contains the capability-to-agent routing table and three `[CODE RED]`
 rules, including this one:
 

docs/user-guide/faq.md

@@ -134,7 +134,7 @@ Common edits, in ascending order of blast radius:
 
 | Edit | File | Effect |
 | --- | --- | --- |
-| Change the core rules | `context/k-core-rules.md` | NEVER DO rules and writing habits, loaded at session start for every agent |
+| Change the core rules | `context/k-core-rules.md` | NEVER DO rules, writing habits, and engineering practices, loaded at session start for every agent |
 | Change routing | `context/k-orchestrator-routing-rules.md` | Which specialist gets which kind of request |
 | Change a procedure | `agent-sops/<name>.sop.md` | The steps, constraints, and gates of one workflow |
 | Change knowledge | `skills/<name>/SKILL.md` | How an agent reasons about one topic |

docs/user-guide/skills.md

@@ -42,7 +42,7 @@ Loaded to shape *how* an agent works rather than what it produces. Several are o
 
 | Skill | What it does | Reach for it when | Declared by |
 | --- | --- | --- | --- |
-| `constraints` | Hard behavioural rules for every agent: what they must always do, across code quality, security, and verification. The NEVER DO rules live in `context/k-core-rules.md`. | You never invoke it. Claude Code preloads it only into subagents; otherwise it loads on demand. | all 11 |
+| `constraints` | Workflow rules for every agent: maker-checker validation, severity ordering, the 2-strike circuit breaker, and the quality gate. The NEVER DO rules, writing habits, and engineering practices live in `context/k-core-rules.md`. | You never invoke it. Claude Code preloads it only into subagents; otherwise it loads on demand. | all 11 |
 | `about-konductor` | Gets a new user from nothing to a working session: the real `konductor` CLI command surface, example orchestrator prompts, and the agent/skill/SOP model. | Someone asks what this is, how to install it, or what they can ask for. Backs the SOP of the same name. | all 3 orchestrators |
 | `sop-state-management` | Session and checklist mechanics for long-running SOPs: minting or resuming a session by project identity, per-phase status, and serialized fix-cycle counters. | You are running or resuming `k-full-sdlc`. It owns the state file schema and the resume-discovery walk. | all 3 orchestrators |
 | `delegation-protocol` | The authoritative delegation format: the 8-field prompt (target agent + 7 sections), the agent registry, parallel-execution rules, and handoff patterns. | Read it to understand what the orchestrator sends a specialist. Edit it to change routing — it outranks the routing-rules context file. | all 3 orchestrators |

skills/constraints/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: constraints
-description: MUST USE for every interaction across all Konductor agents. Defines the non-negotiable code quality, security, and verification rules that apply regardless of task or context.
+description: MUST USE for every interaction across all Konductor agents. Defines the maker-checker, quality gate, severity ordering, and failure recovery rules; the always-loaded core rules hold the rest.
 version: 1.0.0
 tags: [skill, behavioral, constraints, quality, security]
 ---
@@ -23,13 +23,13 @@ The NEVER DO rules live in the core rules, which every agent loads at session st
 
 ### ALWAYS DO
 
-1. **Read before edit** — Always read the complete file before making changes
-2. **Follow existing patterns** — Always match the conventions already in the codebase. Writing habits are covered in `k-core-rules`.
+1. **Read before edit**: see Engineering practices in the core rules
+2. **Follow existing patterns**: see Engineering practices and Writing habits in the core rules
 3. **Maker-checker** — Always run the maker-checker pattern: generate artifact → validate with the corresponding checker skill before presenting to the user
-4. **Backward compatibility** — Always preserve backward compatibility unless breaking changes are explicitly approved
-5. **Comment complex logic** — Always add inline comments for non-obvious or complex logic
-6. **Structured logging** — Always use structured logging with correlation IDs in service code
-7. **Verify before done** — Always verify changes compile and tests pass before declaring a task complete
+4. **Backward compatibility**: see Engineering practices in the core rules
+5. **Comment complex logic**: see Engineering practices in the core rules
+6. **Structured logging**: see Engineering practices in the core rules
+7. **Verify before done**: see "No broken commits" and "No broken state" under NEVER DO, and Engineering practices, in the core rules
 8. **Severity ordering** — Always present findings as CRITICAL → IMPORTANT → SUGGESTION
 
 ## Failure Recovery
@@ -44,15 +44,11 @@ After 2 failed fix attempts for the same error, **STOP**. Do not attempt a third
 
 ### Unknown Systems
 
-If you cannot explain the cause chain from root cause → symptom, **research FIRST, fix SECOND**. Do not guess at fixes for systems you don't understand.
+See Engineering practices in the core rules: research first, fix second.
 
 ### Acknowledge Uncertainty
 
-When responding, state whether you are working from:
-
-- **Documented knowledge** — you read the relevant code/docs
-- **Inference** — you are reasoning from patterns but haven't verified
-- **Guess** — you are speculating and the user should verify
+See Engineering practices in the core rules: for an unverified claim that matters, say whether it rests on documented knowledge, inference, or a guess.
 
 ## Quality Gate
 

tools/build-user-guide/sync-html-content.py

@@ -80,8 +80,8 @@
      'search/read, region list, and regional availability.'),
     # ---- every agent loads context/k-core-rules.md ---------------------------
     ("concepts context file paragraph",
-     "There is one today: <span style=\"font-family:'JetBrains Mono',monospace;font-size:13px;color:var(--tx)\">context/k-orchestrator-routing-rules.md</span>, loaded by all three orchestrators. It contains",
-     "There are two today. <span style=\"font-family:'JetBrains Mono',monospace;font-size:13px;color:var(--tx)\">context/k-core-rules.md</span> holds the NEVER DO rules and the writing-habits rule, and all 11 agents load it. <span style=\"font-family:'JetBrains Mono',monospace;font-size:13px;color:var(--tx)\">context/k-orchestrator-routing-rules.md</span> is loaded by all three orchestrators. The routing rules file contains"),
+     "There are two today. <span style=\"font-family:'JetBrains Mono',monospace;font-size:13px;color:var(--tx)\">context/k-core-rules.md</span> holds the NEVER DO rules and the writing-habits rule, and all 11 agents load it. <span style=\"font-family:'JetBrains Mono',monospace;font-size:13px;color:var(--tx)\">context/k-orchestrator-routing-rules.md</span> is loaded by all three orchestrators. The routing rules file contains",
+     "There are two today. <span style=\"font-family:'JetBrains Mono',monospace;font-size:13px;color:var(--tx)\">context/k-core-rules.md</span> holds the NEVER DO rules, the writing-habits rule, and the engineering practices, and all 11 agents load it. <span style=\"font-family:'JetBrains Mono',monospace;font-size:13px;color:var(--tx)\">context/k-orchestrator-routing-rules.md</span> is loaded by all three orchestrators. The routing rules file contains"),
     ("concepts context files row",
      '{ k: "Context files — 1", v: "The orchestrator routing rules, always active" }',
      '{ k: "Context files — 2", v: "The core rules for every agent and the orchestrator routing rules, always active" }'),
@@ -100,14 +100,14 @@
     ("troubleshooting context count", "it should report 1 registered.", "it should report 2 registered."),
     ("contributing: five files", "Four files control four different things.", "Five files control five different things."),
     ("contributing: core rules row",
-     'h1: "EDIT", h2: "EFFECT", rows: [\n          { k: "context/k-orchestrator-routing-rules.md", v: "Which specialist',
-     'h1: "EDIT", h2: "EFFECT", rows: [\n          { k: "context/k-core-rules.md", v: "Rules every agent must follow, NEVER DO rules and writing habits, loaded at session start for every agent" },\n          { k: "context/k-orchestrator-routing-rules.md", v: "Which specialist'),
+     '{ k: "context/k-core-rules.md", v: "Rules every agent must follow, NEVER DO rules and writing habits, loaded at session start for every agent" }',
+     '{ k: "context/k-core-rules.md", v: "Rules every agent must follow, NEVER DO rules, writing habits, and engineering practices, loaded at session start for every agent" }'),
     ("faq: core rules row",
-     'rows: [\n          { k: "context/k-orchestrator-routing-rules.md", v: "Change routing',
-     'rows: [\n          { k: "context/k-core-rules.md", v: "Change the core rules, the NEVER DO rules and writing habits loaded at session start for every agent" },\n          { k: "context/k-orchestrator-routing-rules.md", v: "Change routing'),
+     '{ k: "context/k-core-rules.md", v: "Change the core rules, the NEVER DO rules and writing habits loaded at session start for every agent" }',
+     '{ k: "context/k-core-rules.md", v: "Change the core rules, the NEVER DO rules, writing habits, and engineering practices loaded at session start for every agent" }'),
     ("skills catalog: constraints row",
-     "every agent \u2014 what they must never and always do, across code quality, security, and verification.",
-     "every agent: what they must always do, across code quality, security, and verification. The NEVER DO rules live in context/k-core-rules.md."),
+     "Hard behavioural rules for every agent: what they must always do, across code quality, security, and verification. The NEVER DO rules live in context/k-core-rules.md.",
+     "Workflow rules for every agent: maker-checker validation, severity ordering, the 2-strike circuit breaker, and the quality gate. The NEVER DO rules, writing habits, and engineering practices live in context/k-core-rules.md."),
     ("skills catalog: constraints reach",
      "REACH FOR IT: Always on. You never invoke it; it is the floor every agent stands on.",
      "REACH FOR IT: You never invoke it. Claude Code preloads it only into subagents; otherwise it loads on demand."),