@hivehub/rulebook 5.2.0 → 5.3.0

package/dist/core/rules-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-generator.d.ts","sourceRoot":"","sources":["../../src/core/rules-generator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,SAAS,kBAAkB,CAAC;AACzC,eAAO,MAAM,kBAAkB,0CAA0C,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,wBAAwB,wFAS3B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,eAAe,8IAMlB,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAkB9E,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAExF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAMlF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMvF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAC5C,OAAO,CAAC,qBAAqB,CAAC,CA2DhC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACxB;AAED,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAuBpF"}

package/dist/core/rules-generator.js

@@ -0,0 +1,201 @@
+import path from 'path';
+import { readFile, writeFile, fileExists, ensureDir } from '../utils/file-system.js';
+import { getTemplatesDir } from './generator.js';
+/**
+ * v5.3.0 `.claude/rules/` generator.
+ *
+ * For every detected language that rulebook ships a template for, emit
+ * `.claude/rules/<language>.md` with YAML `paths:` frontmatter. These are
+ * Anthropic's path-scoped rules (loaded only when Claude reads a file
+ * matching the glob), so they cost zero context budget outside of the
+ * relevant file types.
+ *
+ * Files generated by rulebook carry a sentinel comment immediately after
+ * the frontmatter. On `rulebook update`, any `.claude/rules/*.md` without
+ * the sentinel is treated as user-authored and left alone. This lets users
+ * adopt a generated rule file as their own by simply deleting the sentinel
+ * comment line.
+ */
+export const RULES_DIR = '.claude/rules';
+export const GENERATED_SENTINEL = 'Generated by @hivehub/rulebook v5.3.0';
+/**
+ * Languages with shipped rule templates. Adding a new entry here requires a
+ * matching `templates/rules/<slug>.md` file.
+ */
+export const SUPPORTED_RULE_LANGUAGES = [
+    'typescript',
+    'javascript',
+    'rust',
+    'python',
+    'go',
+    'cpp',
+    'java',
+    'csharp',
+];
+/**
+ * Generic (non-language) rules shipped by rulebook v5.3.0.
+ * These are always emitted regardless of detection result.
+ */
+export const ALWAYS_ON_RULES = [
+    'multi-agent-teams',
+    'consult-analysis-before-implementing',
+    'respect-handoff-trigger',
+    'diagnostic-first',
+    'fail-twice-escalate',
+];
+/**
+ * Detected languages from the `detector.ts` pipeline may use aliases
+ * (e.g. `"c"` — which rulebook treats as C/C++ and routes to the `cpp`
+ * template). Map them here.
+ */
+const LANGUAGE_ALIASES = {
+    c: 'cpp',
+    'c++': 'cpp',
+    cs: 'csharp',
+    'c#': 'csharp',
+    ts: 'typescript',
+    js: 'javascript',
+    py: 'python',
+    rs: 'rust',
+};
+export function getRulesDir(projectRoot) {
+    return path.join(projectRoot, RULES_DIR);
+}
+export function getRulePath(projectRoot, language) {
+    return path.join(getRulesDir(projectRoot), `${language}.md`);
+}
+/**
+ * Normalize a detected language string to a supported rule template slug.
+ * Returns null if rulebook does not ship a template for it.
+ */
+export function resolveRuleLanguage(detected) {
+    const lower = detected.toLowerCase().trim();
+    if (SUPPORTED_RULE_LANGUAGES.includes(lower)) {
+        return lower;
+    }
+    return LANGUAGE_ALIASES[lower] ?? null;
+}
+/**
+ * Read a language rule template from the package's `templates/rules/`
+ * directory.
+ */
+export async function readRuleTemplate(language) {
+    const templatePath = path.join(getTemplatesDir(), 'rules', `${language}.md`);
+    if (!(await fileExists(templatePath))) {
+        throw new Error(`Rule template not found at ${templatePath}`);
+    }
+    return await readFile(templatePath);
+}
+/**
+ * Check whether an existing rule file was generated by rulebook. Returns
+ * true only if the canonical sentinel comment is present. User files that
+ * the user "adopted" by deleting the sentinel return false and are
+ * preserved across updates.
+ */
+export function hasGeneratedSentinel(content) {
+    return content.includes(GENERATED_SENTINEL);
+}
+/**
+ * Generate `.claude/rules/<language>.md` for every detected language that
+ * has a shipped template. User-authored rules (no sentinel) are preserved.
+ */
+export async function generateRules(projectRoot, detection) {
+    const rulesDir = getRulesDir(projectRoot);
+    await ensureDir(rulesDir);
+    const result = {
+        written: [],
+        preserved: [],
+        unsupported: [],
+    };
+    // Deduplicate: a project might detect both "typescript" and "javascript";
+    // we emit both rules since both apply. But if two detection entries map
+    // to the same template slug, only write once.
+    const seen = new Set();
+    for (const entry of detection.languages) {
+        const slug = resolveRuleLanguage(entry.language);
+        if (!slug) {
+            result.unsupported.push(entry.language);
+            continue;
+        }
+        if (seen.has(slug))
+            continue;
+        seen.add(slug);
+        const targetPath = getRulePath(projectRoot, slug);
+        if (await fileExists(targetPath)) {
+            const existing = await readFile(targetPath);
+            if (!hasGeneratedSentinel(existing)) {
+                // User-owned file — never touch it.
+                result.preserved.push(targetPath);
+                continue;
+            }
+        }
+        const template = await readRuleTemplate(slug);
+        await writeFile(targetPath, template);
+        result.written.push(targetPath);
+    }
+    // Always-on rules (not language-scoped) — emit if sentinel-based skip allows
+    for (const ruleName of ALWAYS_ON_RULES) {
+        const targetPath = path.join(rulesDir, `${ruleName}.md`);
+        if (await fileExists(targetPath)) {
+            const existing = await readFile(targetPath);
+            if (!hasGeneratedSentinel(existing)) {
+                result.preserved.push(targetPath);
+                continue;
+            }
+        }
+        const templatePath = path.join(getTemplatesDir(), 'rules', `${ruleName}.md`);
+        if (await fileExists(templatePath)) {
+            const template = await readFile(templatePath);
+            await writeFile(targetPath, template);
+            result.written.push(targetPath);
+        }
+    }
+    return result;
+}
+export async function listRulesWithSource(projectRoot) {
+    const rulesDir = getRulesDir(projectRoot);
+    if (!(await fileExists(rulesDir)))
+        return [];
+    const { promises: fs } = await import('fs');
+    const entries = await fs.readdir(rulesDir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const filePath = path.join(rulesDir, entry.name);
+        const content = await readFile(filePath);
+        const source = hasGeneratedSentinel(content) ? 'generated' : 'user';
+        results.push({
+            name: entry.name.replace(/\.md$/, ''),
+            path: filePath,
+            source,
+            paths: extractPathsFrontmatter(content),
+        });
+    }
+    results.sort((a, b) => a.name.localeCompare(b.name));
+    return results;
+}
+/**
+ * Extract the `paths:` field from a YAML frontmatter block at the top of a
+ * markdown file. Returns null if no frontmatter or no `paths:` field.
+ * Intentionally simple — handles the exact shape the shipped templates use,
+ * not arbitrary YAML. Callers that need full YAML support should use a real
+ * parser.
+ */
+function extractPathsFrontmatter(content) {
+    // Handle both LF and CRLF line endings (Windows writes CRLF)
+    const normalized = content.replace(/\r\n/g, '\n');
+    const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return null;
+    const frontmatter = match[1];
+    const pathsMatch = frontmatter.match(/^paths:\s*\n((?:\s*-\s+.+\n?)+)/m);
+    if (!pathsMatch)
+        return null;
+    const lines = pathsMatch[1].split('\n').filter((l) => l.trim().startsWith('-'));
+    return lines.map((l) => l
+        .replace(/^\s*-\s+/, '')
+        .replace(/^["']|["']$/g, '')
+        .trim());
+}
+//# sourceMappingURL=rules-generator.js.map

package/dist/core/rules-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-generator.js","sourceRoot":"","sources":["../../src/core/rules-generator.ts"],"names":[],"mappings":"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"}

package/dist/core/state-writer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v5.3.0 F3 — `.rulebook/STATE.md` auto-regeneration.
+ *
+ * Renders a short (<40 line) machine-written status file imported by
+ * CLAUDE.md via `@.rulebook/STATE.md`. Updated on every task state
+ * change or Ralph iteration. Users can opt out by adding a
+ * `manual: true` YAML frontmatter flag.
+ */
+export declare const STATE_FILE = ".rulebook/STATE.md";
+export interface StateSnapshot {
+    activeTask?: {
+        id: string;
+        phase: string;
+        progress: string;
+    } | null;
+    lastRalphIteration?: number | null;
+    lastQualityGate?: string | null;
+    healthScore?: number | null;
+    updatedAt: string;
+}
+export declare function getStatePath(projectRoot: string): string;
+/**
+ * Check whether the STATE.md has `manual: true` frontmatter, meaning
+ * the user maintains it by hand and rulebook should not touch it.
+ */
+export declare function isManuallyMaintained(projectRoot: string): Promise<boolean>;
+/**
+ * Write or overwrite `.rulebook/STATE.md` with the given snapshot.
+ * No-op if the file has `manual: true` frontmatter.
+ */
+export declare function writeState(projectRoot: string, snapshot: StateSnapshot): Promise<{
+    path: string;
+    written: boolean;
+}>;
+//# sourceMappingURL=state-writer.d.ts.map

package/dist/core/state-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-writer.d.ts","sourceRoot":"","sources":["../../src/core/state-writer.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,eAAO,MAAM,UAAU,uBAAuB,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACpE,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKhF;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAU7C"}

package/dist/core/state-writer.js

@@ -0,0 +1,81 @@
+import path from 'path';
+import { writeFile, fileExists, readFile, ensureDir } from '../utils/file-system.js';
+/**
+ * v5.3.0 F3 — `.rulebook/STATE.md` auto-regeneration.
+ *
+ * Renders a short (<40 line) machine-written status file imported by
+ * CLAUDE.md via `@.rulebook/STATE.md`. Updated on every task state
+ * change or Ralph iteration. Users can opt out by adding a
+ * `manual: true` YAML frontmatter flag.
+ */
+export const STATE_FILE = '.rulebook/STATE.md';
+export function getStatePath(projectRoot) {
+    return path.join(projectRoot, STATE_FILE);
+}
+/**
+ * Check whether the STATE.md has `manual: true` frontmatter, meaning
+ * the user maintains it by hand and rulebook should not touch it.
+ */
+export async function isManuallyMaintained(projectRoot) {
+    const target = getStatePath(projectRoot);
+    if (!(await fileExists(target)))
+        return false;
+    const content = await readFile(target);
+    return /^---\n[\s\S]*?manual:\s*true/m.test(content);
+}
+/**
+ * Write or overwrite `.rulebook/STATE.md` with the given snapshot.
+ * No-op if the file has `manual: true` frontmatter.
+ */
+export async function writeState(projectRoot, snapshot) {
+    if (await isManuallyMaintained(projectRoot)) {
+        return { path: getStatePath(projectRoot), written: false };
+    }
+    const target = getStatePath(projectRoot);
+    await ensureDir(path.dirname(target));
+    const content = renderState(snapshot);
+    await writeFile(target, content);
+    return { path: target, written: true };
+}
+function renderState(s) {
+    const lines = [
+        '<!-- Auto-generated by rulebook v5.3.0. Do not edit — changes will be overwritten. -->',
+        '<!-- Add `manual: true` frontmatter to opt out of auto-generation. -->',
+        '',
+        '# Project state',
+        '',
+        `**Last updated**: ${s.updatedAt}`,
+        '',
+    ];
+    if (s.activeTask) {
+        lines.push(`## Active task`);
+        lines.push('');
+        lines.push(`- **ID**: \`${s.activeTask.id}\``);
+        lines.push(`- **Phase**: ${s.activeTask.phase}`);
+        lines.push(`- **Progress**: ${s.activeTask.progress}`);
+        lines.push('');
+    }
+    else {
+        lines.push('## Active task');
+        lines.push('');
+        lines.push('No active task.');
+        lines.push('');
+    }
+    if (s.lastRalphIteration != null) {
+        lines.push(`## Ralph`);
+        lines.push('');
+        lines.push(`- **Last iteration**: ${s.lastRalphIteration}`);
+        if (s.lastQualityGate) {
+            lines.push(`- **Quality gate**: ${s.lastQualityGate}`);
+        }
+        lines.push('');
+    }
+    if (s.healthScore != null) {
+        lines.push(`## Health`);
+        lines.push('');
+        lines.push(`- **Score**: ${s.healthScore}/100`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=state-writer.js.map

package/dist/core/state-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-writer.js","sourceRoot":"","sources":["../../src/core/state-writer.ts"],"names":[],"mappings":"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"}

package/dist/core/task-manager.d.ts

@@ -15,6 +15,37 @@ export interface TaskValidationResult {
     errors: string[];
     warnings: string[];
 }
+/**
+ * v5.3.0 F-NEW-3 — mandatory task tail.
+ *
+ * Every task MUST end with these three items. `createTask()` appends them
+ * automatically; `validateTask()` refuses any task that does not have them
+ * all checked; `archiveTask()` propagates that refusal.
+ *
+ * Idempotent: `renderMandatoryTail` is deterministic and `checkMandatoryTail`
+ * is case-insensitive on the leading verb so a user who rewords the items
+ * slightly (e.g. "Update docs covering the change") is still recognized.
+ */
+export declare const MANDATORY_TAIL_ITEMS: readonly [{
+    readonly label: "Update or create documentation covering the implementation";
+    readonly match: RegExp;
+}, {
+    readonly label: "Write tests covering the new behavior";
+    readonly match: RegExp;
+}, {
+    readonly label: "Run tests and confirm they pass";
+    readonly match: RegExp;
+}];
+export declare function renderMandatoryTail(sectionNumber: number): string;
+export interface TailCheckResult {
+    /** True when all three tail items are present in the file. */
+    present: boolean;
+    /** Labels of items that are entirely missing from the file. */
+    missing: string[];
+    /** Labels of items that are present but unchecked (`- [ ]`). */
+    unchecked: string[];
+}
+export declare function checkMandatoryTail(tasksContent: string): TailCheckResult;
 export declare class TaskManager {
     private rulebookPath;
     private tasksPath;
@@ -75,6 +106,10 @@ export declare class TaskManager {
      * Update task status
      */
     updateTaskStatus(taskId: string, status: RulebookTask['status']): Promise<void>;
+    /**
+     * v5.3.0 F3: refresh .rulebook/STATE.md after task state changes.
+     */
+    private refreshState;
     /**
      * Get raw task metadata (including blocks/blockedBy/cascadeImpact for v5 blocker tracking)
      */

package/dist/core/task-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-manager.d.ts","sourceRoot":"","sources":["../../src/core/task-manager.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM,EAAE,WAAW,GAAE,MAAoB;IAMlE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAInC;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAUlE;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAMlE;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgE/C;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAkEnC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAkCxC;;OAEG;IACG,SAAS,CAAC,eAAe,GAAE,OAAe,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAyC1E;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAsFvF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkEjE;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCjF;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBrF;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAW9E;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAiB5D;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAchD;AAED,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,MAAoB,GAChC,WAAW,CAEb"}
+{"version":3,"file":"task-manager.d.ts","sourceRoot":"","sources":["../../src/core/task-manager.ts"],"names":[],"mappings":"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"}

package/dist/core/task-manager.js

@@ -12,6 +12,58 @@ const README_FILE = 'README.md';
  * Examples: phase0_3.1.0-volumetric-clouds, phase3a_3.24.0-lens-flare
  */
 const PHASE_PREFIX_REGEX = /^phase\d+[a-z]?_/;
+/**
+ * v5.3.0 F-NEW-3 — mandatory task tail.
+ *
+ * Every task MUST end with these three items. `createTask()` appends them
+ * automatically; `validateTask()` refuses any task that does not have them
+ * all checked; `archiveTask()` propagates that refusal.
+ *
+ * Idempotent: `renderMandatoryTail` is deterministic and `checkMandatoryTail`
+ * is case-insensitive on the leading verb so a user who rewords the items
+ * slightly (e.g. "Update docs covering the change") is still recognized.
+ */
+export const MANDATORY_TAIL_ITEMS = [
+    {
+        label: 'Update or create documentation covering the implementation',
+        match: /^\s*-\s*\[[ x]\]\s.*(update|create).*documentation/i,
+    },
+    { label: 'Write tests covering the new behavior', match: /^\s*-\s*\[[ x]\]\s.*write.*tests?/i },
+    {
+        label: 'Run tests and confirm they pass',
+        match: /^\s*-\s*\[[ x]\]\s.*run.*tests?.*(pass|confirm)/i,
+    },
+];
+export function renderMandatoryTail(sectionNumber) {
+    return [
+        `## ${sectionNumber}. Tail (mandatory — enforced by rulebook v5.3.0)`,
+        `- [ ] ${sectionNumber}.1 Update or create documentation covering the implementation`,
+        `- [ ] ${sectionNumber}.2 Write tests covering the new behavior`,
+        `- [ ] ${sectionNumber}.3 Run tests and confirm they pass`,
+        '',
+    ].join('\n');
+}
+export function checkMandatoryTail(tasksContent) {
+    const lines = tasksContent.split('\n');
+    const missing = [];
+    const unchecked = [];
+    for (const item of MANDATORY_TAIL_ITEMS) {
+        const matched = lines.find((line) => item.match.test(line));
+        if (!matched) {
+            missing.push(item.label);
+            continue;
+        }
+        // Checked if the line contains `[x]` or `[X]`; unchecked otherwise.
+        if (!/\[x\]/i.test(matched)) {
+            unchecked.push(item.label);
+        }
+    }
+    return {
+        present: missing.length === 0,
+        missing,
+        unchecked,
+    };
+}
 export class TaskManager {
     rulebookPath;
     tasksPath;
@@ -34,6 +86,8 @@ export class TaskManager {
         if (!existsSync(this.archivePath)) {
             mkdirSync(this.archivePath, { recursive: true });
         }
+        // Auto-migrate legacy archive from tasks/archive to .rulebook/archive
+        await this.migrateArchive();
     }
     /**
      * Get the path to a task directory
@@ -79,34 +133,30 @@ export class TaskManager {
         mkdirSync(taskPath, { recursive: true });
         mkdirSync(join(taskPath, SPECS_DIR), { recursive: true });
         // Create proposal.md template
-        const proposalContent = `# Proposal: ${taskId}
-
-## Why
-[Explain why this change is needed - minimum 20 characters]
-
-## What Changes
-[Describe what will change]
-
-## Impact
-- Affected specs: [list]
-- Affected code: [list]
-- Breaking change: YES/NO
-- User benefit: [describe]
+        const proposalContent = `# Proposal: ${taskId}
+
+## Why
+[Explain why this change is needed - minimum 20 characters]
+
+## What Changes
+[Describe what will change]
+
+## Impact
+- Affected specs: [list]
+- Affected code: [list]
+- Breaking change: YES/NO
+- User benefit: [describe]
 `;
         await writeFileAsync(join(taskPath, 'proposal.md'), proposalContent);
-        // Create tasks.md template
-        const tasksContent = `## 1. Implementation
-- [ ] 1.1 First task
-- [ ] 1.2 Second task
-
-## 2. Testing
-- [ ] 2.1 Write tests
-- [ ] 2.2 Verify coverage
-
-## 3. Documentation
-- [ ] 3.1 Update README
-- [ ] 3.2 Update CHANGELOG
-`;
+        // Create tasks.md template — the MANDATORY tail items (v5.3.0 F-NEW-3)
+        // are appended automatically here AND enforced by validateTask() /
+        // archiveTask(): a task cannot be closed unless docs are updated,
+        // tests are written, and tests pass.
+        const tasksContent = `## 1. Implementation
+- [ ] 1.1 First task
+- [ ] 1.2 Second task
+
+${renderMandatoryTail(2)}`;
         await writeFileAsync(join(taskPath, 'tasks.md'), tasksContent);
         // Create .metadata.json with initial status
         const now = new Date().toISOString();
@@ -116,8 +166,9 @@ export class TaskManager {
             updatedAt: now,
         };
         await writeFileAsync(join(taskPath, '.metadata.json'), JSON.stringify(metadata, null, 2));
-        // Update tasks README index
+        // Update tasks README index + STATE.md
         await this.updateReadme();
+        await this.refreshState();
     }
     /**
      * Generate and update README.md index in the tasks root directory.
@@ -154,17 +205,21 @@ export class TaskManager {
         };
         const statusIcon = (status) => {
             switch (status) {
-                case 'completed': return '✅';
-                case 'in-progress': return '🔄';
-                case 'blocked': return '🚫';
-                default: return '⬚';
+                case 'completed':
+                    return '✅';
+                case 'in-progress':
+                    return '🔄';
+                case 'blocked':
+                    return '🚫';
+                default:
+                    return '⬚';
             }
         };
         let readme = `# Tasks Index\n\n`;
         readme += `> Auto-generated by rulebook. Do not edit manually.\n\n`;
         const totalTasks = tasks.length;
-        const completedTasks = tasks.filter(t => t.status === 'completed').length;
-        const inProgressTasks = tasks.filter(t => t.status === 'in-progress').length;
+        const completedTasks = tasks.filter((t) => t.status === 'completed').length;
+        const inProgressTasks = tasks.filter((t) => t.status === 'in-progress').length;
         readme += `**Total**: ${totalTasks} tasks | **Completed**: ${completedTasks} | **In Progress**: ${inProgressTasks} | **Pending**: ${totalTasks - completedTasks - inProgressTasks}\n\n`;
         for (const [phaseKey, phaseTasks] of phases) {
             readme += `## ${phaseKey}\n\n`;
@@ -172,9 +227,7 @@ export class TaskManager {
             readme += `|--------|------|----------|-------------|\n`;
             for (const task of phaseTasks) {
                 const progress = getProgress(task);
-                const progressStr = progress.total > 0
-                    ? `${progress.done}/${progress.total}`
-                    : '-';
+                const progressStr = progress.total > 0 ? `${progress.done}/${progress.total}` : '-';
                 // Extract short description from task ID (after phase prefix)
                 const desc = task.id.replace(/^phase\d+[a-z]?_/, '').replace(/-/g, ' ');
                 readme += `| ${statusIcon(task.status)} | ${task.id} | ${progressStr} | ${desc} |\n`;
@@ -362,6 +415,16 @@ export class TaskManager {
                 errors.push('Purpose section (## Why) must have at least 20 characters');
             }
         }
+        // v5.3.0 F-NEW-3: mandatory task tail (docs + tests + verify)
+        const tail = task.tasks
+            ? checkMandatoryTail(task.tasks)
+            : { present: false, missing: MANDATORY_TAIL_ITEMS.map((i) => i.label), unchecked: [] };
+        if (!tail.present) {
+            errors.push(`Mandatory task tail missing from tasks.md (required in v5.3.0): ${tail.missing.join(', ')}`);
+        }
+        else if (tail.unchecked.length > 0) {
+            errors.push(`Mandatory task tail items are still unchecked: ${tail.unchecked.join(', ')}`);
+        }
         // Validate specs
         if (!task.specs || Object.keys(task.specs).length === 0) {
             warnings.push('No spec files found (specs/*/spec.md)');
@@ -430,8 +493,9 @@ export class TaskManager {
         // Move task to archive using cross-platform filesystem operations
         const { renameSync } = await import('fs');
         renameSync(taskPath, archiveTaskPath);
-        // Update tasks README index
+        // Update tasks README index + STATE.md
         await this.updateReadme();
+        await this.refreshState();
     }
     /**
      * Update task status
@@ -452,8 +516,43 @@ export class TaskManager {
             updatedAt: task.updatedAt,
         };
         await writeFileUtil(metadataPath, JSON.stringify(metadata, null, 2));
-        // Update tasks README index
+        // Update tasks README index + STATE.md
         await this.updateReadme();
+        await this.refreshState();
+    }
+    /**
+     * v5.3.0 F3: refresh .rulebook/STATE.md after task state changes.
+     */
+    async refreshState() {
+        try {
+            const { writeState } = await import('./state-writer.js');
+            const tasks = await this.listTasks(false);
+            const active = tasks.find((t) => t.status === 'in-progress') ??
+                tasks.find((t) => t.status === 'pending') ??
+                null;
+            const totalItems = tasks.reduce((n, t) => {
+                const m = t.tasks?.match(/- \[x\]/gi);
+                const u = t.tasks?.match(/- \[ \]/g);
+                return n + (m?.length ?? 0) + (u?.length ?? 0);
+            }, 0);
+            const checkedItems = tasks.reduce((n, t) => {
+                const m = t.tasks?.match(/- \[x\]/gi);
+                return n + (m?.length ?? 0);
+            }, 0);
+            await writeState(join(this.rulebookPath, '..'), {
+                activeTask: active
+                    ? {
+                        id: active.id,
+                        phase: active.id.match(/^(phase\d+[a-z]?)_/)?.[1] ?? '?',
+                        progress: `${checkedItems}/${totalItems} items`,
+                    }
+                    : null,
+                updatedAt: new Date().toISOString(),
+            });
+        }
+        catch {
+            // Non-fatal — STATE.md refresh must never break task operations
+        }
     }
     /**
      * Get raw task metadata (including blocks/blockedBy/cascadeImpact for v5 blocker tracking)