@njeybe/nativ 2.0.2 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2.2.0
+
+### Added
+
+- **Dual-Track Intake (Experience-First vs Data-First).** The `ui_specs.md` template can now start from either user experience (sketches and flows) or data structure (tables and entity relationships). Both paths lead to the same component map and style tile.
+- **Semantic Component Trees.** Components now organize into a hierarchical structure with semantic roles: layout containers, data display, input controls, feedback, and navigation. The component map in `ui_specs.md` reflects these roles.
+- **Stack-Aware Style Tiles.** Style tiles now include platform-specific variants. A web style tile shows how a design token adapts across desktop, tablet and mobile breakpoints. Flutter tiles show platform-native adaptations for iOS, Android and Cupertino.
+- **Contextual Typography.** The `ui_specs.md` template documents font scales in context: scale per platform, role (heading, body, caption, code), and how type tokens map to semantic roles in components. Font sizes, weights and line heights are specified per context, not globally.
+- **Mutation State Specs.** Every input component, button, and interactive element now carries a spec for its mutation states: default, hover, focus, disabled, loading, error and success. States are shown in the wireframe notes and in the component section.
+
+## 2.1.0
+
+### Added
+
+- **Design-first planning.** The `ui_specs.md` template is rewritten around planning levels (Quick, Standard, Full), content samples, user flows, wireframes, a component map and a style tile. The architect, frontend and flutter guides are leaner.
+- **Optional task fields** `specRefs`, `complexity` and `acceptanceCriteria`: `nativ task add --spec-refs --complexity --accept`, and the same fields on the `nativ_task_add` MCP tool.
+- **Spec slices.** `nativ task next --json` returns `specSlices` and `specWarnings` for a task's `specRefs`, the native run engine adds a `<spec_slices>` block to the worker prompt, and `nativ validate` warns about refs that do not resolve.
+- **Complexity-based model routing.** `nativ task next --json` returns `recommendedModel` (simple: haiku, standard: sonnet, complex: opus). Override it with `workerModels` in `.nativ/config.json`. The run engine uses it when no model is given, and the project manager passes it as the Agent `model` parameter. Works with a Claude Pro login; no API key.
+- **Code style rules** for workers in `AGENTS.md`, and a code-shape check in `nativ verify` for long lines and long comments. It warns by default; configure it with `codeStyle` in `.nativ/config.json`. The `nativ task complete` gatekeeper runs it too, warn-only.
+- **API spec links.** `specRefs` can point at an endpoint by method and path (`api_contracts.json#GET /path`) or by endpoint id (`api_contracts.json#<endpoint-id>`).
+- **Design Brief step** in the Architect procedure. It records the primary platform and comes before the design directions.
+
+### Changed
+
+- **`nativ_task_complete` over MCP refuses `skipVerify`.** Only a human at a terminal can skip verification.
+
 ## 2.0.2
 
 - **`nativ doctor` no longer reports a failure on a brand-new project.** Right after `nativ init`, Claude Code lists the project's `nativ` MCP server as "Pending approval" until you approve it, which is the expected first state. Doctor showed it as a red failure and exited 1. It is now a warning that tells you to open `claude` in the folder and approve the server; a server that genuinely fails to connect is still a failure.
@@ -8,7 +34,7 @@
 
 Documentation and package metadata only; no behaviour changes.
 
-- **npm is the only install path.** The source repository is private, so the instructions for `npm install -g github:…` and for adding the plugin marketplace were removed from the README and the installation guide. `nativ setup` is the complete route: it writes the agents, the enforcement hook, the MCP entry and the permission rules, which a plugin cannot ship.
+- **npm is the only install path.** The source repository is private, so the instructions for `npm install -g github:…` and for adding the plugin marketplace were removed from the README and the installation guide. `nativ setup` is the complete route: it writes the agents, the enforcement hook, the MCP entry and the permission rules, which a plugin cannot ship.
 - The plugin files still ship inside the package (`plugin/`) and can be tried for one session with `claude --plugin-dir`.
 - `package.json` no longer declares `repository`, `homepage` or `bugs`, so the npm page has no dead links.
 - The 2.0.0 entry below still mentions the plugin marketplace; that route is not available outside the private repository.

package/README.md

@@ -125,6 +125,34 @@ Start in `warn`, look at the log, then switch to `block`. If a task genuinely ne
 
 ---
 
+## Design-first planning, task fields and model routing
+
+**Planning levels.** The `.ai/ui_specs.md` template opens with a planning level: Quick (small fix, no design phase), Standard (new screen in an existing design) or Full (new app or redesign). It then walks through the design brief, users and top tasks, real content samples, user flows, design directions with a style tile, wireframes, a component map and one section per component. The architect and frontend/flutter guides were trimmed to match.
+
+**UI/UX design enhancements.** The template supports two intake approaches: Experience-First (start with user flows and wireframes) or Data-First (start with entity relationships and table schemas), both leading to the same component map. The component map now organizes components into semantic trees reflecting their roles in the interface (layout, data display, input, feedback, navigation). Style tiles are stack-aware, showing platform-specific token variants for web breakpoints and Flutter platform adaptations. Typography is specified in context with font scales per platform and semantic role, mapped directly to components. Every interactive element and input carries a mutation state spec: default, hover, focus, disabled, loading, error and success states, documented in wireframe notes and component sections.
+
+**Optional task fields.** A task can carry `specRefs` (anchors such as `ui_specs.md#appointment-list`), `complexity` (`simple`, `standard` or `complex`) and `acceptanceCriteria` ("done when" lines):
+
+```bash
+nativ task add "Appointment list" -a frontend --complexity standard   --spec-refs "ui_specs.md#appointment-list" --accept "Empty state shown|Rows sorted by time"
+```
+
+`--accept` can be repeated or `|`-separated. The `nativ_task_add` MCP tool takes the same three fields.
+
+**Spec slices.** For a task with `specRefs`, `nativ task next --json` adds `specSlices` (the referenced heading sections or JSON pointers, size-capped) and `specWarnings` (a ref that is missing or outside `.ai/`). The native run engine puts the same slices in a `<spec_slices>` block of the worker prompt, and `nativ validate` prints the warnings for the whole plan. Workers read a whole contract only when a slice is missing or cut short.
+
+**Model routing.** `nativ task next --json` returns `recommendedModel` from the task's `complexity`: `simple` gives `haiku`, `standard` gives `sonnet`, `complex` gives `opus`. A task with no complexity gets no recommendation and nothing changes. Override the mapping with `workerModels` in `.nativ/config.json`:
+
+```json
+{ "workerModels": { "simple": "haiku", "standard": "sonnet", "complex": "opus" } }
+```
+
+The run engine uses the routed model when you did not pass one explicitly, and the project manager passes `recommendedModel` as the `model` parameter of the Agent tool. These are Claude Code model aliases, so a Claude Pro login is enough and no API key is needed.
+
+**Code style.** `AGENTS.md` gives workers short style rules: lines of 100 characters or fewer (hard maximum 120), functions of about 40 lines, files of about 300, comments of at most 2 lines, and your own formatter config wins. `nativ verify` also runs a check on a task's target files for over-long lines and long comment blocks. It only warns by default. Tune it with `codeStyle` in `.nativ/config.json` (`mode`: `warn`, `block` or `off`; `maxLineLength`, default 120; `maxCommentLines`, default 2). The `nativ task complete` gatekeeper runs it too, warn-only.
+
+---
+
 ## Providers
 
 nativ's own model calls (currently triage of escalations) go through one adapter, so no single vendor is on the critical path.
@@ -171,6 +199,7 @@ nativ task next                  # next executable task and its contract slice
 nativ task list --available
 nativ task list --milestone m1 --status pending
 nativ task add "Implement OAuth2 callback" -a backend -v "npm test" -f "src/auth.ts"
+nativ task add "Login form" -a frontend --complexity simple --spec-refs "ui_specs.md#login-form" --accept "Errors shown inline"
 nativ task start task-01
 nativ task complete task-01                # runs the verification command
 nativ task complete task-01 --timeout 600000   # for slow suites
@@ -271,7 +300,7 @@ Task transitions and role violations are recorded in `.ai/telemetry.json`: durat
 | Tool / resource | Description |
 | :--- | :--- |
 | `nativ_task_next`, `nativ_task_list`, `nativ_task_add` | Find and add work |
-| `nativ_task_start`, `nativ_task_complete`, `nativ_task_block` | Move a task through its lifecycle (complete runs the gatekeeper) |
+| `nativ_task_start`, `nativ_task_complete`, `nativ_task_block` | Move a task through its lifecycle (complete runs the gatekeeper and refuses skipVerify) |
 | `nativ_task_escalate`, `nativ_task_propose_patch` | Escalate a contract gap, or propose a governed patch |
 | `nativ_verify`, `nativ_bench`, `nativ_status` | Verification, benchmarks, progress |
 | `nativ_worktree_*` | Create, list, merge and remove task worktrees |

package/dist/commands/task.d.ts

@@ -55,6 +55,12 @@ export interface TaskAddOptions {
     /** Dependency task IDs, comma-separated or as an array. */
     deps?: string | string[];
     notes?: string;
+    /** Spec refs, comma-separated or as an array. */
+    specRefs?: string | string[];
+    /** simple | standard | complex. */
+    complexity?: string;
+    /** "Done when" lines: an array, or one string with "|" separators. */
+    accept?: string | string[];
     json?: boolean;
 }
 export interface TaskAddResult {

package/dist/commands/task.js

@@ -1,10 +1,12 @@
 import path from 'node:path';
 import pc from 'picocolors';
 import { isSubagentType, SUBAGENT_TYPES, validateMasterPlanTask, } from '../scanner/types.js';
-import { executeVerification } from '../core/verifier.js';
+import { applyCodeShape, executeVerification } from '../core/verifier.js';
 import { ContractGovernor, CircuitBreaker, TestIntegrityGuard, resolveGitHead, appendEscalation, } from '../governor/index.js';
 import { loadPlan, savePlan, withPlanLock } from '../core/lock-manager.js';
 import { recordTaskStart, recordTaskComplete } from '../core/telemetry.js';
+import { resolveSpecSlices } from '../core/spec-slices.js';
+import { resolveWorkerModel } from '../core/model-routing.js';
 import { addTaskUnlock, removeTaskUnlock } from '../core/enforcement.js';
 export { loadPlan, savePlan, withPlanLock };
 function getPlanPath(targetDirArg) {
@@ -256,6 +258,10 @@ export async function runTaskNext(targetDirArg, options = {}) {
     const roleGuide = getRoleGuide(targetTask.assignedSubagent);
     const contractSlice = getRecommendedContractSlice(targetTask.assignedSubagent);
     if (options.json) {
+        const specResult = targetTask.specRefs?.length
+            ? resolveSpecSlices(path.dirname(path.dirname(planPath)), targetTask.specRefs)
+            : null;
+        const recommendedModel = resolveWorkerModel(path.dirname(path.dirname(planPath)), targetTask);
         console.log(JSON.stringify({
             status: 'ready',
             milestoneId: activeMilestone.id,
@@ -264,6 +270,8 @@ export async function runTaskNext(targetDirArg, options = {}) {
                 ...targetTask,
                 roleGuide,
                 recommendedContractSlice: contractSlice,
+                ...(recommendedModel ? { recommendedModel } : {}),
+                ...(specResult ? { specSlices: specResult.slices, ...(specResult.warnings.length ? { specWarnings: specResult.warnings } : {}) } : {}),
             }
         }, null, 2));
         return;
@@ -417,7 +425,8 @@ export async function runTaskComplete(taskId, targetDirArg, options = {}) {
     // ── Verification Gatekeeper ────────────────────────────────────────────────
     let vResult = null;
     if (!options.skipVerify) {
-        vResult = await executeVerification(foundTask.verificationCommand, targetDir, options.timeout);
+        const rawResult = await executeVerification(foundTask.verificationCommand, targetDir, options.timeout);
+        vResult = applyCodeShape(rawResult, targetDir, foundTask);
         if (!vResult.success) {
             console.error(pc.red(`\n✖ Task [${pc.bold(taskId)}] verification FAILED with exit code ${vResult.exitCode}:`));
             console.error(pc.yellow(`  Command: \`${foundTask.verificationCommand}\``));
@@ -704,6 +713,12 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
                 return failTaskAdd('NO_OPEN_MILESTONE', 'Every milestone is completed. Pass --milestone <id> to reopen one, or --fast-path', options.json);
             }
         }
+        const specRefs = [...new Set(splitList(options.specRefs))];
+        const acceptanceCriteria = (Array.isArray(options.accept) ? options.accept : options.accept ? [options.accept] : [])
+            .flatMap((item) => item.split('|'))
+            .map((item) => item.trim())
+            .filter(Boolean);
+        const complexity = options.complexity?.trim().toLowerCase();
         const task = {
             id: generateNextTaskId(plan),
             title: cleanTitle,
@@ -715,6 +730,9 @@ export async function runTaskAdd(title, targetDirArg, options = {}) {
             verificationCommand: (options.verify ?? '').trim(),
             notes: (options.notes ?? '').trim(),
             ...(fastPath ? { fastPath: true } : {}),
+            ...(specRefs.length ? { specRefs } : {}),
+            ...(complexity ? { complexity: complexity } : {}),
+            ...(acceptanceCriteria.length ? { acceptanceCriteria } : {}),
         };
         const problems = validateMasterPlanTask(task);
         if (problems.length) {

package/dist/commands/validate.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import pc from 'picocolors';
+import { resolveSpecSlices } from '../core/spec-slices.js';
 export async function runValidate(targetDirArg) {
     const targetDir = path.resolve(targetDirArg || process.cwd());
     console.log(pc.bold(pc.cyan(`\n🔍 Validating AI Agent Workflow Contracts in: ${targetDir}\n`)));
@@ -52,6 +53,19 @@ export async function runValidate(targetDirArg) {
             hasErrors = true;
         }
     }
+    if (plan && Array.isArray(plan.milestones)) {
+        const specWarnings = [];
+        for (const m of plan.milestones) {
+            for (const t of Array.isArray(m?.tasks) ? m.tasks : []) {
+                if (!Array.isArray(t?.specRefs) || !t.specRefs.length)
+                    continue;
+                for (const w of resolveSpecSlices(targetDir, t.specRefs).warnings)
+                    specWarnings.push(`${t.id}: ${w}`);
+            }
+        }
+        for (const w of specWarnings)
+            console.log(pc.yellow(`  ⚠ ${w}`));
+    }
     const escalationPath = path.join(targetDir, '.ai/escalation.json');
     if (fs.existsSync(escalationPath)) {
         const escData = checkFile('.ai/escalation.json', true);

package/dist/core/code-shape.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Code-shape check: flags over-long lines and long comment blocks in a task's target files.
+ * Settings live under `codeStyle` in .nativ/config.json. Default mode is 'warn'.
+ * Exempt: a license/header comment at the top of a file, and JSDoc directly above an export.
+ */
+export type CodeShapeMode = 'warn' | 'block' | 'off';
+export interface CodeShapeSettings {
+    mode: CodeShapeMode;
+    maxLineLength: number;
+    maxCommentLines: number;
+}
+export interface CodeShapeIssue {
+    file: string;
+    line: number;
+    kind: 'long-line' | 'long-comment';
+    message: string;
+}
+export interface CodeShapeReport {
+    mode: CodeShapeMode;
+    issues: CodeShapeIssue[];
+}
+export declare function loadCodeShapeSettings(targetDir: string): CodeShapeSettings;
+export declare function checkFileShape(file: string, text: string, s: CodeShapeSettings): CodeShapeIssue[];
+export declare function checkCodeShape(targetDir: string, targetFiles?: string[]): CodeShapeReport;
+/** Short plain-language summary; empty string when there is nothing to report. */
+export declare function formatCodeShapeReport(report: CodeShapeReport): string;

package/dist/core/code-shape.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULTS = { mode: 'warn', maxLineLength: 120, maxCommentLines: 2 };
+const SOURCE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.kt', '.dart',
+    '.c', '.cc', '.cpp', '.h', '.cs', '.rb', '.php', '.swift', '.vue', '.svelte', '.css', '.scss',
+]);
+const SKIPPED_DIRS = ['dist', 'build', 'node_modules', 'generated', '.next', 'coverage'];
+const MAX_SHOWN = 10;
+export function loadCodeShapeSettings(targetDir) {
+    const settings = { ...DEFAULTS };
+    try {
+        const raw = fs.readFileSync(path.join(targetDir, '.nativ', 'config.json'), 'utf8');
+        const style = JSON.parse(raw)?.codeStyle;
+        if (!style || typeof style !== 'object')
+            return settings;
+        if (['warn', 'block', 'off'].includes(style.mode))
+            settings.mode = style.mode;
+        if (Number.isInteger(style.maxLineLength) && style.maxLineLength > 0) {
+            settings.maxLineLength = style.maxLineLength;
+        }
+        if (Number.isInteger(style.maxCommentLines) && style.maxCommentLines > 0) {
+            settings.maxCommentLines = style.maxCommentLines;
+        }
+    }
+    catch {
+        // Missing or unreadable config: use defaults.
+    }
+    return settings;
+}
+function isCheckable(file) {
+    const parts = file.split(/[\\/]/);
+    if (parts.some((p) => SKIPPED_DIRS.includes(p)))
+        return false;
+    const base = parts[parts.length - 1];
+    if (/\.(min|generated|g)\./.test(base) || base.endsWith('.d.ts'))
+        return false;
+    return SOURCE_EXTENSIONS.has(path.extname(base).toLowerCase());
+}
+/** Returns the comment-block runs as { start, length, exempt } (start is a 1-based line number). */
+function findCommentBlocks(lines) {
+    const blocks = [];
+    let inBlock = false;
+    let current = null;
+    let seenCode = false;
+    const close = (endIndex) => {
+        if (!current)
+            return;
+        const next = lines.slice(endIndex + 1).find((l) => l.trim() !== '') ?? '';
+        const header = !seenCode && current.start <= 3;
+        const exportedDoc = current.jsdoc && /^\s*export\b/.test(next);
+        blocks.push({ start: current.start, length: current.length, exempt: header || exportedDoc });
+        current = null;
+    };
+    lines.forEach((line, i) => {
+        const t = line.trim();
+        const isComment = inBlock || t.startsWith('//') || t.startsWith('/*');
+        if (isComment) {
+            current ??= { start: i + 1, length: 0, jsdoc: t.startsWith('/**') };
+            current.length++;
+            if (t.startsWith('/*') && !t.includes('*/'))
+                inBlock = true;
+            if (inBlock && t.includes('*/'))
+                inBlock = false;
+            return;
+        }
+        close(i - 1);
+        if (t !== '')
+            seenCode = true;
+    });
+    close(lines.length - 1);
+    return blocks;
+}
+export function checkFileShape(file, text, s) {
+    const issues = [];
+    const lines = text.split(/\r?\n/);
+    lines.forEach((line, i) => {
+        if (line.length > s.maxLineLength) {
+            issues.push({
+                file, line: i + 1, kind: 'long-line',
+                message: `line is ${line.length} characters (max ${s.maxLineLength})`,
+            });
+        }
+    });
+    for (const b of findCommentBlocks(lines)) {
+        if (b.length > s.maxCommentLines && !b.exempt) {
+            issues.push({
+                file, line: b.start, kind: 'long-comment',
+                message: `comment block is ${b.length} lines (max ${s.maxCommentLines})`,
+            });
+        }
+    }
+    return issues;
+}
+export function checkCodeShape(targetDir, targetFiles = []) {
+    const settings = loadCodeShapeSettings(targetDir);
+    const report = { mode: settings.mode, issues: [] };
+    if (settings.mode === 'off')
+        return report;
+    for (const file of targetFiles) {
+        if (!isCheckable(file))
+            continue;
+        const full = path.resolve(targetDir, file);
+        try {
+            if (!fs.statSync(full).isFile())
+                continue;
+            report.issues.push(...checkFileShape(file, fs.readFileSync(full, 'utf8'), settings));
+        }
+        catch {
+            // File missing or unreadable: skip.
+        }
+    }
+    return report;
+}
+/** Short plain-language summary; empty string when there is nothing to report. */
+export function formatCodeShapeReport(report) {
+    if (report.mode === 'off' || report.issues.length === 0)
+        return '';
+    const total = report.issues.length;
+    const head = report.mode === 'block'
+        ? `Code shape: ${total} issue(s) must be fixed before this task can pass.`
+        : `Code shape: ${total} style warning(s). Verification is not affected.`;
+    const shown = report.issues.slice(0, MAX_SHOWN).map((i) => `  ${i.file}:${i.line} ${i.message}`);
+    const more = total > MAX_SHOWN ? [`  ...and ${total - MAX_SHOWN} more`] : [];
+    return [head, ...shown, ...more].join('\n');
+}

package/dist/core/model-routing.d.ts

@@ -0,0 +1,6 @@
+import { type MasterPlanTask, type TaskComplexity } from '../scanner/types.js';
+export declare const DEFAULT_WORKER_MODELS: Record<TaskComplexity, string>;
+/** Model alias for the task, or null when it has no complexity (behaviour stays unchanged). */
+export declare function resolveWorkerModel(root: string, task: Pick<MasterPlanTask, 'complexity'>): string | null;
+/** Turns an alias into a full model ID for the native engine; unknown values pass through. */
+export declare function toNativeModelId(model: string, opusModelId: string): string;

package/dist/core/model-routing.js

@@ -0,0 +1,49 @@
+/**
+ * Picks the worker model from a task's complexity.
+ * Overrides live under `workerModels` in .nativ/config.json. The separate `models` key is
+ * for nativ's own provider calls and is never read here.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { TASK_COMPLEXITIES } from '../scanner/types.js';
+export const DEFAULT_WORKER_MODELS = {
+    simple: 'haiku',
+    standard: 'sonnet',
+    complex: 'opus',
+};
+// Full IDs for the native engine. Opus is passed in by the caller (its default model).
+const NATIVE_MODEL_IDS = {
+    haiku: 'claude-haiku-4-5-20251001',
+    sonnet: 'claude-sonnet-4-6',
+};
+function loadWorkerModelOverrides(root) {
+    try {
+        const raw = fs.readFileSync(path.join(root, '.nativ', 'config.json'), 'utf8');
+        const overrides = JSON.parse(raw)?.workerModels;
+        if (!overrides || typeof overrides !== 'object')
+            return {};
+        const result = {};
+        for (const level of TASK_COMPLEXITIES) {
+            const value = overrides[level];
+            if (typeof value === 'string' && value.trim())
+                result[level] = value.trim();
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/** Model alias for the task, or null when it has no complexity (behaviour stays unchanged). */
+export function resolveWorkerModel(root, task) {
+    const level = task.complexity;
+    if (!level || !TASK_COMPLEXITIES.includes(level))
+        return null;
+    return loadWorkerModelOverrides(root)[level] ?? DEFAULT_WORKER_MODELS[level];
+}
+/** Turns an alias into a full model ID for the native engine; unknown values pass through. */
+export function toNativeModelId(model, opusModelId) {
+    if (model === 'opus')
+        return opusModelId;
+    return NATIVE_MODEL_IDS[model] ?? model;
+}

package/dist/core/spec-slices.d.ts

@@ -0,0 +1,27 @@
+export interface SpecSlice {
+    ref: string;
+    /** Path relative to the project root, forward slashes (e.g. ".ai/ui_specs.md"). */
+    file: string;
+    text: string;
+    truncated: boolean;
+}
+export interface SpecSliceResult {
+    slices: SpecSlice[];
+    warnings: string[];
+}
+export interface SpecSliceOptions {
+    /** Cap per slice (default 4000 characters). */
+    maxChars?: number;
+    /** Cap across all slices (default 4x maxChars). */
+    maxTotalChars?: number;
+}
+export declare const DEFAULT_SLICE_CHARS = 4000;
+export declare const TRUNCATION_MARKER = "\n[... truncated ...]";
+/** GitHub-style heading slug: lowercase, drop punctuation, spaces to hyphens. */
+export declare function slugifyHeading(text: string): string;
+/**
+ * Resolves specRefs ("ui_specs.md#anchor", "api_contracts.json#/paths/~1x",
+ * "api_contracts.json#GET /x" or "api_contracts.json#<endpoint id>") relative to
+ * <root>/.ai into size-capped slices. Unresolvable refs produce a warning and no slice.
+ */
+export declare function resolveSpecSlices(root: string, specRefs: string[] | undefined, options?: SpecSliceOptions): SpecSliceResult;

package/dist/core/spec-slices.js

@@ -0,0 +1,194 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_SLICE_CHARS = 4000;
+export const TRUNCATION_MARKER = '\n[... truncated ...]';
+/** GitHub-style heading slug: lowercase, drop punctuation, spaces to hyphens. */
+export function slugifyHeading(text) {
+    return text
+        .trim()
+        .toLowerCase()
+        .replace(/[`*_~]/g, '')
+        .replace(/[^\p{L}\p{N}\s-]/gu, '')
+        .replace(/\s/g, '-');
+}
+function cap(text, max) {
+    if (text.length <= max)
+        return { text, truncated: false };
+    return { text: text.slice(0, Math.max(0, max)) + TRUNCATION_MARKER, truncated: true };
+}
+function markdownSection(content, anchor) {
+    const wanted = decodeURIComponent(anchor).toLowerCase();
+    const lines = content.split(/\r?\n/);
+    const seen = new Map();
+    let inFence = false;
+    let start = -1;
+    let level = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s{0,3}(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const m = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+        if (!m)
+            continue;
+        const hLevel = m[1].length;
+        if (start >= 0) {
+            if (hLevel <= level)
+                return lines.slice(start, i).join('\n').trimEnd();
+            continue;
+        }
+        const base = slugifyHeading(m[2]);
+        const count = seen.get(base) ?? 0;
+        seen.set(base, count + 1);
+        const slug = count === 0 ? base : `${base}-${count}`;
+        if (slug === wanted) {
+            start = i;
+            level = hLevel;
+        }
+    }
+    return start >= 0 ? lines.slice(start).join('\n').trimEnd() : null;
+}
+function jsonPointerValue(doc, pointer) {
+    if (pointer === '')
+        return { found: true, value: doc };
+    if (!pointer.startsWith('/'))
+        return { found: false };
+    let current = doc;
+    for (const raw of pointer.slice(1).split('/')) {
+        let token;
+        try {
+            token = decodeURIComponent(raw);
+        }
+        catch {
+            token = raw;
+        }
+        token = token.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (Array.isArray(current)) {
+            if (!/^(0|[1-9]\d*)$/.test(token) || Number(token) >= current.length)
+                return { found: false };
+            current = current[Number(token)];
+        }
+        else if (current && typeof current === 'object' && Object.prototype.hasOwnProperty.call(current, token)) {
+            current = current[token];
+        }
+        else {
+            return { found: false };
+        }
+    }
+    return { found: true, value: current };
+}
+function joinUrl(base, p) {
+    return typeof base === 'string' ? base.replace(/\/+$/, '') + p : p;
+}
+/** Finds an endpoint by "GET /path" (with or without baseUrl) or by its id. */
+function endpointValue(doc, fragment) {
+    let ref = fragment;
+    try {
+        ref = decodeURIComponent(fragment);
+    }
+    catch {
+        // keep the raw text when it is not valid percent-encoding
+    }
+    ref = ref.trim();
+    const call = /^([A-Za-z]+)\s+(\/\S*)$/.exec(ref);
+    const list = Array.isArray(doc?.endpoints) ? doc.endpoints : [];
+    if (call) {
+        const method = call[1].toLowerCase();
+        const want = call[2];
+        const hit = list.find((e) => {
+            if (!e || typeof e.path !== 'string' || String(e.method).toLowerCase() !== method)
+                return false;
+            return e.path === want || joinUrl(doc.baseUrl, e.path) === want;
+        });
+        if (hit)
+            return { found: true, value: hit };
+        const item = doc?.paths && typeof doc.paths === 'object' ? doc.paths[want] : undefined;
+        if (item && typeof item === 'object' && Object.prototype.hasOwnProperty.call(item, method)) {
+            return { found: true, value: item[method] };
+        }
+        return { found: false };
+    }
+    const byId = list.find((e) => e && typeof e.id === 'string' && e.id === ref);
+    return byId ? { found: true, value: byId } : { found: false };
+}
+function jsonRefValue(doc, fragment) {
+    if (fragment === '' || fragment.startsWith('/'))
+        return jsonPointerValue(doc, fragment);
+    return endpointValue(doc, fragment);
+}
+/**
+ * Resolves specRefs ("ui_specs.md#anchor", "api_contracts.json#/paths/~1x",
+ * "api_contracts.json#GET /x" or "api_contracts.json#<endpoint id>") relative to
+ * <root>/.ai into size-capped slices. Unresolvable refs produce a warning and no slice.
+ */
+export function resolveSpecSlices(root, specRefs, options = {}) {
+    const slices = [];
+    const warnings = [];
+    const maxChars = options.maxChars ?? DEFAULT_SLICE_CHARS;
+    const maxTotal = options.maxTotalChars ?? maxChars * 4;
+    const aiDir = path.resolve(root, '.ai');
+    let total = 0;
+    for (const ref of specRefs ?? []) {
+        if (typeof ref !== 'string' || !ref.trim())
+            continue;
+        const hash = ref.indexOf('#');
+        const filePart = (hash >= 0 ? ref.slice(0, hash) : ref).trim();
+        const fragment = hash >= 0 ? ref.slice(hash + 1) : '';
+        const full = path.resolve(aiDir, filePart);
+        const rel = path.relative(aiDir, full);
+        if (!filePart || rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+            warnings.push(`specRef "${ref}" points outside .ai/ and was ignored`);
+            continue;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(full, 'utf8');
+        }
+        catch {
+            warnings.push(`specRef "${ref}": file .ai/${rel.split(path.sep).join('/')} not found`);
+            continue;
+        }
+        let body;
+        if (/\.json$/i.test(filePart)) {
+            try {
+                const found = jsonRefValue(JSON.parse(content), fragment);
+                body = found.found ? JSON.stringify(found.value, null, 2) ?? 'null' : null;
+            }
+            catch {
+                warnings.push(`specRef "${ref}": .ai/${rel.split(path.sep).join('/')} is not valid JSON`);
+                continue;
+            }
+            if (body === null) {
+                warnings.push(`specRef "${ref}": JSON reference "${fragment}" not found`);
+                continue;
+            }
+        }
+        else if (fragment) {
+            try {
+                body = markdownSection(content, fragment);
+            }
+            catch {
+                body = null;
+            }
+            if (body === null) {
+                warnings.push(`specRef "${ref}": heading anchor "#${fragment}" not found`);
+                continue;
+            }
+        }
+        else {
+            body = content;
+        }
+        const remaining = maxTotal - total;
+        if (remaining <= 0) {
+            warnings.push(`specRef "${ref}" omitted: total spec slice budget (${maxTotal} characters) exhausted`);
+            continue;
+        }
+        const capped = cap(body, Math.min(maxChars, remaining));
+        total += capped.text.length;
+        slices.push({ ref, file: `.ai/${rel.split(path.sep).join('/')}`, text: capped.text, truncated: capped.truncated });
+    }
+    return { slices, warnings };
+}

package/dist/core/verifier.d.ts

@@ -1,4 +1,5 @@
-import { MasterPlan } from '../scanner/types.js';
+import { MasterPlan, MasterPlanTask } from '../scanner/types.js';
+import { type CodeShapeReport } from './code-shape.js';
 export interface VerificationResult {
     success: boolean;
     exitCode: number;
@@ -8,6 +9,7 @@ export interface VerificationResult {
     durationMs: number;
     error?: string;
     skipped?: boolean;
+    codeShape?: CodeShapeReport;
 }
 export interface TaskVerificationResult {
     taskId: string;
@@ -35,6 +37,11 @@ export declare function loadMasterPlan(targetDir: string): {
  * Execute a verification command in the workspace directory with timeout and output capture.
  */
 export declare function executeVerification(command: string, cwd: string, timeoutMs?: number): Promise<VerificationResult>;
+/**
+ * Run the code-shape check on a task's target files and print a short summary to stderr.
+ * In 'warn' mode (default) the result is untouched; in 'block' mode issues fail it with a reason.
+ */
+export declare function applyCodeShape(result: VerificationResult, targetDir: string, task: MasterPlanTask): VerificationResult;
 /**
  * Run verification for a single specific task in the plan.
  */