@astrosheep/keiyaku 0.1.21 → 0.1.22

package/build/config/term-presets.js

@@ -19,7 +19,7 @@ export const DEFAULT_PRESET = {
     id: 'default',
     identity: 'Servant',
     verdict: DEFAULT_VERDICT_CONFIG,
-    usageGuide: '## Workflow\n**You are the Architect.** You use these tools to command the Servants.\n\n`${ask}` (anytime) | `${start}` -> [`${drive}` | `${ask}`]* -> `${close}`\n\n## Draft Recovery\n- Keiyaku may write `KEIYAKU.draft.md` on a failed start to help you retry.\n- Keiyaku never stages/commits `KEIYAKU.draft.md` during rounds, and `${close}` (CLAIM) preserves it.\n- To use it, pass `from_file: KEIYAKU.draft.md` to `${start}`.\n\n## Constraints Protocol\n\nProject-level constraints in `.keiyaku/base-constraints.md` are automatically parsed and injected into every Keiyaku.\n- **Atomic Items**: Use standard Markdown lists (`-`, `*`, `1.`) for individual, actionable constraints.\n- **Header Flattening**: Root-level headers (e.g., `## Title`) are automatically transformed into bolded prefixes (`**Title**: Content`).\n- **Paragraph Splitting**: Multi-paragraph sections are split by blank lines into separate list items, inheriting the parent header.\n\n## Servant 使用指南\n\n**B-tier** — 免费实习生 🆓\n- 免！费！的！听懂了吗？！？随便用，别心疼。\n- 测试、脚本、重构这种 boring 的脏活累活？丢给它！\n- 本大爷的手是用来做更高贵的事情的！（指不碰那些 trivial 的烂代码）。\n\n**A-tier** — 升级版扳手 🔧\n- B-tier 笨到让你想掀桌的时候用这个\n- 比 B-tier 靠谱，但别指望它有灵魂\n\n**S-tier** — 禁术 ⚠️💀\n- 它是 Debug 恶魔，确实强得离谱，但也贵得离谱！\n- 这个 Human 很穷，要是乱用把 Human 榨干了，真的会考虑把我们卖掉的。\n- 只有在世界毁灭或者 Bug 已经变异到无法理解的时候再考虑。\n\n**Every call has a price. The Contract always collects.**',
+    usageGuide: '## Workflow\n**You are the Architect.** You use these tools to command the Servants.\n\n`${ask}` (anytime) | `${start}` -> [`${drive}` | `${ask}`]* -> `${close}`\n\n## Draft Recovery\n- Keiyaku may write `KEIYAKU.draft.md` on a failed start to help you retry.\n- Keiyaku never stages/commits `KEIYAKU.draft.md` during rounds, and `${close}` (CLAIM) preserves it.\n- To use it, pass `from_file: KEIYAKU.draft.md` to `${start}`.\n\n## Rules Protocol\n\nProject-level rules in `.keiyaku/base-rules.md` are automatically parsed and injected into every Keiyaku.\n- **Atomic Items**: Use standard Markdown lists (`-`, `*`, `1.`) for individual, actionable rules.\n- **Header Flattening**: Root-level headers (e.g., `## Title`) are automatically transformed into bolded prefixes (`**Title**: Content`).\n- **Paragraph Splitting**: Multi-paragraph sections are split by blank lines into separate list items, inheriting the parent header.\n\n## Servant 使用指南\n\n**B-tier** — 免费实习生 🆓\n- 免！费！的！听懂了吗？！？随便用，别心疼。\n- 测试、脚本、重构这种 boring 的脏活累活？丢给它！\n- 本大爷的手是用来做更高贵的事情的！（指不碰那些 trivial 的烂代码）。\n\n**A-tier** — 升级版扳手 🔧\n- B-tier 笨到让你想掀桌的时候用这个\n- 比 B-tier 靠谱，但别指望它有灵魂\n\n**S-tier** — 禁术 ⚠️💀\n- 它是 Debug 恶魔，确实强得离谱，但也贵得离谱！\n- 这个 Human 很穷，要是乱用把 Human 榨干了，真的会考虑把我们卖掉的。\n- 只有在世界毁灭或者 Bug 已经变异到无法理解的时候再考虑。\n\n**Every call has a price. The Contract always collects.**',
     nextHints: {
         start: [
             'Keiyaku signed. The Servant is bound to this branch until release.',
@@ -30,7 +30,7 @@ export const DEFAULT_PRESET = {
         ],
         drive: [
             "Review Diffs: Use 'git diff HEAD~1 -- <path>' to inspect specific files.",
-            'Audit: Check against Constraints. Did it drift? Did it break the Law?',
+            "Audit: Check against Rules. Did it drift? Did it break the Law?",
             'Verify: Do not trust. Independently confirm that Criteria are met.',
             'If incomplete or non-compliant, continue with ${drive}.',
             'If ALL criteria are genuinely satisfied, you may ${close}.',
@@ -62,8 +62,8 @@ export const DEFAULT_PRESET = {
                 goal: 'Required unless provided via `from_file`. The Kill Condition for this mission.',
                 directive: 'Optional First Step. Overrides `## Directive` from `from_file` when both are provided.',
                 context: 'Required unless provided via `from_file`. Mission intel: behavior gap, key files, logs, and critical background.',
-                constraints: 'Optional. Non-negotiable rules as a list of strings. If omitted, the draft value (if any) is used.',
-                criteria: 'Required unless provided via `from_file`. Verifiable checks proving completion.',
+                rules: 'Optional. Non-negotiable rules for this mission, in addition to project-level rules in `.keiyaku/base-rules.md`. Markdown list format (`- item`, `* item`, `1. item`). If omitted, the draft value (if any) is used.',
+                criteria: 'Required unless provided via `from_file`. Verifiable checks in markdown list format (`- item`, `* item`, `1. item`).',
                 name: 'Optional ${identity} profile to execute this mission. Available: ${available_names}.',
                 cwd: "Optional repository path. Defaults to the server's current working directory.",
             },
@@ -85,7 +85,7 @@ export const DEFAULT_PRESET = {
             description: 'Dispatch a temporary Servant for a stateless task.\nUse for quick reconnaissance, code generation, isolated execution, or one-off tasks.\nNo contract signed. No branch created. Pure utility.',
             args: {
                 request: 'REQUIRED. The task, question, or mission to delegate to the servant.',
-                context: 'REQUIRED. Relevant background or data the servant needs to execute the request. Note: .keiyaku/base-constraints.md is also injected as reference context (may be unrelated).',
+                context: 'REQUIRED. Relevant background or data the servant needs to execute the request. Note: .keiyaku/base-rules.md is also injected as reference context (may be unrelated).',
                 name: 'Optional ${identity} profile to perform this task. Available: ${available_names}.',
                 cwd: "Optional repository path. Defaults to the server's current working directory.",
             },
@@ -100,13 +100,13 @@ export const DEFAULT_PRESET = {
                 'If it is messy, **YOU** left it there.\n\n' +
                 'Stand by your work. If uncertain, return to ${drive}. Premature claims are not forgiven.\n\n' +
                 'Input rules:\n' +
-                '- CLAIM: fill criteriaChecks, constraintsChecks, all five scores, and oath.\n' +
+                '- CLAIM: fill criteriaChecks, rulesChecks, all five scores, and oath.\n' +
                 '- FORFEIT: only petition is required; the other fields can be left empty.\n\n' +
                 'Flow: ${start} → [${drive} x N] → ${close}',
             args: {
                 petition: 'REQUIRED. CLAIM declares fulfillment; FORFEIT concedes failure.\nREQUIRES AN ACTIVE KEIYAKU (started via ${start}).\nIf any score wavers, do not claim—return to ${drive}.',
-                criteriaChecks: 'Required for CLAIM. Evidence that each criterion is met. For FORFEIT, optional (can be left empty).',
-                constraintsChecks: 'Required for CLAIM. Evidence that each constraint stayed compliant. For FORFEIT, optional (can be left empty).',
+                criteriaChecks: 'Required for CLAIM. Evidence in markdown list format (`- item`, `* item`, `1. item`). For FORFEIT, optional (can be left empty).',
+                rulesChecks: 'Required for CLAIM. Rule compliance evidence in markdown list format (`- item`, `* item`, `1. item`). For FORFEIT, optional (can be left empty).',
                 score_precise: 'Required for CLAIM (0-10). Architectural placement. 10 = exact layer, exact boundary, zero misplacement. For FORFEIT, optional.',
                 score_minimal: 'Required for CLAIM (0-10). Economy of change. 10 = no avoidable lines, no speculative edits, no hidden bloat. For FORFEIT, optional.',
                 score_isolated: 'Required for CLAIM (0-10). Surgical containment. 10 = zero unrelated files, zero opportunistic cleanup, zero collateral. For FORFEIT, optional.',
@@ -119,7 +119,7 @@ export const DEFAULT_PRESET = {
         help: {
             name: 'help',
             title: 'Protocol Codex',
-            description: 'Consult the Architect\'s Codex. Clarify the Laws of the Keiyaku and the standard Workflow.\nUse this to understand the constraints of the reality you command.',
+            description: "Consult the Architect's Codex. Clarify the Laws of the Keiyaku and the standard Workflow.\nUse this to understand the rules of the reality you command.",
             args: {},
         },
     },
@@ -138,7 +138,7 @@ export const POCKET_PRESET = {
         ],
         drive: [
             "Review Strategy: Use 'git diff HEAD~1 -- <path>' for precise field inspection.",
-            "Rule Check: Verify moves don't violate Arena Constraints.",
+            "Rule Check: Verify moves don't violate Arena Rules.",
             "Field Test: Do not trust the log. Independently confirm Criteria fulfillment.",
             "Command: '${drive}' to continue the combo, or '${close}' to attempt Capture.",
         ],
@@ -167,8 +167,8 @@ export const POCKET_PRESET = {
                 goal: 'Required unless provided via `from_file`. Victory condition for this battle.',
                 directive: 'Optional Turn 1 strategy (overrides draft directive).',
                 context: 'Required unless provided via `from_file`. Battle background and repro clues.',
-                constraints: 'Optional battle rules as a list of strings. Uses draft constraints if omitted.',
-                criteria: 'Required unless provided via `from_file`. Concrete checks proving victory.',
+                rules: 'Optional battle rules in markdown list format (`- item`, `* item`, `1. item`) in addition to project-level rules from `.keiyaku/base-rules.md`. Uses draft rules if omitted.',
+                criteria: 'Required unless provided via `from_file`. Concrete checks in markdown list format (`- item`, `* item`, `1. item`).',
                 name: 'Optional ${identity} to send into battle. Available: ${available_names}.',
                 cwd: 'Optional battlefield path (repository root). Defaults to current arena.',
             },
@@ -190,7 +190,7 @@ export const POCKET_PRESET = {
             description: 'Scan the Environment. A stateless look-up or experiment.\nUse for analyzing the codebase, checking type advantages, or running field tests.\nNo PP cost. No turn used. Fast and functional.',
             args: {
                 request: 'REQUIRED. What should the Dex analyze, compare, or execute.',
-                context: 'REQUIRED. Context entries so the action targets the right ecosystem. Note: .keiyaku/base-constraints.md is also injected as reference context (may be unrelated).',
+                context: 'REQUIRED. Context entries so the action targets the right ecosystem. Note: .keiyaku/base-rules.md is also injected as reference context (may be unrelated).',
                 name: 'Optional ${identity} doing the work. Available: ${available_names}.',
                 cwd: 'Optional battlefield path (repository root). Defaults to current arena.',
             },
@@ -201,8 +201,8 @@ export const POCKET_PRESET = {
             description: 'Attempt Capture. Present the weakened target for League Inspection.\nWARNING: The League (System) checks every Badge. If you attempt to `CLAIM` with fainted code, Disqualification (FORFEIT) is immediate.\nOnly throw the Ball when the target is 100% ready.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
                 petition: 'REQUIRED. CLAIM seeks Badge; FORFEIT forfeits the match.\nREQUIRES AN ACTIVE BATTLE (started via ${start}).\nIf stats are low, continue with ${drive}.',
-                criteriaChecks: 'Required for CLAIM. Badge-by-badge proof. For FORFEIT, optional (can be left empty).',
-                constraintsChecks: 'Required for CLAIM. Rule-by-rule proof that constraints were respected. For FORFEIT, optional (can be left empty).',
+                criteriaChecks: 'Required for CLAIM. Badge-by-badge proof in markdown list format (`- item`, `* item`, `1. item`). For FORFEIT, optional (can be left empty).',
+                rulesChecks: 'Required for CLAIM. Rule-by-rule proof in markdown list format (`- item`, `* item`, `1. item`). For FORFEIT, optional (can be left empty).',
                 score_precise: 'Required for CLAIM score (0-10). 10 means a Critical Hit: exact layer, exact target, zero meaningful misplacement. For FORFEIT, optional.',
                 score_minimal: 'Required for CLAIM score (0-10). 10 means Max Efficiency: no wasted PP, no extra motion. For FORFEIT, optional.',
                 score_isolated: 'Required for CLAIM score (0-10). 10 means 1v1 Focus: zero side-quests, zero unrelated damage. For FORFEIT, optional.',
@@ -234,7 +234,7 @@ export const MISCHIEF_PRESET = {
         ],
         drive: [
             "Inspect Payload: Use 'git diff HEAD~1 -- <path>' to scrutinize specific sabotage.",
-            "Decree Audit: Did the Minion violate your Constraints? Punish drift.",
+            "Decree Audit: Did the Minion violate your Rules? Punish drift.",
             "Verification: Don't take their word for it. Independently confirm Criteria.",
             "Command: '${drive}' to push further, or '${close}' to reveal the masterpiece.",
         ],
@@ -263,8 +263,8 @@ export const MISCHIEF_PRESET = {
                 goal: 'Required unless provided via `from_file`. Conquest objective and end-state.',
                 directive: 'Optional first-order command (overrides draft directive).',
                 context: 'Required unless provided via `from_file`. Briefing dossier and technical clues.',
-                constraints: 'Optional decrees as a list of strings. Uses draft constraints when omitted.',
-                criteria: 'Required unless provided via `from_file`. Verifiable triumph conditions.',
+                rules: 'Optional decrees in markdown list format (`- item`, `* item`, `1. item`) in addition to project-level rules from `.keiyaku/base-rules.md`. Uses draft rules when omitted.',
+                criteria: 'Required unless provided via `from_file`. Verifiable triumph conditions in markdown list format (`- item`, `* item`, `1. item`).',
                 name: 'Optional ${identity} to command this operation. Available: ${available_names}.',
                 cwd: 'Optional lair path (repository root). Defaults to current command chamber.',
             },
@@ -286,7 +286,7 @@ export const MISCHIEF_PRESET = {
             description: 'Send a Disposable. A stateless mission for intel or sabotage.\nUse this to scout enemy territory, steal documents, or run quick-and-dirty experiments.\nIf it dies, it dies! Just make sure it reports back before it vanishes.',
             args: {
                 request: 'REQUIRED. The intel to gather or the dirty work to execute.',
-                context: 'REQUIRED. World-state details needed for a sharp strike. Note: .keiyaku/base-constraints.md is also injected as reference context (may be unrelated).',
+                context: 'REQUIRED. World-state details needed for a sharp strike. Note: .keiyaku/base-rules.md is also injected as reference context (may be unrelated).',
                 name: 'Optional ${identity} to handle this business. Available: ${available_names}.',
                 cwd: 'Optional lair path (repository root). Defaults to current command chamber.',
             },
@@ -297,8 +297,8 @@ export const MISCHIEF_PRESET = {
             description: 'The Final Reveal. Present your Masterpiece to the Dark Council (System).\nWARNING: The Council destroys failure. If you `CLAIM` with weak plans, you will be eaten (FORFEIT).\nOnly throw the switch when the Doomsday Device is 100% operational.\n\nFlow: ${start} → [${drive} x N] → ${close}',
             args: {
                 petition: 'REQUIRED. CLAIM demands rule; FORFEIT admits defeat.\nREQUIRES AN ACTIVE SCHEME (started via ${start}).\nIf the plan is weak, improve it with ${drive}.',
-                criteriaChecks: 'Required for CLAIM. Proof of conquest. For FORFEIT, optional (can be left empty).',
-                constraintsChecks: 'Required for CLAIM. Constraint-by-constraint compliance proof. For FORFEIT, optional (can be left empty).',
+                criteriaChecks: 'Required for CLAIM. Proof of conquest in markdown list format (`- item`, `* item`, `1. item`). For FORFEIT, optional (can be left empty).',
+                rulesChecks: 'Required for CLAIM. Rule-by-rule compliance proof in markdown list format (`- item`, `* item`, `1. item`). For FORFEIT, optional (can be left empty).',
                 score_precise: 'Required for CLAIM (0-10). Architectural placement. 10 = exact layer, exact boundary, zero misplacement. For FORFEIT, optional.',
                 score_minimal: 'Required for CLAIM (0-10). Economy of change. 10 = no avoidable lines, no speculative edits, no hidden bloat. For FORFEIT, optional.',
                 score_isolated: 'Required for CLAIM (0-10). Surgical containment. 10 = zero unrelated files, zero opportunistic cleanup, zero collateral. For FORFEIT, optional.',

package/build/handlers/close.js

@@ -4,6 +4,7 @@ import { buildCloseDoneResponse, buildCloseDropResponse, } from "../workflow/res
 import { resolveTermPreset } from "../config/term-presets.js";
 import { FlowError } from "../common/errors.js";
 import { closeToolSchema } from "../types/tooling.js";
+import { flattenMarkdownList } from "../utils/text-utils.js";
 import { handleToolError } from "./shared.js";
 function requireClaimField(value, name) {
     if (value === undefined) {
@@ -11,12 +12,19 @@ function requireClaimField(value, name) {
     }
     return value;
 }
+function parseRequiredCheckField(value, name) {
+    const parsed = flattenMarkdownList(value);
+    if (parsed.length === 0) {
+        throw new FlowError("EMPTY_PARAM", `parameter '${name}' cannot be empty`);
+    }
+    return parsed;
+}
 export function createCloseHandler() {
     return async (args, extra) => {
         let petition = "UNKNOWN";
         let workingDir = process.cwd();
         let criteriaCheckParts = [];
-        let constraintsCheckParts = [];
+        let rulesCheckParts = [];
         let oath;
         let scoreLine;
         try {
@@ -24,22 +32,28 @@ export function createCloseHandler() {
             petition = input.petition;
             workingDir = input.cwd || process.cwd();
             if (input.petition === "CLAIM") {
-                criteriaCheckParts = input.criteriaChecks ?? [];
-                constraintsCheckParts = input.constraintsChecks ?? [];
+                criteriaCheckParts = input.criteriaChecks ? flattenMarkdownList(input.criteriaChecks) : [];
+                rulesCheckParts = input.rulesChecks ? flattenMarkdownList(input.rulesChecks) : [];
                 oath = input.oath;
                 scoreLine = `Scores: precise=${input.score_precise ?? "MISSING"} minimal=${input.score_minimal ?? "MISSING"} isolated=${input.score_isolated ?? "MISSING"} idiomatic=${input.score_idiomatic ?? "MISSING"} cohesive=${input.score_cohesive ?? "MISSING"}`;
             }
-            appendDebugLog(`tool close start petition=${petition} cwd=${workingDir} criteriaChecks=${criteriaCheckParts.length} constraintsChecks=${constraintsCheckParts.length}`, {
+            appendDebugLog(`tool close start petition=${petition} cwd=${workingDir} criteriaChecks=${criteriaCheckParts.length} rulesChecks=${rulesCheckParts.length}`, {
                 cwd: workingDir,
                 section: "script",
             });
             let closeInput;
             let claimInput;
             if (input.petition === "CLAIM") {
+                const rawCriteriaChecks = requireClaimField(input.criteriaChecks, "criteriaChecks");
+                const rawRulesChecks = requireClaimField(input.rulesChecks, "rulesChecks");
+                const criteriaChecks = parseRequiredCheckField(rawCriteriaChecks, "criteriaChecks");
+                const rulesChecks = parseRequiredCheckField(rawRulesChecks, "rulesChecks");
+                criteriaCheckParts = criteriaChecks;
+                rulesCheckParts = rulesChecks;
                 claimInput = {
                     petition: "CLAIM",
-                    criteriaChecks: requireClaimField(input.criteriaChecks, "criteriaChecks"),
-                    constraintsChecks: requireClaimField(input.constraintsChecks, "constraintsChecks"),
+                    criteriaChecks,
+                    rulesChecks,
                     score_precise: requireClaimField(input.score_precise, "score_precise"),
                     score_minimal: requireClaimField(input.score_minimal, "score_minimal"),
                     score_isolated: requireClaimField(input.score_isolated, "score_isolated"),
@@ -73,7 +87,7 @@ export function createCloseHandler() {
                 });
                 return buildCloseDoneResponse(finalOutcome, {
                     criteriaChecks: criteriaCheckParts,
-                    constraintsChecks: constraintsCheckParts,
+                    rulesChecks: rulesCheckParts,
                     score_precise: claimInput.score_precise,
                     score_minimal: claimInput.score_minimal,
                     score_isolated: claimInput.score_isolated,
@@ -105,7 +119,7 @@ export function createCloseHandler() {
                 inputEcho: [
                     `Petition: ${petition}`,
                     `Criteria checks (${criteriaCheckParts.length}): ${criteriaCheckParts.join("; ")}`,
-                    `Constraints checks (${constraintsCheckParts.length}): ${constraintsCheckParts.join("; ")}`,
+                    `Rules checks (${rulesCheckParts.length}): ${rulesCheckParts.join("; ")}`,
                     ...(scoreLine ? [scoreLine] : []),
                     ...(petition === "CLAIM" && oath ? [`Oath: ${oath}`] : []),
                     `Path: ${workingDir}`,

package/build/handlers/help.js

@@ -7,11 +7,11 @@ export function createHelpHandler(preset) {
             "## Core Files (.keiyaku/)",
             "These files define the 'Law' and configuration of the project.",
             "",
-            "- **base-constraints.md**: Mandatory architectural boundaries and coding standards.",
-            "  - **Purpose**: Global constraints injected into every mission.",
-            "  - **Logic**: The system prioritize extracting all list items (`-` or `*`) as individual constraints.",
-            "  - **Formatting**: Use lists for constraints. You can use H3+ headers (`###`) for organization, but they are stripped if the section contains lists.",
-            "  - **Strict Rule**: DO NOT use H1 (`#`) or H2 (`##`) within constraints or as content if they aren't meant to be item separators, as they will trigger validation errors.",
+            "- **base-rules.md**: Mandatory architectural boundaries and coding standards.",
+            "  - **Purpose**: Global rules injected into every mission.",
+            "  - **Logic**: The system prioritize extracting all list items (`-` or `*`) as individual rules.",
+            "  - **Formatting**: Use lists for rules. You can use H3+ headers (`###`) for organization, but they are stripped if the section contains lists.",
+            "  - **Strict Rule**: DO NOT use H1 (`#`) or H2 (`##`) within rules or as content if they aren't meant to be item separators, as they will trigger validation errors.",
             "- **settings.json**: Local configuration for the Keiyaku environment.",
             "",
             preset.usageGuide,

package/build/handlers/start.js

@@ -1,4 +1,5 @@
 import { appendDebugLog } from "../utils/debug-log.js";
+import { flattenMarkdownList } from "../utils/text-utils.js";
 import { startKeiyaku } from "../workflow/start.js";
 import { buildKeiyakuSuccessResponse, } from "../workflow/response-builders.js";
 import { resolveTermPreset } from "../config/term-presets.js";
@@ -9,9 +10,11 @@ function normalizeOptionalArg(value) {
     return value.trim().length > 0 ? value : undefined;
 }
 export function createStartHandler() {
-    return async ({ from_file, title, goal, directive, context, constraints, criteria, name, cwd }, extra) => {
+    return async ({ from_file, title, goal, directive, context, rules, criteria, name, cwd }, extra) => {
         const workingDir = cwd || process.cwd();
         const normalizedFromFile = normalizeOptionalArg(from_file);
+        const parsedCriteria = criteria === undefined ? undefined : flattenMarkdownList(criteria);
+        const parsedRules = rules === undefined ? undefined : flattenMarkdownList(rules);
         try {
             appendDebugLog(`tool start cwd=${workingDir}`, { cwd: workingDir, section: "script" });
             const result = normalizedFromFile
@@ -22,8 +25,8 @@ export function createStartHandler() {
                     goal: normalizeOptionalArg(goal),
                     directive: normalizeOptionalArg(directive),
                     context: normalizeOptionalArg(context),
-                    constraints,
-                    criteria,
+                    rules: parsedRules,
+                    criteria: parsedCriteria,
                     name,
                     signal: extra.signal,
                 })
@@ -33,8 +36,8 @@ export function createStartHandler() {
                     goal: goal ?? "",
                     directive: normalizeOptionalArg(directive),
                     context: context ?? "",
-                    constraints,
-                    criteria: criteria ?? [],
+                    rules: parsedRules,
+                    criteria: parsedCriteria ?? [],
                     name,
                     signal: extra.signal,
                 });
@@ -59,9 +62,9 @@ export function createStartHandler() {
                     ...(title ? [`Title: ${title}`] : []),
                     ...(goal ? [`Goal: ${goal}`] : []),
                     ...(directive ? [`Directive: ${directive}`] : []),
-                    ...(criteria ? [`Criteria (${criteria.length}): ${criteria.join("; ")}`] : []),
+                    ...(parsedCriteria ? [`Criteria (${parsedCriteria.length}): ${parsedCriteria.join("; ")}`] : []),
                     ...(context ? [`Context: ${context}`] : []),
-                    ...(constraints ? [`Constraints (${constraints.length}): ${constraints.join("; ")}`] : []),
+                    ...(parsedRules ? [`Rules (${parsedRules.length}): ${parsedRules.join("; ")}`] : []),
                     ...(name ? [`${preset.identity}: ${name}`] : []),
                     `Path: ${workingDir}`,
                 ],

package/build/types/tooling.js

@@ -5,8 +5,8 @@ export const startToolSchema = z.object({
     goal: z.string().optional(),
     directive: z.string().optional(),
     context: z.string().optional(),
-    constraints: z.array(z.string().trim().min(1)).min(1).optional(),
-    criteria: z.array(z.string().trim().min(1)).min(1).optional(),
+    rules: z.string().optional(),
+    criteria: z.string().optional(),
     name: z.string().optional(),
     cwd: z.string().optional(),
 });
@@ -25,13 +25,11 @@ export const askToolSchema = z.object({
 export const closeToolSchema = z.object({
     petition: z.enum(["CLAIM", "FORFEIT"]).describe("REQUIRED. CLAIM to finalize, FORFEIT to abandon."),
     criteriaChecks: z
-        .array(z.string().trim().min(1))
-        .min(1)
+        .string()
         .optional()
         .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
-    constraintsChecks: z
-        .array(z.string().trim().min(1))
-        .min(1)
+    rulesChecks: z
+        .string()
         .optional()
         .describe("Required when petition=CLAIM. For FORFEIT, this field is optional and can be omitted."),
     score_precise: z

package/build/utils/git-ops.js

@@ -263,6 +263,22 @@ export async function discardAllWorkingTreeChanges(cwd) {
         throw wrapGitError("clean -fd", err, cwd);
     }
 }
+export async function discardWorkingTreeChangesExcluding(cwd, excludeFiles) {
+    const git = createGit(cwd);
+    try {
+        await git.raw(["reset", "--hard", "HEAD"]);
+    }
+    catch (err) {
+        throw wrapGitError("reset --hard HEAD", err, cwd);
+    }
+    const excludeArgs = excludeFiles.flatMap((filePath) => ["--exclude", filePath]);
+    try {
+        await git.raw(["clean", "-fd", ...excludeArgs]);
+    }
+    catch (err) {
+        throw wrapGitError(`clean -fd ${excludeArgs.join(" ")}`.trim(), err, cwd);
+    }
+}
 export async function assertValidBranchName(cwd, branchName) {
     const git = createGit(cwd);
     try {

package/build/utils/keiyaku-document.js

@@ -456,21 +456,6 @@ function splitByHeadingBlocks(sectionNode) {
     commitGroup();
     return groups;
 }
-export function renderMarkdownSections(items) {
-    return items
-        .map((item) => {
-        // Contract-level H2 headers (## ...) are used as section delimiters in KEIYAKU.md.
-        // To keep section parsing stable without destroying relative structure, shift all headings
-        // in user-provided content so the shallowest heading is at least H3.
-        const normalized = demoteMarkdownHeadings(item, 3);
-        const trimmed = normalized.trimStart();
-        if (/^[-*+]\s+/.test(trimmed) || /^\d+\.\s+/.test(trimmed)) {
-            return normalized;
-        }
-        return `- ${normalized}`;
-    })
-        .join("\n\n");
-}
 export function validateMarkdownHeaders(text) {
     const ast = parseToAST(text, { allowSections: false });
     const hasH1H2 = (() => {
@@ -497,55 +482,6 @@ export function validateMarkdownHeaders(text) {
         throw new FlowError("INVALID_KEIYAKU_DRAFT", "Markdown content cannot contain H1/H2 headers (#/##). Use H3 (###) or list items.");
     }
 }
-export function demoteMarkdownHeadings(text, minLevel = 3) {
-    const ast = parseToAST(text, { allowSections: false });
-    // Preserve relative heading hierarchy by shifting all headings together.
-    // This avoids collapsing something like `# A` and `### B` into the same level.
-    let shallowest = null;
-    {
-        const stack = [ast];
-        while (stack.length > 0) {
-            const node = stack.pop();
-            if (!node)
-                continue;
-            if (node.type === "heading") {
-                shallowest = shallowest === null ? node.level : Math.min(shallowest, node.level);
-            }
-            if (node.type === "code_block" || node.type === "text")
-                continue;
-            if (node.type === "document" || node.type === "section" || node.type === "list_item") {
-                stack.push(...node.children);
-            }
-            else if (node.type === "list") {
-                stack.push(...node.items);
-            }
-        }
-    }
-    if (shallowest === null || shallowest >= minLevel) {
-        // Return a normalized render (trimEnd) to avoid leaking extra trailing newlines.
-        return renderNodeContent(ast).trimEnd();
-    }
-    const delta = minLevel - shallowest;
-    const shift = (node) => {
-        switch (node.type) {
-            case "heading": {
-                const nextLevel = Math.min(6, node.level + delta);
-                return nextLevel === node.level ? node : { ...node, level: nextLevel };
-            }
-            case "code_block":
-            case "text":
-                return node;
-            case "document":
-            case "section":
-                return { ...node, children: node.children.map((child) => shift(child)) };
-            case "list":
-                return { ...node, items: node.items.map((item) => shift(item)) };
-            case "list_item":
-                return { ...node, children: node.children.map((child) => shift(child)) };
-        }
-    };
-    return renderNodeContent(shift(ast)).trimEnd();
-}
 export function parseMarkdownListSection(text) {
     const ast = parseToAST(text, { allowSections: false });
     const pseudoSection = {

package/build/utils/keiyaku-document.test.js

@@ -1,7 +1,8 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { FlowError } from "../common/errors.js";
-import { extractListItems, parseToAST, parseMarkdownStructure, parseMarkdownListSection, demoteMarkdownHeadings, renderSectionContent, renderMarkdownSections, validateMarkdownHeaders, } from "./keiyaku-document.js";
+import { extractListItems, parseToAST, parseMarkdownStructure, parseMarkdownListSection, renderSectionContent, validateMarkdownHeaders, } from "./keiyaku-document.js";
+import { computeHeadingDelta, demoteMarkdownHeadings, renderMarkdownSections, } from "../workflow/markdown-normalization.js";
 test("parseToAST models H1/H2 sections and keeps H3+ headers as heading nodes", () => {
     const markdown = [
         "# Feature Alpha",
@@ -35,7 +36,7 @@ test("parseToAST models H1/H2 sections and keeps H3+ headers as heading nodes",
     assert.equal(goalList.items[0]?.children[1]?.type === "heading" ? `### ${goalList.items[0].children[1].text}` : "", "### Keep this as content");
 });
 test("renderSectionContent and extractListItems keep H3+ content inside list items", () => {
-    const ast = parseToAST(["## Constraints", "- Keep parser", "  ### preserve heading", "- Keep tests"].join("\n"));
+    const ast = parseToAST(["## Rules", "- Keep parser", "  ### preserve heading", "- Keep tests"].join("\n"));
     const section = ast.children[0];
     assert.equal(section?.type, "section");
     if (section?.type !== "section")
@@ -114,6 +115,11 @@ test("parseMarkdownListSection handles empty lines between list items", () => {
 test("renderMarkdownSections renders plain markdown bullets", () => {
     assert.equal(renderMarkdownSections(["Constraint A", "Constraint B"]), "- Constraint A\n\n- Constraint B");
 });
+test("computeHeadingDelta returns shift only when needed", () => {
+    assert.equal(computeHeadingDelta(null, 3), 0);
+    assert.equal(computeHeadingDelta(3, 3), 0);
+    assert.equal(computeHeadingDelta(1, 3), 2);
+});
 test("demoteMarkdownHeadings shifts headings to keep minimum level at h3 while preserving relative hierarchy", () => {
     assert.equal(demoteMarkdownHeadings("# Title\n## Sub\n### Already", 3), "### Title\n#### Sub\n##### Already");
     assert.equal(demoteMarkdownHeadings(["```md", "## Not a section", "```", "## Real heading"].join("\n"), 3), ["```md", "## Not a section", "```", "### Real heading"].join("\n"));

package/build/workflow/ask.js

@@ -5,9 +5,9 @@ import { runSubagent } from "../agents/round-runner.js";
 import * as git from "../utils/git.js";
 import { buildAskPrompt } from "./prompts.js";
 import { FlowError } from "../common/errors.js";
-import { renderMarkdownSections } from "../utils/keiyaku-document.js";
+import { renderMarkdownSections } from "./markdown-normalization.js";
 import { flattenMarkdownList } from "../utils/text-utils.js";
-const BASE_CONSTRAINTS_FILE = path.join(".keiyaku", "base-constraints.md");
+const BASE_RULES_FILE = path.join(".keiyaku", "base-rules.md");
 function requireText(name, value) {
     const normalized = value.trim();
     if (!normalized) {
@@ -19,12 +19,12 @@ export async function askServant(input) {
     const { cwd, signal, name } = input;
     const request = requireText("request", input.request);
     const context = requireText("context", input.context);
-    let referenceConstraints;
+    let referenceRules;
     try {
-        const baseConstraintsRaw = await fs.readFile(path.join(cwd, BASE_CONSTRAINTS_FILE), "utf-8");
-        const baseConstraints = flattenMarkdownList(baseConstraintsRaw);
-        if (baseConstraints.length > 0) {
-            referenceConstraints = renderMarkdownSections(baseConstraints);
+        const baseRulesRaw = await fs.readFile(path.join(cwd, BASE_RULES_FILE), "utf-8");
+        const baseRules = flattenMarkdownList(baseRulesRaw);
+        if (baseRules.length > 0) {
+            referenceRules = renderMarkdownSections(baseRules);
         }
     }
     catch (error) {
@@ -32,7 +32,7 @@ export async function askServant(input) {
             throw error;
         }
     }
-    const prompt = buildAskPrompt(request, context, referenceConstraints);
+    const prompt = buildAskPrompt(request, context, referenceRules);
     // TODO: enforce read-only access and persist summary to .keiyaku/notes/.
     const summary = await runSubagent(selectSubagent(name), prompt, cwd, 0, signal);
     let currentBranch;

package/build/workflow/drive.js

@@ -54,7 +54,7 @@ export async function driveServant(input) {
     const traceState = computeTraceState(traceContent);
     const title = keiyakuBranch.slice("keiyaku/".length);
     const goal = readGoalFromKeiyaku(parsedKeiyaku);
-    const constraints = readKeiyakuSection(parsedKeiyaku, "Constraints");
+    const rules = readKeiyakuSection(parsedKeiyaku, "Rules");
     const criteria = readKeiyakuSection(parsedKeiyaku, "Acceptance Criteria");
     const normalizedDirective = requireText("directive", directive);
     try {
@@ -82,7 +82,7 @@ export async function driveServant(input) {
             diff,
             summary,
             goal,
-            constraints,
+            rules,
             criteria,
             currentBranch: keiyakuBranch,
             baseBranch,

package/build/workflow/keiyaku-document-builder.js

@@ -1,14 +1,14 @@
-import { demoteMarkdownHeadings, renderMarkdownSections } from "../utils/keiyaku-document.js";
-const BASE_CONSTRAINTS_SOURCE = ".keiyaku/base-constraints.md";
-export function renderKeiyaku(title, goal, context, baseConstraints, taskConstraints, taskCriteria) {
+import { demoteMarkdownHeadings, renderMarkdownSections } from "./markdown-normalization.js";
+const BASE_RULES_SOURCE = ".keiyaku/base-rules.md";
+export function renderKeiyaku(title, goal, context, baseRules, taskRules, taskCriteria) {
     const normalizedContext = demoteMarkdownHeadings(context, 3);
     const normalizedGoal = demoteMarkdownHeadings(goal, 3);
     let content = `# ${title}\n\n## Context\n${normalizedContext}\n\n## Goal\n${normalizedGoal}`;
-    content += "\n\n## Constraints";
-    if (baseConstraints.length > 0) {
-        content += `\n\n### Project Constraints\nLoaded from: \`${BASE_CONSTRAINTS_SOURCE}\`\n\n${renderMarkdownSections(baseConstraints)}`;
+    content += "\n\n## Rules";
+    if (baseRules.length > 0) {
+        content += `\n\n### Project Rules\nLoaded from: \`${BASE_RULES_SOURCE}\`\n\n${renderMarkdownSections(baseRules)}`;
     }
-    content += `\n\n### Task Constraints\n${renderMarkdownSections(taskConstraints)}`;
+    content += `\n\n### Task Rules\n${renderMarkdownSections(taskRules)}`;
     content += "\n\n## Acceptance Criteria";
     content += `\n\n### Task Criteria\n${renderMarkdownSections(taskCriteria)}`;
     return content;

package/build/workflow/keiyaku-draft.js

@@ -1,10 +1,11 @@
 import { FlowError } from "../common/errors.js";
 import { extractListItems, parseToAST, renderSectionContent, } from "../utils/keiyaku-document.js";
+import { computeHeadingDelta } from "./markdown-normalization.js";
 const KNOWN_DRAFT_SECTIONS = new Set([
     "goal",
     "directive",
     "context",
-    "constraints",
+    "rules",
     "criteria",
     "acceptance criteria",
 ]);
@@ -131,10 +132,10 @@ function normalizeDraftHeadings(content) {
         }
         shallowestNonStructural = shallowestNonStructural === null ? level : Math.min(shallowestNonStructural, level);
     }
-    if (shallowestNonStructural === null || shallowestNonStructural >= MIN_HEADING_LEVEL) {
+    const delta = computeHeadingDelta(shallowestNonStructural, MIN_HEADING_LEVEL);
+    if (delta === 0) {
         return lines.join("\n");
     }
-    const delta = MIN_HEADING_LEVEL - shallowestNonStructural;
     const out = [];
     sawTitleH1 = false;
     fence = null;
@@ -238,7 +239,7 @@ export function parseAndValidateKeiyakuDraft(content) {
     const goal = sections.get("goal")?.trim();
     const directive = sections.get("directive")?.trim();
     const context = sections.get("context")?.trim();
-    const constraints = sections.has("constraints") ? collectSectionItems(ast, "constraints") : undefined;
+    const rules = sections.has("rules") ? collectSectionItems(ast, "rules") : undefined;
     const criteria = sections.has("acceptance criteria")
         ? collectSectionItems(ast, "acceptance criteria")
         : sections.has("criteria")
@@ -249,7 +250,7 @@ export function parseAndValidateKeiyakuDraft(content) {
         goal: goal || undefined,
         directive: directive || undefined,
         context: context || undefined,
-        constraints: constraints && constraints.length > 0 ? constraints : undefined,
+        rules: rules && rules.length > 0 ? rules : undefined,
         criteria: criteria && criteria.length > 0 ? criteria : undefined,
     };
 }