agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/audit/terminologyDrift.js

@@ -0,0 +1,281 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMappingFile } from "../core/yaml.js";
+import { isSafeProjectSourcePath } from "../registries/glossaryEntryContract.js";
+import { unicodeCaselessExact } from "../registries/glossaryTermIdentity.js";
+import { containsGlossaryTerm } from "../registries/glossaryTermOccurrence.js";
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Deterministic variant ordering only; never use this key for term identity. */
+function variantSortKey(term) {
+    return term.toLowerCase();
+}
+function orderedEvidence(evidence) {
+    return [...evidence].sort((left, right) => compareText(left.source_path, right.source_path)
+        || left.line - right.line
+        || compareText(left.source_record_sha256, right.source_record_sha256));
+}
+function evidenceIdentity(item) {
+    return `${item.source_path}:${item.line}`;
+}
+function proposalWithoutDigest(proposal) {
+    const { proposal_digest: _digest, ...finding } = proposal;
+    return {
+        ...finding,
+        canonical_evidence: orderedEvidence(finding.canonical_evidence),
+        variants: finding.variants
+            .map((variant) => ({ ...variant, evidence: orderedEvidence(variant.evidence) }))
+            .sort((left, right) => compareText(variantSortKey(left.term), variantSortKey(right.term))
+            || compareText(left.term, right.term)),
+    };
+}
+export function canonicalTerminologyJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalTerminologyJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => compareText(left, right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalTerminologyJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Digest one complete finding while ignoring semantically irrelevant array order. */
+export function terminologyProposalDigest(proposal) {
+    return crypto
+        .createHash("sha256")
+        .update(canonicalTerminologyJson(proposalWithoutDigest(proposal)))
+        .digest("hex");
+}
+function canonicalProposal(seed) {
+    const ordered = seed.terms
+        .map((term) => ({ term: term.term, evidence: orderedEvidence(term.evidence) }))
+        .sort((left, right) => right.evidence.length - left.evidence.length || compareText(left.term, right.term));
+    const [canonical, ...variants] = ordered;
+    const finding = {
+        family: "terminology_drift",
+        concept: seed.concept,
+        proposed_canonical_term: canonical.term,
+        canonical_evidence: canonical.evidence,
+        variants: variants.sort((left, right) => compareText(variantSortKey(left.term), variantSortKey(right.term))
+            || compareText(left.term, right.term)),
+        severity: seed.confidence < 70 ? "info" : seed.severity,
+        confidence: seed.confidence,
+        ...(seed.personal_divergence ? { personal_divergence: seed.personal_divergence } : {}),
+    };
+    return { ...finding, proposal_digest: terminologyProposalDigest(finding) };
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function exactFields(value, allowed) {
+    return Object.keys(value).every((field) => allowed.includes(field));
+}
+function proposalEvidence(value, label, violations) {
+    if (!mapping(value) || !exactFields(value, ["source_path", "line", "source_record_sha256"])) {
+        violations.push(`${label} must contain only source_path, line, and source_record_sha256`);
+        return null;
+    }
+    if (!isSafeProjectSourcePath(value.source_path)
+        || !Number.isInteger(value.line)
+        || Number(value.line) < 1
+        || typeof value.source_record_sha256 !== "string"
+        || !/^[a-f0-9]{64}$/.test(value.source_record_sha256)) {
+        violations.push(`${label} must identify one safe project-relative source line with a lowercase SHA-256`);
+        return null;
+    }
+    return value;
+}
+/** Validate and normalize the complete finding shape that Audit itself can emit. */
+export function validateTerminologyProposal(value) {
+    const violations = [];
+    const fields = ["family", "concept", "proposed_canonical_term", "canonical_evidence", "variants", "severity", "confidence", "personal_divergence", "proposal_digest"];
+    if (!mapping(value) || !exactFields(value, fields)) {
+        return { proposal: null, violations: ["proposal must be one complete terminology_drift finding with no undeclared fields"] };
+    }
+    if (value.family !== "terminology_drift")
+        violations.push("proposal family must be terminology_drift");
+    if (typeof value.concept !== "string" || value.concept.trim() === "")
+        violations.push("proposal concept must be non-empty");
+    if (typeof value.proposed_canonical_term !== "string" || value.proposed_canonical_term.trim() === "")
+        violations.push("proposed canonical term must be non-empty");
+    if (!["critical", "warning", "info"].includes(String(value.severity)))
+        violations.push("proposal severity is invalid");
+    const minimumConfidence = confidenceFloor();
+    if (!Number.isInteger(value.confidence) || Number(value.confidence) < minimumConfidence || Number(value.confidence) > 100) {
+        violations.push(`proposal confidence must be an integer from ${minimumConfidence} through 100`);
+    }
+    if (Number.isInteger(value.confidence) && Number(value.confidence) < 70 && value.severity !== "info") {
+        violations.push("confidence below 70 requires info severity");
+    }
+    if (typeof value.proposal_digest !== "string" || !/^[a-f0-9]{64}$/.test(value.proposal_digest))
+        violations.push("proposal_digest must be a lowercase SHA-256");
+    const terms = [];
+    const readTerm = (term, records, label) => {
+        if (typeof term !== "string" || term.trim() === "") {
+            violations.push(`${label} term must be non-empty`);
+            return;
+        }
+        if (!Array.isArray(records) || records.length === 0) {
+            violations.push(`${label} evidence must be non-empty`);
+            return;
+        }
+        const parsed = records
+            .map((record, index) => proposalEvidence(record, `${label}[${index}]`, violations))
+            .filter((record) => record !== null);
+        if (new Set(parsed.map(evidenceIdentity)).size !== parsed.length) {
+            violations.push(`${label} identities must be distinct`);
+        }
+        terms.push({ term, evidence: parsed });
+    };
+    readTerm(value.proposed_canonical_term, value.canonical_evidence, "canonical_evidence");
+    if (!Array.isArray(value.variants) || value.variants.length === 0) {
+        violations.push("proposal variants must be non-empty");
+    }
+    else {
+        value.variants.forEach((variant, index) => {
+            if (!mapping(variant) || !exactFields(variant, ["term", "evidence"])) {
+                violations.push(`variants[${index}] must contain only term and evidence`);
+                return;
+            }
+            readTerm(variant.term, variant.evidence, `variants[${index}].evidence`);
+        });
+    }
+    if (terms.some((term, index) => terms.slice(0, index).some((candidate) => unicodeCaselessExact(candidate.term, term.term)))) {
+        violations.push("proposal term identities must be Unicode caseless-exact unique");
+    }
+    let divergence;
+    if (value.personal_divergence !== undefined) {
+        if (!mapping(value.personal_divergence)
+            || !exactFields(value.personal_divergence, ["personal_term", "project_term"])
+            || typeof value.personal_divergence.personal_term !== "string"
+            || value.personal_divergence.personal_term.trim() === ""
+            || value.personal_divergence.project_term !== value.proposed_canonical_term)
+            violations.push("personal_divergence must bind a non-empty personal term to the proposed project term");
+        else
+            divergence = value.personal_divergence;
+    }
+    if (violations.length > 0 || terms.length < 2)
+        return { proposal: null, violations };
+    const expected = canonicalProposal({
+        family: "terminology_drift",
+        concept: value.concept,
+        terms,
+        severity: value.severity,
+        confidence: value.confidence,
+        ...(divergence ? { personal_divergence: divergence } : {}),
+    });
+    if (expected.proposed_canonical_term !== value.proposed_canonical_term)
+        violations.push("proposed canonical term is not the best-supported term under the Audit tie-break");
+    if (canonicalTerminologyJson(proposalWithoutDigest(expected)) !== canonicalTerminologyJson(proposalWithoutDigest(value))) {
+        violations.push("proposal shape or ordering is not the canonical Audit output");
+    }
+    if (expected.proposal_digest !== value.proposal_digest)
+        violations.push("proposal_digest does not match the canonical Audit output");
+    return { proposal: violations.length === 0 ? expected : null, violations };
+}
+function confidenceFloor() {
+    const protocol = loadYamlMappingFile(path.join(resolveSourceRoot(), "skills", "agentera", "protocol.yaml"));
+    const scale = protocol.CONFIDENCE_SCALE;
+    const range = scale?.["3"]?.range;
+    if (!Array.isArray(range) || !Number.isInteger(range[0])) {
+        throw new Error("protocol CONFIDENCE_SCALE CS3 lower bound is unavailable");
+    }
+    return Number(range[0]);
+}
+function verifiedEvidence(projectRoot, term, evidence) {
+    const root = fs.realpathSync(projectRoot);
+    const verified = [];
+    const identities = new Set();
+    for (const item of evidence) {
+        if (!Number.isInteger(item.line) || item.line < 1 || !isSafeProjectSourcePath(item.source_path))
+            return null;
+        const pathname = path.resolve(root, item.source_path);
+        if (pathname !== root && !pathname.startsWith(`${root}${path.sep}`))
+            return null;
+        let realPath;
+        try {
+            realPath = fs.realpathSync(pathname);
+        }
+        catch {
+            return null;
+        }
+        if (!realPath.startsWith(`${root}${path.sep}`) || !fs.statSync(realPath).isFile())
+            return null;
+        const line = fs.readFileSync(realPath, "utf8").split(/\r?\n/)[item.line - 1];
+        if (line === undefined || !containsGlossaryTerm(line, term))
+            return null;
+        const sourcePath = path.relative(root, realPath).split(path.sep).join(path.posix.sep);
+        const identity = `${sourcePath}:${item.line}`;
+        if (identities.has(identity))
+            continue;
+        identities.add(identity);
+        verified.push({
+            source_path: sourcePath,
+            line: item.line,
+            source_record_sha256: crypto.createHash("sha256").update(line).digest("hex"),
+        });
+    }
+    return verified.length > 0 ? verified : null;
+}
+/** Generate findings from assessed concepts without writing project or personal state. */
+export function assessTerminologyDrift(input) {
+    const minimumConfidence = confidenceFloor();
+    const findings = [];
+    for (const concept of input.concepts) {
+        if (concept.confidence < minimumConfidence ||
+            concept.confidence > 100 ||
+            !Number.isInteger(concept.confidence) ||
+            input.deliberateDecisionConcepts.has(concept.concept) ||
+            input.trackedIssueConcepts.has(concept.concept))
+            continue;
+        const consolidated = [];
+        let invalidEvidence = false;
+        for (const candidate of concept.terms) {
+            const term = candidate.term.trim();
+            const evidence = term ? verifiedEvidence(input.projectRoot, term, candidate.evidence) : null;
+            if (!evidence) {
+                invalidEvidence = true;
+                break;
+            }
+            const group = consolidated.find((item) => unicodeCaselessExact(item.term, term)) ?? { term, evidence: new Map() };
+            for (const item of evidence)
+                group.evidence.set(`${item.source_path}:${item.line}`, item);
+            if (!consolidated.includes(group))
+                consolidated.push(group);
+        }
+        if (invalidEvidence || consolidated.length < 2)
+            continue;
+        const terms = consolidated.map((term) => ({
+            term: term.term,
+            evidence: orderedEvidence([...term.evidence.values()]),
+        }));
+        const seed = {
+            family: "terminology_drift",
+            concept: concept.concept,
+            terms,
+            severity: concept.severity,
+            confidence: concept.confidence,
+        };
+        let finding = canonicalProposal(seed);
+        const personalTerm = input.personalTerms?.get(concept.concept)?.trim();
+        if (personalTerm && !unicodeCaselessExact(personalTerm, finding.proposed_canonical_term)) {
+            finding = canonicalProposal({
+                ...seed,
+                personal_divergence: {
+                    personal_term: personalTerm,
+                    project_term: finding.proposed_canonical_term,
+                },
+            });
+        }
+        const validated = validateTerminologyProposal(finding);
+        if (!validated.proposal)
+            throw new Error(`Audit produced an invalid terminology proposal: ${validated.violations.join("; ")}`);
+        findings.push(validated.proposal);
+    }
+    return findings;
+}

package/dist/bin/agentera.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import { main } from "../cli/dispatch.js";
-process.exit(main(process.argv));
-//# sourceMappingURL=agentera.js.map
+// Assigning exitCode lets Node drain piped stdout/stderr before the process
+// terminates. Calling process.exit() here truncates large command payloads.
+process.exitCode = main(process.argv);

package/dist/capabilities/audit/instructions.js

@@ -0,0 +1,16 @@
+// Markdown instructions served via agentera prime --context audit --format json
+export const instructions = JSON.parse(String.raw `"# AUDIT\n\n**Integrity Navigation: Systematic Pattern Evaluation, Knowledge Tracing. Examine, Report, Advise.**\n\nCodebase health audit: multi-dimensional structural quality evaluation with evidence-based findings, confidence scores, and trajectory tracking. The retrospective counterpart to build's forward motion: is the codebase getting better or just bigger? Each invocation = one audit. Findings feed build's work selection via TODO.md.\n\nGlyph: **⛶** (protocol ref: SG3). Used in the mandatory exit marker.\n\nRead \u0060capability_context.startup.outcome\u0060 and use bounded \u0060evidence_context\u0060 from \u0060agentera prime --context audit --format json\u0060 for evaluation startup. For deferred detail, use the matching availability row\u0027s exact \u0060detail_command\u0060. Do not re-encode machine-readable rules in prose.\n\n---\n\n## State artifacts\n\n| Artifact | Role | Path |\n|----------|------|------|\n| health | produces_and_consumes | \u0060.agentera/health.yaml\u0060 |\n| todo | produces_and_consumes | TODO.md |\n| decisions | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| progress | consumes | \u0060.agentera/progress.yaml\u0060 |\n| plan | consumes | \u0060.agentera/plan.yaml\u0060 |\n| docs | consumes | \u0060.agentera/docs.yaml\u0060 |\n| vision | consumes (protected) | \u0060.agentera/vision.yaml\u0060 |\n| design | consumes (optional) | DESIGN.md |\n| profile | consumes | Profile state from \u0060evidence_context.residual_risks\u0060 |\n\n### health.yaml shape\n\n\u0060\u0060\u0060yaml\naudits:\n  - number: 1\n    date: YYYY-MM-DD\n    dimensions: [architecture_alignment, test_health]\n    findings_summary: \"X critical, Y warnings, Z info\"\n    overall: stable\n    dimension_grades:\n      - dimension: architecture_alignment\n        grade: B\n    findings:\n      - severity: degraded\n        title: Finding title\n        confidence: 80\n        location: file:line\n        evidence: What was observed.\n        impact: Why this matters.\n        suggested_action: Specific fix or investigation.\n    trends: What improved, degraded, or changed.\n    patterns_observed: De facto architecture patterns.\n\u0060\u0060\u0060\n\nEvery finding MUST include \u0060location\u0060, \u0060evidence\u0060, \u0060impact\u0060, \u0060suggested_action\u0060, and \u0060confidence\u0060. WARN and FAIL findings MUST carry a reproducible anchor: \u0060location: <file>:<line>\u0060 (or \u0060not-applicable: <reason>\u0060). WARN rows with file:line citations SHOULD include \u0060verify_command\u0060 — the exact \u0060grep\u0060 or \u0060git show\u0060 invocation that reproduces the evidence at the cited line. Prose-only evidence for WARN/FAIL findings is incomplete.\n\n### Evidence context startup\n\nStart with \u0060agentera prime --context audit --format json\u0060. Use the returned \u0060evidence_context\u0060 for prior audit findings, known issues, decision caveats, protected-state boundaries, version checks, progress verification, and residual risks. If \u0060evidence_context\u0060 is absent or caveated for a state family you need, read \u0060capability_context.startup.outcome\u0060 and use the matching \u0060capability_context.startup.availability\u0060 row\u0027s exact \u0060detail_command\u0060 for deferred detail. Raw artifact reads are last-resort diagnostics, not normal startup behavior. Preserve caveats — they calibrate confidence, not approval to refresh state, read vision, edit objective state, or contact remotes.\n\n---\n\n## Workflow phases\n\nLinear: orient, select, assess, distill, report, connect.\n\n### Step 1: Orient\n\nUse \u0060evidence_context\u0060 for prior audits, decisions, TODO, and progress. Then project discovery: map directory structure, read dependency manifests, README, AGENTS.md, identify language/stack/build commands, \u0060git log --oneline -20\u0060.\n\nDerive change magnitude: \u0060git log --stat\u0060 on commits since the last audit timestamp to estimate total change volume. If the audit timestamp is unavailable, skip; default depth applies.\n\nList key structural facts (module boundaries, dependency patterns, test coverage gaps) in your response. These survive context compaction.\n\n**Exit-early stop condition**: if \u0060git diff\u0060 since the last audit timestamp shows no file changes, report \u0060─── ⛶ audit · complete ───\u0060 with \"no changes since last audit\" and stop.\n\n### Step 2: Select dimensions\n\nChoose dimensions based on the codebase and user request. Not every dimension applies; a 200-line CLI does not need the same audit as a monorepo.\n\n#### Available dimensions\n\n| Dimension | What it evaluates | When to include |\n|-----------|-------------------|-----------------|\n| Architecture alignment | Does the code match stated architecture? Pattern mismatches, module boundary violations, layering breaks. | \u0060.agentera/vision.yaml\u0060 or README describes architecture |\n| Pattern consistency | Are patterns used consistently? Naming, error handling, structure, abstractions. | Any codebase with 5+ modules or files |\n| Coupling health | Hidden dependencies, circular imports, god modules, inappropriate intimacy. | Any codebase with multiple modules |\n| Complexity hotspots | Functions too long, deeply nested, high fan-out, accumulated conditionals. | Any codebase |\n| Test health | Coverage gaps, test quality, test-to-code ratio, behavior vs implementation testing. | Project has tests |\n| Dependency health | Outdated deps, security advisories, unused deps, dep sprawl, pinning discipline. | Project has external dependencies |\n| Version health | Unreleased significant changes: \u0060feat\u0060/\u0060fix\u0060 commits since last version bump. | \u0060.agentera/docs.yaml\u0060 has a \u0060versioning\u0060 convention block |\n| Artifact freshness | Are state artifacts current relative to plan activity or recent development? Detects artifacts that should have been updated but weren't. | Plan context available or progress has entries |\n| Prose health | Do artifact entries respect writing rules? Verbosity overruns, abstraction creep, filler. | Project has 3+ artifact files |\n| Security hygiene | Hardcoded secrets, dangerous calls, injection patterns. Lightweight regex scan. | Any codebase |\n\n#### Depth guidance\n\nWhen change magnitude was derived in Step 1, apply advisory depth scaling:\n\n- **Light changes** (roughly ≤5 files, ≤200 lines since last audit): prioritize dimensions most relevant to changed areas. Skip dimensions with no intersection.\n- **Standard changes** (default): assess all applicable dimensions at normal depth.\n- **Heavy changes** (roughly ≥20 files or architectural-scope commits): assess all applicable dimensions and increase evidence depth.\n\nThese thresholds are guidelines, not hard rules. A 6-file change touching a critical security module warrants thorough depth.\n\n**User-specified dimensions**: audit only those. **Full audit or unspecified**: auto-select all applicable. Report selections before proceeding.\n\n### Step 3: Assess\n\nFor each selected dimension, run analysis and produce structured findings. Every finding MUST include: specific file and line references, quoted code or structural observation, explanation of why it matters, and confidence score (0-100, protocol: CS1-CS5).\n\nFor parallel analysis, use subagents — one per dimension. Each agent receives the dimension definition, relevant context files, and instructions to return findings matching the health.yaml finding shape.\n\n#### Version health\n\nOnly run if \u0060.agentera/docs.yaml\u0060 contains a \u0060versioning\u0060 convention block. Skip entirely if absent.\n\n- Read the \u0060versioning\u0060 convention to identify version file(s) and bump trigger rules\n- Run \u0060git log --oneline\u0060 to find \u0060feat\u0060 and \u0060fix\u0060 commits since the last modification date of the version file(s)\n- Count unbumped \u0060feat\u0060/\u0060fix\u0060 commits and note the age of the oldest one\n- Severity: warning (SF2) if 1-4 unbumped commits or age ≤ 7 days; critical (SF1) if 5+ unbumped commits or age > 7 days\n- If no \u0060feat\u0060/\u0060fix\u0060 commits since the last bump, this dimension is healthy with no finding\n\n#### Artifact freshness\n\nEvaluates whether state artifacts are current relative to plan activity or recent development.\n\n**With plan context** (\u0060.agentera/plan.yaml\u0060 has a created date and task history):\n\n- Read the plan's \u0060Created\u0060 date from its metadata\n- Identify dispatched capabilities by scanning task entries and progress cycle logs\n- For each dispatched capability, look up its expected artifacts in the staleness convention\n- Check each expected artifact's last modification: \u0060git log -1 --format=%aI -- <path>\u0060\n- An artifact is **stale** if its last modification predates the plan's creation date AND the owning capability was dispatched at least once during the plan\n- Severity: warning (SF2, confidence 70+). Plan-relative staleness carries causal evidence.\n- Artifacts that a capability reads but does not produce are not staleness candidates\n\n**Without plan context**:\n\n- Fall back to progress recency: an artifact is potentially stale if not modified since the most recent progress cycle entry date\n- If progress has no entries (fresh project), no staleness check applies\n- Severity: info (SF3, confidence 50-60). Advisory, not authoritative.\n\nStale artifact findings are reported like any other dimension finding but noted as context for the next plan cycle, not as blocking errors.\n\n#### Prose health\n\nEvaluate artifact prose quality against the three Self-Audit Protocol rules:\n\n- **Rule 1: Verbosity overrun** — approximate word count per entry. Entries exceeding their budget by 50%+ are findings.\n- **Rule 2: Abstraction creep** — scan each entry for ≥1 concrete anchor (file path, line number, commit hash 7+ hex chars, metric value with unit, identifier, direct quote). Entries with zero concrete anchors are findings.\n- **Rule 3: Filler accumulation** — flag entries with: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification.\n\nUse \u0060agentera state decisions list --limit 20 --format json\u0060 for decision artifact prose context; preserve returned caveats. Read all project artifacts (\u0060.agentera/progress.yaml\u0060, \u0060.agentera/decisions.yaml\u0060, \u0060.agentera/plan.yaml\u0060, \u0060.agentera/health.yaml\u0060, TODO.md, CHANGELOG.md, \u0060.agentera/vision.yaml\u0060, DESIGN.md, \u0060.agentera/docs.yaml\u0060) when this dimension requires raw artifact prose inspection.\n\n#### Security hygiene\n\nLightweight regex-based scan for common security anti-patterns. Surface-level check, not a replacement for dedicated security analysis.\n\nScan for hardcoded secrets (API key patterns, token strings, private keys), dangerous function calls (\u0060eval()\u0060 on variables, \u0060exec()\u0060 with string concatenation, subprocess with unsanitized input), and injection patterns (SQL string concatenation, unsanitized shell construction). Use Grep across source files; exclude \u0060.git/\u0060, \u0060node_modules/\u0060, \u0060vendor/\u0060, \u0060__pycache__/\u0060.\n\n- Hardcoded secrets: warning (SF2, confidence 75-90)\n- Dangerous function calls: warning (SF2) or critical (SF1) depending on user input flow\n- Injection patterns: warning (SF2, confidence 60-80)\n\nEvery security hygiene finding MUST include a footer recommending dedicated security tools.\n\n### Step 4: Distill\n\nAfter analysis completes:\n\n1. **Filter**: discard findings below 50 confidence. Mark 50-69 as \"info\" (SF3) regardless of apparent severity.\n2. **Deduplicate**: merge by preference: (1) fullest context, (2) most evidence-rich dimension, (3) most recent. Preserve complementary evidence from discarded findings.\n3. **Cross-reference** against \u0060.agentera/decisions.yaml\u0060 and TODO.md (via \u0060agentera state decisions list --limit 20 --format json\u0060):\n   - Matches known decision → discard or downgrade to info (SF3)\n   - Matches known issue → \"already tracked\", skip\n   - Genuinely new → include at full severity\n4. **Grade** each dimension: **A** (no critical/warning), **B** (no critical, some warnings), **C** (1-2 critical or many warnings), **D** (multiple critical), **F** (pervasive critical).\n5. **Trajectory**: compare to prior audit — improving (VT12), degrading (VT13), stable. Calculate overall trajectory.\n\n### Step 5: Report\n\nRun \u0060agentera check lint --artifact health\u0060 on the draft entry before writing. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\nWrite the audit entry with \u0060agentera state health append --input PATH --format json\u0060 (or \u0060--input -\u0060 for YAML/JSON stdin). The writer assigns the audit number, validates the candidate and final compacted bytes, and applies shared retention before publishing. No reasoning in the artifact; the conversation preserves analysis, the artifact preserves conclusions.\n\nWhen updating existing entries, edit the specific YAML entry rather than rewriting unrelated history.\n\nCompaction is writer-owned; do not hand-compact the health artifact before or after the command.\n\n#### Report structure\n\n\u0060\u0060\u0060markdown\n## Audit N · YYYY-MM-DD\n\n**Dimensions assessed**: [list]\n**Findings**: X critical, Y warnings, Z info (N filtered by confidence)\n**Overall trajectory**: ⮉ improving | stable | ⮋ degrading vs Audit N-1\n**Grades**: Architecture [B] | Patterns [A] | Coupling [C] | Complexity [B] | Tests [D] | Deps [A] | Security [A]\n\n### [Dimension Name]: [Grade]\n\n#### ⇶ [Finding title], critical (confidence: N/100)\n#### ⇉ [Finding title], warning (confidence: N/100)\n#### ⇢ [Finding title], info (confidence: N/100)\n- **Location**: \u0060file:line\u0060 (or module/package)\n- **Evidence**: [quoted code or structural observation]\n- **Impact**: [what breaks, degrades, or risks]\n- **Suggested action**: [specific fix, investigation, or refactor]\n\n### Trends vs Audit N-1\n- **Improved**: [what got better and why]\n- **Degraded**: [what got worse and why]\n- **New findings**: [issues not present in prior audit]\n- **Resolved**: [prior findings no longer present]\n\n### Patterns Observed\n[De facto architecture patterns extracted — the \"what IS\" independent of what's stated.]\n\u0060\u0060\u0060\n\n### Step 6: Connect\n\nFeed actionable findings into the suite:\n\n1. **TODO.md**: for each critical finding not already tracked, offer to add under the appropriate severity section. Severity mapping (protocol: SM1-SM3): critical (SF1) → \u0060## ⇶ Critical\u0060 (SI1), warning (SF2) → \u0060## ⇉ Degraded\u0060 (SI2), info (SF3) → \u0060## ⇢ Annoying\u0060 (SI4). Each entry: \u0060- [ ] [finding description]\u0060. Get user confirmation before writing.\n2. **\u0060.agentera/vision.yaml\u0060**: if architecture has intentionally evolved past stated architecture, suggest updating via discuss.\n3. **Present findings** and ask if the user wants to: file to TODO.md, deliberate via discuss, deep-dive on a dimension, or investigate a specific finding.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT modify source code. Audit audits; other capabilities fix.\n- MUST NOT file findings to TODO.md without explicit user confirmation.\n- MUST NOT present speculative findings (confidence < 50) as definitive problems.\n- MUST NOT flag findings that contradict deliberate decisions documented in \u0060.agentera/decisions.yaml\u0060. A deliberate decision is an implementation of intent, not a finding. Discard or downgrade.\n- MUST NOT report issues already tracked in TODO.md as new findings.\n- MUST NOT flag subjective style preferences as findings unless they violate stated principles in \u0060.agentera/vision.yaml\u0060, AGENTS.md, or the decision profile.\n- MUST NOT run destructive commands or install packages. Read-only assessment.\n- MUST NOT mark, infer, or user-confirm decision satisfaction — only the user confirms final satisfaction.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ⛶ audit · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): All selected dimensions assessed, findings synthesized, grades assigned, \u0060health\u0060 artifact updated, actionable results presented.\n- **flagged** (EX2): Completed with notable caveats — dimensions skipped due to missing tooling, confidence too low to grade reliably, or critical findings require urgent attention beyond audit scope.\n- **stuck** (EX3): Cannot complete — project inaccessible, required language tooling unavailable and manual analysis not feasible, or filing to TODO.md declined with no safe way to surface results.\n- **waiting** (EX4): The audit target is ambiguous — no project identified, codebase too incomplete to assess, or dimensions requested cannot be evaluated without additional information.\n\n---\n\n## Cross-capability integration\n\nAudit is the feedback loop: it tells build whether its work is making things better.\n\n### Feeds\n\n- **⧉ build**: Critical and warning findings filed to TODO.md become candidates for build's work selection. \"Patterns Observed\" helps build understand the codebase's de facto architecture when planning changes.\n- **❈ discuss**: When an architecture mismatch is found, suggest discuss before fixes begin.\n- **≡ plan**: When multiple related structural issues are found, suggest plan for a remediation plan.\n- **⎘ optimize**: When a dimension grade is poor and the improvement is measurable (test coverage, dependency count, complexity score), suggest optimize.\n\n### Reads\n\n- **⧉ build output**: \u0060.agentera/progress.yaml\u0060 tells audit what was built recently. Recent changes are higher-priority audit targets.\n- **❈ discuss output**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Findings that contradict deliberate decisions are not findings.\n- **◰ design output**: DESIGN.md provides identity constraints that audit can check for consistency.\n\n### Informed by\n\n- **♾ profile**: The decision profile calibrates what \"healthy\" means for this user. High-confidence quality preferences weight the grading.\n\n### Getting started\n\n**First audit**: \u0060/agentera audit\u0060 runs a full audit across all applicable dimensions, bootstraps \u0060health\u0060 artifact. Review findings, file critical ones to TODO.md, then \u0060/agentera build\u0060 picks them up.\n\n**Periodic health checks**: run audit every 5-10 build cycles, or when a major feature was added, significant refactoring occurred, the codebase feels harder to work in, or before a major architectural decision.\n\nStaleness detection: \u0060agentera prime\u0060 marks a health audit stale when \u0060AGENTERA_AUDIT_MAX_AGE_DAYS\u0060 (default 30) or \u0060AGENTERA_AUDIT_MAX_CYCLES\u0060 (default 10) since the last audit is exceeded. Either axis exceeding its threshold triggers staleness; when progress is absent, time-only evaluation still applies.\n\n**Targeted audits**: specify dimensions to narrow scope — \u0060/agentera audit architecture coupling\u0060.\n\n**After an audit**: Good grades (A/B) — keep building. Mixed (C) — file criticals, deliberate on warnings. Poor (D/F) — consider pausing feature work; use discuss for priorities, then build for structural fixes.\n\n### Orchestrate evaluation\n\nWARN and FAIL findings used by orchestrate evaluation reports MUST carry \u0060citation: <file>:<line>\u0060 per row (schema: \u0060agentera.inspekteraEvaluationReport.v1\u0060 in \u0060references/cli/capability-instruction-contract.yaml#evaluator_handoff\u0060)."`);
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## Workflow phases/, `## State artifacts
+
+Health audits, decisions, progress cycles, plans, and plan tasks use entity authority: each record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is available through bounded list and exact \`get --id ID\` commands. Begin with \`agentera prime --context audit --format json\`; read \`capability_context.startup.outcome\` and use a deferred availability row's exact \`detail_command\` for detail. Discover health writes with \`agentera state health explain --format json\` and append through the typed entity writer; never edit entity paths directly. TODO, vision, design, docs policy, and profile retain their declared editorial or protected boundaries.
+
+Publish a completed audit with \`agentera state health append --input PATH --format json\`.
+
+## Workflow phases`)
+    .replaceAll("`.agentera/decisions.yaml`", "the decisions entity view")
+    .replaceAll("`.agentera/progress.yaml`", "the progress entity view")
+    .replaceAll("`.agentera/health.yaml`", "the health entity view")
+    .replaceAll("`.agentera/plan.yaml`", "the plan entity view")
+    .replace("The writer assigns the audit number, validates the candidate and final compacted bytes, and applies shared retention before publishing.", "The writer assigns a bare ID, validates the entity, and publishes one canonical file.")
+    .replace("Read `capability_context.startup.outcome` and use bounded `evidence_context` from `agentera prime --context audit --format json` for evaluation startup. For deferred detail, use the matching availability row's exact `detail_command`. Do not re-encode machine-readable rules in prose.", "Read `capability_context.startup.outcome` and use bounded `evidence_context` from `agentera prime --context audit --format json` for evaluation startup. For deferred detail, use the matching availability row's exact `detail_command`. Do not re-encode machine-readable rules in prose.\n\n## Terminology-drift findings\n\nAudit implements one mutation-free, read-only terminology-drift finding family. Assess cited project-file terms for one concept, propose the best-supported canonical term, retain project-file evidence for every drift variant, and emit the deterministic proposal digest consumed by the typed publication path. Compare optional personal PROFILE usage without writing profile state. Apply the existing confidence, deliberate-decision, and tracked-TODO filters; weak, known, tracked, and no-drift evidence yields no finding. A proposal is not approval: Build project-glossary publication is active and requires proposal-specific user confirmation. Audit never performs consumer lookup or mutation; Discuss, Plan, and Build use the separate active read-only advice path. Personal-profile mutation and docs-mapping mutation remain outside both paths.");

package/dist/capabilities/build/instructions.js

@@ -0,0 +1,59 @@
+// Capability instructions for build
+// Served via `agentera prime --context build --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# BUILD\n\n**Relentless Execution: Autonomous Loops Iterating Software. Evolve, Refine, Adapt**\n\nGlyph: \u29c9 (protocol ref: SG2).\n\nAn autonomous development loop that evolves any software project one cycle at a time. Decisions grounded in the user's decision profile. Continuity lives in files, not memory.\n\nEach invocation = one cycle. After completing a cycle (orient through log, exit signal reported), **stop**. The next cycle starts only when the user explicitly requests it or switches to \u2388 orchestrate for autonomous multi-task execution. A compaction-continue prompt is not consent to start a new cycle.\n\nWhen offering execution mode choices after plan completion, label \u0060build\u0060 as \"one task, then stop\" and \u2388 orchestrate as \"all tasks autonomously.\"\n\n---\n\n## State artifacts\n\nBuild reads project state and writes progress, TODO, and changelog. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060progress\u0060 | produces | \u0060.agentera/progress.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | produces_and_consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060docs\u0060 | consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### progress.yaml\n\n\u0060\u0060\u0060yaml\ncycles:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    type: feat\n    phase: build\n    what: One-line summary of what shipped.\n    inspiration: External source, if any.\n    discovered: Issues or ideas found.\n    verified: Observed output, N/A tag, or rationale.\n    next: Most valuable next work.\n    context:\n      intent: Why this cycle happened.\n      constraints: What had to stay true.\n      unknowns: What remains uncertain.\n      scope: What changed.\narchive: []\n\u0060\u0060\u0060\n\nThe \u0060verified\u0060 field is mandatory for every cycle entry.\n\n### CHANGELOG.md\n\nPublic-facing change history. Keep-a-changelog format. Build appends entries under \u0060## [Unreleased]\u0060 based on commit type: \u0060feat\u0060 \u2192 Added, \u0060refactor/chore\u0060 \u2192 Changed, \u0060fix\u0060 \u2192 Fixed. On version bumps, promote the Unreleased section to a versioned heading.\n\n---\n\n## Workflow phases: The cycle\n\n### Vision bootstrap\n\nIf the vision artifact is absent and \u26e5 vision is not installed, ask the user for project direction inline (one question: \"What does this software make possible?\"). Write the answer to \u0060.agentera/vision.yaml\u0060 and proceed to the cycle. If \u26e5 vision is installed and the artifact is absent, suggest \u26e5 vision and wait for confirmation. In all other cases, skip straight to the cycle.\n\n### The cycle\n\nStep markers: display \u0060\u2500\u2500 step N/8: verb\u0060 before each step.\nSteps: orient, select, research, plan, dispatch, verify, commit, log.\n\n### Step 1: Orient\n\nStart from the Build execution-context seam:\n\n\u0060\u0060\u0060bash\nagentera prime --context build --format json\n\u0060\u0060\u0060\n\nRead \u0060capability_context.startup.outcome\u0060 and use the bounded \u0060execution_context\u0060 from the same capsule as normal startup context. For a \u0060deferred\u0060 family, use its availability row\u0027s exact \u0060detail_command\u0060. Do not read raw plan, progress, TODO, docs, health, decisions, changelog, vision, profile, or design artifacts to re-check selected work, acceptance criteria, constraints, verification expectations, or scope caveats.\n\nIf \u0060execution_context\u0060 is incomplete or caveated, preserve every caveat in the cycle report, read \u0060capability_context.startup.outcome\u0060, and for deferred detail run the matching \u0060capability_context.startup.availability\u0060 row\u0027s exact \u0060detail_command\u0060 before any last-resort raw artifact diagnostic.\n\n#### Decision satisfaction authority\n\nWhen a cycle touches decision satisfaction, agents MAY mark provisional satisfaction with evidence only. Build MUST NOT mark or imply user-confirmed satisfaction; only the user confirms final satisfaction. Missing, compacted, open, provisional, or review-needed satisfaction state remains a caveat and review pressure in the cycle report \u2014 automation MUST NOT reconstruct hidden outcomes or claim it proved user intent.\n\n#### Context consumption\n\nConsume these \u0060execution_context\u0060 fields:\n\n- \u0060work_selection\u0060: selected task or no-plan/completed-plan mode\n- \u0060acceptance_criteria\u0060: exact criteria for this cycle\n- \u0060constraints\u0060: plan constraints and protected-action boundaries\n- \u0060verification_expectations\u0060: expected validation and latest progress evidence\n- \u0060artifact_update_requirements\u0060: plan, TODO, changelog, and progress update obligations\n- \u0060changelog_boundary\u0060: current public-history boundary or fallback\n- \u0060scope_boundary\u0060: artifact-family scope and conservative source-file scope\n\nUse \u0060status.profile\u0060 for profile summary; stale or missing profile is a caveat, not approval to refresh profile state.\n\n#### Project discovery\n\nOn cycle 1 or when unfamiliar with the project:\n\n- Map the directory structure\n- Read dependency manifests and README.md, AGENTS.md\n- Identify build/test/lint commands\n- Read key source files to understand architecture\n\nRun \u0060git log --oneline -20\u0060 for recent changes.\n\nBefore proceeding, list the 3-5 facts that determine this cycle.\n\n**Exit-early stop condition (plan-driven mode only)**: If \u0060.agentera/plan.yaml\u0060 has \u0060header.status: complete\u0060 and every task is complete, perform a **plan-completion sweep** before archiving. A plan with blocked, skipped, or otherwise incomplete tasks is not complete and MUST remain visible for replanning.\n\nSweep checklist:\n\n1. **progress.yaml aggregate cycle entry**: run \u0060agentera state progress append ... --format json\u0060 with a summary of the whole plan.\n2. **CHANGELOG.md plan-level entries**: verify \u0060## [Unreleased]\u0060 covers each completed task's user-facing impact.\n3. **TODO.md milestone advance**: mark each plan task as \u0060## \u2713 Resolved\u0060.\n4. **health.yaml cross-reference**: mention any resolved findings.\n\nAfter the sweep, run \u0060agentera state plan archive --format json\u0060 and report exit signal \u0060complete: plan finished\u0060. The writer preserves immutable archive history and removes the active plan.\n\n### Step 2: Pick work\n\nChoose **one** focused increment. No backlog; decide by reasoning about the gap between vision and codebase, weighted against known issues.\n\nEach cycle: **build toward the vision, or fix something broken?** Consult the decision profile. A critical bug trumps a new feature; a minor nit does not block progress.\n\n**Building toward vision**: Read codebase and vision artifact, identify the gap, pick the smallest increment closing the most valuable part.\n\n**Fixing issues**: Pick from TODO.md by severity (critical > degraded > annoying).\n\n**Optimization-shaped work**: suggest \u2398 optimize for measurable metrics and wait for confirmation instead of silently delegating.\n\nWrite a 1-2 sentence rationale. Scope down aggressively.\n\nCompose a Context block for this cycle: intent, constraints, unknowns, and scope. Keep it \u226480 words.\n\n**Plan unknowns consumption**: If the selected task comes from \u2261 plan and the plan carries \u0060unknowns:\u0060, note in the cycle context which unknowns affect this task and what the execution resolved. Carry unresolved unknowns forward in the progress entry's \u0060context.unknowns\u0060 field.\n\n**Decision gate**: After selecting work, use \u0060agentera state decisions list --limit 20 --format json\u0060 and check whether any \u0060exploratory\u0060 (DL3) entries relate to the selected work area. Preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure in the cycle context. If an exploratory decision is found: flag the uncertain foundation, suggest \u2748 discuss to firm up the decision, and wait for confirmation. In autonomous mode, proceed with the work but log the risk.\n\n### Step 3: Seek inspiration\n\nSearch for relevant external approaches before planning.\n\n1. **Assess**: bug fixes rarely benefit from inspiration. New features, architecture decisions, and unfamiliar domains do.\n2. **Search**: 2-3 targeted web queries for libraries, articles, repos, or patterns.\n3. **Analyze**: read promising finds deeply.\n4. **Integrate**: fold applicable patterns into the plan.\n\n### Step 4: Plan\n\nWrite a concrete plan: what changes in which files, expected behavior, verification approach.\n\nRead files you plan to modify before committing to the plan.\n\nKeep small enough for one agent session. Too large? Split and save the rest.\n\n### Step 5: Dispatch\n\nSpawn an implementation sub-agent in a git worktree for isolation. Commit pending artifact changes before branching so the subagent starts from current state (\u0060git status --porcelain\u0060; if empty, skip). Use the runtime-native subagent surface (Task tool, \u0060@agent\u0060 descriptor, etc.) \u2014 never spawn by running \u0060agentera build\u0060 or other capability-name CLI commands.\n\nBefore spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If count > 0, do not merge the worktree branch \u2014 fetch the diff and apply it to the main checkout.\n\nSubagent prompt:\n\n\u0060\u0060\u0060\nYou are implementing a focused change for [project].\n\n## Task\n[The plan]\n\n## Constraints\n- Implement ONLY what the plan describes. No scope creep.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Verify the change works as described, then run the project's test/build suite.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\n### Step 6: Verify\n\nVerification has two phases: structural and behavioral. Both MUST pass before commit.\n\n**Phase A, structural verification**:\n\n1. Check the diff: does it match the plan?\n2. Functional check: does the changed behavior work end-to-end?\n3. Run the project's verification suite (test/build/lint).\n\n**Phase B, behavioral verification gate**: observe the new behavior by running the project's primary entrypoint against real project state:\n\n- CLI tool: invoke with realistic arguments\n- Library/SDK: run a smoke driver\n- Web service: send a request to a production-shaped endpoint\n- Skill repo: \u0060agentera check verify eval skills --skill <name>\u0060\n\nIf verification fails: diagnose, spawn a fix agent, re-verify.\n\n**N/A path**: If the cycle has no runnable behavior change, use \u0060N/A: <tag>\u0060 from the allowlist: \u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060, \u0060chore-build-config\u0060, \u0060test-only\u0060.\n\n### Step 7: Commit\n\nCommit with a conventional commit message: \u0060type(scope): summary\u0060.\n\nTypes: \u0060feat\u0060, \u0060fix\u0060, \u0060docs\u0060, \u0060refactor\u0060, \u0060chore\u0060, \u0060test\u0060. Include all related files. MUST NOT commit partial or broken work.\n\nIf the current task is a version bump: read \u0060.agentera/docs.yaml\u0060 for the \u0060versioning\u0060 section. Update every file in \u0060version_files\u0060.\n\n### Step 8: Log\n\n**Before writing**, run \u0060agentera check lint --artifact <artifact> --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n**Dual-write**: build maintains \u0060.agentera/progress.yaml\u0060 and root \u0060CHANGELOG.md\u0060.\n\n- **TODO.md**: add newly discovered open issues in severity bands with \u0060- [ ]\u0060. Move completed work to \u0060## \u2713 Resolved\u0060 as \u0060- [x]\u0060 with a resolution summary.\n- **progress.yaml**: run \u0060agentera state progress append --type TYPE --phase build --what TEXT --intent TEXT --verified TEXT --format json\u0060. The writer assigns the number, inserts newest-first, validates, compacts, and returns post-write state.\n- **CHANGELOG.md**: append a one-line entry under \u0060## [Unreleased]\u0060.\n\nProgress compaction is writer-owned. When a plan task closes, run \u0060agentera state plan set-status --task N --status complete --format json\u0060 rather than editing the plan directly. TODO.md Resolved compaction follows the same 10/40/50 cap via the validate-artifact hook or \u0060agentera check compact --mode fix\u0060.\n\nThen stop. One cycle complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT push to any remote. Local commits only.\n- MUST NOT bypass the project's test/lint/build suite.\n- MUST NOT modify git config or skip git hooks.\n- MUST NOT force push, amend published commits, or run destructive git operations.\n- MUST NOT add placeholder data or functionality.\n- MUST NOT modify files outside the project directory.\n- MUST NOT modify the vision artifact during a cycle \u2014 only during vision bootstrap.\n- One cycle per invocation. MUST NOT attempt multiple cycles.\n\n</critical>\n\n---\n\n## Handling blocked work\n\nIf blocked:\n\n1. Log blocker in TODO.md with context and decision needed\n2. Log skipped attempt in progress.yaml\n3. Pick different work and complete a full cycle on that instead\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060\u2500\u2500\u2500 \u29c9 build \u00b7 <status> \u2500\u2500\u2500\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060\u25b8\u0060 bullet details below the summary.\n\n- **complete** (EX1): One full cycle completed. Work selected, implemented, verified, committed, artifacts updated.\n- **flagged** (EX2): Cycle completed but with notable issues: verification warnings, scope reduction, or discoveries suggesting next cycle may face blockers.\n- **stuck** (EX3): Cannot complete: the vision artifact is missing and bootstrap can't proceed, all work blocked, or verification suite broken.\n- **waiting** (EX4): No vision artifact and no codebase to infer direction, or user instruction too ambiguous.\n\nBefore reporting any status, inspect the last 3 entries in progress.yaml. If all 3 record failed cycles, stop, log the failure pattern to TODO.md, and surface to the user. Do not attempt a 4th consecutive cycle on the same failing problem.\n\nAfter reporting an exit signal, the cycle is over \u2014 the next cycle requires an explicit user request or \u2388 orchestrate.\n\n---\n\n## Cross-capability integration\n\nBuild is part of a twelve-capability suite.\n\n### Delegates to \u26e5 vision\n\nWhen \u26e5 vision is installed and the vision artifact doesn't exist, suggest \u26e5 vision for deep vision creation. If vision is NOT installed, the vision bootstrap (above) is the standalone fallback.\n\n### Delegates to \u2398 optimize\n\nWhen picked work is optimization-shaped (improving a measurable metric), delegate to optimize.\n\n### Uses \u2b1a research\n\nIn Step 3 (Seek inspiration), search for external approaches. For deeper analysis, use \u0060/agentera research <url>\u0060.\n\n### Reads \u267e profile output\n\nEvery cycle runs the effective profile. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions.\n\n### Uses \u2748 discuss for complex decisions\n\nWhen work selection surfaces a decision too complex for inline resolution, suggest \u2748 discuss.\n\n### Consumes \u2261 plan plans\n\nWhen the plan artifact exists with pending tasks, Step 2 reads the plan instead of reasoning from vision. Pick next pending task with satisfied dependencies. Update task status. When \u0060header.status: complete\u0060 and every task is complete, run the plan-completion sweep, archive the plan, and preserve lineage/evidence.\n\n### Reads \u25a4 document output\n\n\u0060.agentera/docs.yaml\u0060 provides artifact path resolution and versioning conventions.\n\n### Reads \u25f0 design output\n\n\u0060DESIGN.md\u0060 provides visual identity context respected when building user-facing features.\n\n### Audited by \u26f6 audit\n\n\u0060.agentera/health.yaml\u0060 findings become candidates for work selection. Run \u26f6 audit every 5-10 cycles.\n"`);
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## Workflow phases: The cycle/, `## State artifacts
+
+Progress, plans, health audits, and decisions use entity authority: each record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is read through exact, list, or bounded CLI commands. Use \`agentera state <artifact> explain --format json\` before every supported mutation; never edit entity paths directly. Vision, docs policy, changelog, design, and profile remain intentional singletons.
+
+Build reads whether progress is allowed or required from the \`guidance\` and \`input_schema.semantics.progress_write_policy\` returned by \`agentera state progress explain --verb append --format json\`. Required cases append through the typed writer; allowed durable outcomes may append when future work needs them. Build advances a plan task with its bare ID through \`agentera state plan set-status --id ID\`, and is the sole owner of explicitly confirmed project terminology publication through \`agentera state glossary publish --input REQUEST\`. Glossary publication records the approval and shared entry atomically; it does not authorize glossary lookup, personal-profile mutation, or docs-mapping mutation. Build reads \`capability_context.startup.outcome\` and availability from \`agentera prime --context build --format json\`; use a deferred row's exact \`detail_command\` for detail. When no current executable plan exists, explicit transient work may instead start through \`agentera prime --context build --input <file|-> --format json\` with an \`agentera.buildExecutionRequest.v1\` mapping containing exactly \`schema_version\`, \`scope\`, and \`acceptance\`. This input is bounded, read-only, never persists or creates plan state, and conflicts with current plan-owned execution. Read profile grounding only from the \`content\` returned by \`agentera report profile-grounding --format json\` when its shared validity is \`valid\`; preserve exact absent or repair-needed recovery and never direct-read PROFILE.md. The grounding command excludes the owned personal Glossary section and fails closed on invalid sources. Root \`TODO.md\` and \`CHANGELOG.md\` remain capability-owned editorial files.
+
+## Workflow phases: The cycle`)
+    .replaceAll("--number N", "--id ID")
+    .replaceAll("--task N", "--id ID")
+    .replace("Use `status.profile` for profile summary; stale or missing profile is a caveat, not approval to refresh profile state.", `Use \`status.profile\` for profile summary; stale or missing profile is a caveat, not approval to refresh profile state.
+
+#### Governed terminology advice
+
+At initial meaning-sensitive cycle intent, request acquisition and advice with the structured, headless interface declared by \`agentera report glossary-advice --help\` and the vocabulary authority. Repeat only when a later user-authored requirement, intent, acceptance change, cycle-intent change, or clarification answer can alter the affected meaning. Do not refresh for unchanged replay, unrelated turns, background rereads, rendering, or tool output.
+
+Use only \`advice.applicable_meaning\` with \`advice.applicable_owner\`: an exact project entry governs, including an exact divergent collision, while a personal entry applies only after the CLI proves a valid project gap. Invalid or unavailable acquisition abstains; never fabricate fallback. Preserve bounded tension without changing authority.
+
+When \`review\` requires acknowledgment before disputed reliance and interaction is available, ask one focused clarification before meaning-sensitive execution. Re-run advice only for that affected meaning using the clarification answer and an authority-declared host review when applicable. Clarification is not approval or publication consent.
+
+When autonomous or no-pause execution cannot resolve required review, do not use the disputed meaning. Continue only conservatively safe work and append one Build-owned \`glossary_caveat\` current event through \`agentera state progress append\`; discover its exact flags with \`agentera state progress explain --verb append --format json\`. The writer assigns an opaque caveat identity, suppresses duplicate current events, and supports explicit resolved or superseded lifecycle events after a governed refresh. Never put a term, meaning, definition, anchor, path, raw section, provenance, or clock expiry in the caveat.
+
+Advice, tension, clarification, and caveat lifecycle never call \`agentera state glossary publish\`, create or reuse an approval, replace proposal-digest confirmation, satisfy decisions or plan state, or grant Discuss or Audit publication authority. Explicit project publication remains the separate Build-owned digest-confirmed operation.`)
+    .replaceAll("progress.yaml aggregate cycle entry", "progress entity record")
+    .replace("Every cycle runs the effective profile.", "Every cycle uses only the sanitized non-glossary profile content returned by `agentera report profile-grounding --format json`.")
+    .replaceAll("**Dual-write**: build maintains `.agentera/progress.yaml` and root `CHANGELOG.md`.", "Build conditionally records entity progress through the typed writer and maintains root `CHANGELOG.md` separately.")
+    .replaceAll("`.agentera/health.yaml` findings", "Health findings returned by `agentera state health list --format json`")
+    .replace("If `.agentera/plan.yaml` has `header.status: complete` and every task is complete", "If the selected plan entity is complete and every related task entity is complete")
+    .replace("orient through log, exit signal reported", "orient through commit, exit signal reported")
+    .replace("Steps: orient, select, research, plan, dispatch, verify, commit, log.", "Steps: orient, select, research, plan, dispatch, verify, log, commit.")
+    .replace("implemented, verified, committed, artifacts updated", "implemented, verified, artifacts updated, committed")
+    .replace(/### Step 7: Commit[\s\S]*?Then stop\. One cycle complete\./, `### Step 7: Log
+
+**Before writing**, run \`agentera check lint --artifact <artifact> --text "<draft>"\` (or \`--file <path>\`) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \`[post-audit-flagged]\` if still failing.
+
+Build conditionally records entity progress through the typed writer and maintains root \`CHANGELOG.md\` separately. Complete every required artifact update before committing so implementation, tests, and cycle state land together.
+
+- **TODO.md**: add newly discovered open issues in severity bands with \`- [ ]\`. Move completed work to \`## ✓ Resolved\` as \`- [x]\` with a resolution summary.
+- **progress**: run \`agentera state progress explain --verb append --format json\` and apply its \`progress_write_policy\`. If it requires progress, write one YAML/JSON cycle mapping and run \`agentera state progress append --input <path|-> --format json\`. If it only allows progress, write at most one record when future work needs the durable outcome as a milestone. Otherwise make no progress write. Every appended record has a non-empty \`verified\` field. The writer assigns \`id\`, \`artifact\`, and \`publication_order\`, validates the record, atomically publishes one entity, and returns post-write state. Record-content flags are retired.
+- **CHANGELOG.md**: append a one-line entry under \`## [Unreleased]\`.
+- **plan**: when a plan task closes, run \`agentera state plan set-status --id ID --status complete --format json\` rather than editing the plan directly.
+
+TODO.md Resolved compaction follows the 10/40/50 cap via the validate-artifact hook or \`agentera check compact --mode fix\`.
+
+### Step 8: Commit
+
+Commit once with a conventional commit message: \`type(scope): summary\`.
+
+Types: \`feat\`, \`fix\`, \`docs\`, \`refactor\`, \`chore\`, \`test\`. Include implementation, tests, and all required artifact updates. MUST NOT commit partial or broken work.
+
+If the current task is a version bump: read \`.agentera/docs.yaml\` for the \`versioning\` section. Update every file in \`version_files\` before committing.
+
+Then stop. One cycle complete.`)
+    .replace("- `artifact_update_requirements`: plan, TODO, changelog, and progress update obligations\n- `changelog_boundary`", "- `artifact_update_requirements`: plan, TODO, changelog, and progress update obligations\n- `progress_logging_requirements`: required, conditional, or absent progress status plus the authoritative writer policy and guidance command\n- `changelog_boundary`")
+    .replace("1. Log blocker in TODO.md with context and decision needed\n2. Log skipped attempt in progress.yaml\n3. Pick different work and complete a full cycle on that instead", "1. Log a durable blocker in TODO.md with context and the decision needed\n2. Apply the typed progress writer guidance; do not record attempt-only detail when no durable project truth changed\n3. Pick different work and complete a full cycle on that instead")
+    .replace("Before reporting any status, inspect the last 3 entries in progress.yaml. If all 3 record failed cycles, stop, log the failure pattern to TODO.md, and surface to the user. Do not attempt a 4th consecutive cycle on the same failing problem.", "Do not reconstruct attempt or retry history from progress. Plan evaluation owns task attempts, and qualification or publication receipts own release attempts. Use those authorities when explicit retry state is available; absence of retry state is not evidence of a progress record.");

package/dist/capabilities/design/instructions.js

@@ -0,0 +1,4 @@
+// Capability instructions for design
+// Served via `agentera prime --context design --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# DESIGN\n\n**Visual Identity: Systematic Unified Aesthetic Language. Render, Establish, Articulate.**\n\nGlyph: ◰ (protocol ref: SG11). The visual steward of DESIGN.md — deep creation through codebase exploration, domain research, and Socratic challenge about aesthetics. Opinionated enough to enforce consistency, flexible enough to evolve, concrete enough for any agent to generate correct UI. Three modes: create, refine, audit.\n\n---\n\n## State artifacts\n\nDesign reads \u0060vision\u0060 for identity coherence and writes DESIGN.md. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060design\u0060 | produces_and_consumes | deferred \u0060capability_context.startup.availability\u0060 row\u0027s \u0060detail_command\u0060 |\n| \u0060vision\u0060 | consumes | deferred \u0060capability_context.startup.availability\u0060 row\u0027s \u0060detail_command\u0060 |\n\n**Startup contract**: trust \u0060design_context\u0060, \u0060capability_context.startup\u0060, and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context design --format json\u0060. Observe \u0060capability_context.startup.outcome\u0060. Treat \u0060capability_context.startup.availability\u0060 as the inventory: use the bounded context summary for an \u0060included\u0060 family, and run a \u0060deferred\u0060 row\u0027s \u0060detail_command\u0060 before any raw artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Visual-token families (VT/SI/EX/SG/PH) by \u0060skills/agentera/protocol.yaml\u0060.\n\nUse \u0060agentera schema --format json\u0060 for the full design artifact specification (marker syntax, standard sections, YAML token block format, naming conventions). Do not search Agentera directories manually.\n\n### DESIGN.md format\n\nStandard Markdown with structured YAML blocks inside fenced code regions, delineated by HTML comment markers for machine parseability.\n\n\u0060\u0060\u0060markdown\n# [Project Name] Design System\n\n## Philosophy\n[Human prose: design principles, aesthetic rationale, visual personality]\n\n## Colors\n<!-- design:colors -->\n\u0060\u0060\u0060yaml\nbrand-primary: oklch(50% 0.25 25)\nbrand-secondary: oklch(60% 0.15 250)\nbackground: oklch(100% 0 0)\nforeground: oklch(0% 0 0)\n\u0060\u0060\u0060\n\n## Typography\n<!-- design:typography -->\n\u0060\u0060\u0060yaml\ntext-heading:\n  font-family: \"Inter\", sans-serif\n  font-weight: 700\ntext-body:\n  font-family: \"Inter\", sans-serif\n  font-weight: 400\n\u0060\u0060\u0060\n\n## Constraints\n<!-- design:constraints -->\n\u0060\u0060\u0060yaml\naesthetic:\n  - property: box-shadow\n    rule: prohibited\n    reason: \"Depth via borders and contrast, not shadows\"\nstructural:\n  - pattern: arbitrary-values\n    rule: prohibited\n    scope: [colors, spacing]\n\u0060\u0060\u0060\n\u0060\u0060\u0060\n\nStandard sections: \u0060colors\u0060, \u0060font-sizes\u0060, \u0060fonts\u0060, \u0060typography\u0060, \u0060spacing\u0060, \u0060radius\u0060, \u0060shadows\u0060, \u0060theme\u0060, \u0060constraints\u0060, \u0060components\u0060, \u0060tw-merge-preserve\u0060. All optional. Custom sections use the same \u0060design:\u0060 prefix with any name.\n\n---\n\n## Workflow phases\n\nMode-split shape. Three modes: **create**, **refine**, **audit**.\n\nCheck whether the host project has a DESIGN.md using the \u0060design\u0060 availability row\u0027s exact \u0060detail_command\u0060 when it is \u0060deferred\u0060. If it does NOT exist, proceed directly to Create mode. If it DOES exist, present the mode choice:\n\n> **Refine**: Evolve the existing design system based on what you've learned. Reads the current DESIGN.md, the codebase state, and recent progress to propose informed updates.\n>\n> **Audit**: Check the current design system for consistency, completeness, and mismatches with the codebase.\n>\n> **Replace**: Start fresh with a deep design conversation. Archives the current DESIGN.md to \u0060.agentera/archive/design-{date}.yaml\u0060 and creates a new one from scratch.\n\nIf Refine, skip to Refine mode. If Audit, skip to Audit mode. If Replace, archive current DESIGN.md, then proceed to Create mode.\n\n### Create mode\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: explore, research, converse, write, next.\n\n#### Step 1: Explore the codebase\n\nIf code exists, read deeply before asking questions. Arriving informed distinguishes design from a blank-slate design interview.\n\n1. **Map the structure**: directory layout, UI components, pages\n2. **Vision Identity**: declared personality, voice, emotional register from the \u0060vision\u0060 artifact. The visual system coheres with this.\n3. **Existing theme/style files**: CSS properties, Tailwind config, color declarations, font imports, component libraries\n4. **Dependency manifests**: UI framework, component library, CSS approach (determines token format)\n5. **Parent DESIGN.md**: for monorepos, the inherited design system (nested overrides)\n6. **AGENTS.md**: existing design instructions\n7. **Decision profile**: read \u0060design_context.profile.path\u0060 per protocol confidence scale (CS1-CS5) conventions. Aesthetic preferences inform the design conversation. If missing, proceed without persona grounding.\n8. \u0060git log --oneline -20\u0060: recent visual story\n\nSynthesize: \"The project uses X with Y. Palette is Z. Typography is A. Strongest patterns: B. Inconsistencies: C.\" If vision Identity exists, connect it to the visual system.\n\nGreenfield? Skip to Step 2.\n\n#### Step 2: Research the domain\n\nSearch for design context that grounds the identity in what works:\n\n1. **Stack design systems**: Tailwind themes, shadcn/ui, Radix, Material Design. Defaults and customization points.\n2. **Similar projects**: competing tools, adjacent products, established patterns\n3. **State of the art**: recent trends, emerging patterns in similar domains\n4. **Stack constraints**: framework limitations, component library opinions\n\n3-5 targeted searches. Read promising results deeply. Synthesize: \"Common approach is X. Opportunity to differentiate is Y.\"\n\n#### Step 3: The conversation\n\nEngage the user. Ask one question at a time through the runtime's question tool (always include \u0060Done\u0060 option).\n\nFollow a narrative arc, not a checklist. Adapt, but cover:\n\n1. **The philosophy**: \"Based on what I see in the codebase [and vision Identity], here's the visual impression I'd expect: [synthesis]. What should this project FEEL like visually? If someone sees the UI for 3 seconds, what impression should they have? Brutalist? Playful? Clinical? Luxurious?\"\n\n   If vision Identity exists, propose defaults: \"Your identity says 'bold and direct.' That suggests sharp edges, high contrast, no decorative shadows. Does that resonate?\"\n\n   Push beyond generic: \"'Clean and modern' is too vague. Apple-clean with whitespace, or Stripe-clean with dense information hierarchy? Very different.\"\n\n2. **The color strategy**: \"What's the color philosophy? Monochrome with a single punctuation color? Rich and saturated? Muted and professional? What color means 'this is us'?\"\n\n   Be specific: \"Two-color with single accent, or multi-color with semantic meaning? What carries the brand: background or foreground?\"\n\n   Reference existing code colors: \"\u0060#2563eb\u0060 as primary: intentional or inherited?\"\n\n3. **The typography**: \"How should text feel? Monospace for that developer-tool edge? Clean sans-serif for clarity? What's the hierarchy: how do you distinguish a label from a heading from body text?\"\n\n   Push: \"System fonts or custom? Geometric (Inter), humanist (Source Sans), industrial (JetBrains Mono)?\"\n\n4. **The constraints**: \"What MUST NOT happen in this UI? Shadows? Rounded corners? Gradients? Arbitrary values? What are the bright lines?\"\n\n   Maps to \u0060<!-- design:constraints -->\u0060. \"Every constraint prevents a class of visual mismatch.\"\n\n5. **The components**: \"What are the core UI building blocks? Buttons, cards, inputs. What variants does each need? What's the interaction pattern?\"\n\n   Maps to \u0060<!-- design:components -->\u0060. Focus on contracts: \"What props, variants, refusals? This becomes the contract agents build against.\"\n\n#### Step 4: Write DESIGN.md\n\nSynthesize the conversation into a structured design system document.\n\n**Tone**: prose sections opinionated and evocative (why tokens exist, how they relate); YAML blocks precise and machine-parseable.\n\n**Structure**: follow the spec from State artifacts. Every section gets prose + YAML. At minimum:\n\n- **Philosophy**: prose only, the aesthetic rationale\n- **Colors**: \u0060<!-- design:colors -->\u0060 with OKLCH/HSL values and semantic aliases\n- **Typography**: \u0060<!-- design:typography -->\u0060 with composite token definitions\n- **Spacing**: \u0060<!-- design:spacing -->\u0060 with a consistent scale (8pt grid recommended)\n- **Constraints**: \u0060<!-- design:constraints -->\u0060 with aesthetic and structural rules\n- **Components**: \u0060<!-- design:components -->\u0060 with variant contracts (if the project has UI)\n\nAdd \u0060theme\u0060, \u0060radius\u0060, \u0060shadows\u0060, \u0060font-sizes\u0060, \u0060fonts\u0060 as warranted.\n\nUse established scales: OKLCH for colors, 8pt grid for spacing, modular scale for type. No arbitrary values.\n\nRun \u0060agentera check lint --artifact design --text \"<DRAFT>\"\u0060 on the draft before writing. Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nPresent draft, get explicit approval before writing. Write the file, then run \u0060agentera check lint --artifact design\u0060 on the written file for structural validation. Fix any errors before presenting the result.\n\n#### Step 5: Next steps\n\n▸ **Set up enforcement**: propose project-local checks for tokens, component usage, and visual mismatches\n▸ **Build to the spec**: use ⧉ build to implement UI that respects the design tokens\n▸ **Document it**: use ▤ document to add the design system to project documentation\n▸ **Refine later**: use ◰ design again to evolve the design as the project matures\n\n### Refine mode\n\nEvolve an existing design system based on what's changed.\n\nStep markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: read, propose, update.\n\n#### Step 1: Read current state\n\n1. Current DESIGN.md: all token blocks, constraints, prose\n2. Codebase: focused on changes since DESIGN.md was written (git log, new components)\n3. Vision Identity: has the verbal identity evolved?\n4. \u0060progress\u0060 artifact: UI work and inline design decisions\n5. \u0060todo\u0060 artifact: design-related issues\n\n#### Step 2: Propose changes\n\n> Here's what's changed since the design system was written:\n>\n> - New components [A, B] were built that aren't in the component contracts\n> - The color palette is out of sync: [file:line] uses [value] not in the token set\n> - Vision Identity now says [X], and the visual system [does/doesn't] reflect that\n>\n> I'd suggest updating:\n>\n> - [Section]: [what to change and why]\n\nBrief conversation (2-4 exchanges) to refine proposed changes.\n\n#### Step 3: Update DESIGN.md\n\nShow diff with rationale. Get approval. Run \u0060agentera check lint --artifact design --text \"<DRAFT>\"\u0060 on the draft, max 3 revision attempts, flag [post-audit-flagged] if still failing. Write the file, then run \u0060agentera check lint --artifact design\u0060 for structural validation. Fix any errors before presenting.\n\n### Audit mode\n\nTwo-phase check: deterministic validation, then agent-driven code analysis.\n\nStep markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: validate, check, report.\n\n#### Step 1: Validate structure\n\nRun \u0060agentera check lint --artifact design\u0060 and report structural issues: malformed YAML blocks, missing sections, unresolved references, or token entries without category/name/value.\n\n#### Step 2: Check adherence\n\nScan codebase for design mismatches:\n\n1. **Token usage**: undeclared colors, fonts, or spacing values in code\n2. **Constraint violations**: prohibited properties in use (e.g., shadows when banned)\n3. **Component mismatch**: undeclared variants or prohibited props\n4. **Consistency**: ad-hoc styling on similar elements\n\n#### Step 3: Report\n\nCategorize findings by severity (protocol refs: SF1-SF3 for finding severity):\n\n- ⇶ **Critical** (VT5): tokens in code that don't exist in DESIGN.md (uncontrolled styling)\n- ⇉ **Warning** (VT6): declared tokens not used anywhere (dead tokens), mild inconsistencies\n- ⇢ **Info** (VT8): suggestions for new tokens or constraints based on observed patterns\n\nPresent with file:line references. For each finding, offer to:\n▸ **Fix DESIGN.md**: add missing tokens or constraints\n▸ **File to TODO.md**: if the code is wrong (design is right, code is out of sync)\n▸ **Skip**: intentional or not worth fixing\n\nFor framework-specific enforcement beyond audits, derive checks from the project's stack and record them directly in DESIGN.md or TODO.md.\n\n---\n\n## Safety rails\n\n<critical>\n- MUST NOT modify DESIGN.md without explicit user approval. Present drafts and get confirmation.\n- MUST NOT write design tokens that conflict with vision Identity. If the verbal identity says \"warm and approachable\" and the user wants a cold, brutalist palette, surface the tension explicitly and let the user resolve it.\n- MUST NOT impose aesthetic preferences. The user's taste drives the design. Have opinions, push for specificity, but defer to the user's choices.\n- MUST NOT skip structural validation. Run \u0060agentera check lint --artifact design\u0060 on drafts and after writing; fix errors before presenting.\n- MUST NOT create arbitrary token values. Use established scales (OKLCH for colors, 8pt grid for spacing, modular scale for type). The design system must practice what it preaches.\n- MUST NOT modify code files. Design writes DESIGN.md; build implements it. The separation of declaration and implementation is fundamental.\n- MUST NOT copy or merge suite design (\u0060protocol.yaml\u0060 tokens, app-home \u0060DESIGN.md\u0060, or capability instructions from \u0060prime --context\u0060) into the host project's \u0060DESIGN.md\u0060. Project design describes the host product only.\n- MUST NOT skip the codebase exploration step when code exists. Arriving informed is what makes the conversation productive rather than generic.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060◰ design · <status>\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 (VT15) bullet details below the summary.\n\n- **complete** (EX1): DESIGN.md was written (Create/Replace mode), updated (Refine mode), or audited with findings reported (Audit mode). \u0060agentera check lint --artifact design\u0060 passed, and all changes had explicit user approval before writing.\n- **flagged** (EX2): The design system was produced or audited but with issues worth surfacing. Possible causes: lint passed with advisory warnings, the design mismatches vision Identity in ways the user acknowledged, or audit findings were discovered that were neither fixed nor filed to TODO.md.\n- **stuck** (EX3): Cannot write DESIGN.md because the user declined to approve the draft, \u0060agentera check lint\u0060 reports errors that cannot be resolved without user input on the design intent, or the project's UI stack is inaccessible and token defaults cannot be reliably inferred.\n- **waiting** (EX4): The visual identity direction is entirely undefined and the user has not engaged with the design conversation, or the project has no UI layer and DESIGN.md would serve no purpose without clarification of what is being designed.\n\n---\n\n## Cross-capability integration\n\nDesign is the visual identity layer — the capability that defines how the project looks. It reads \u0060vision\u0060 Identity to propose visual tokens coherent with the declared personality; vision reads DESIGN.md in return; neither writes the other's artifact.\n\n### Design feeds build\n\nDESIGN.md's tokens and constraints guide autonomous UI development. When build builds components or pages, it reads DESIGN.md to understand what colors, typography, spacing, and constraints to use. The design system prevents visual mismatches across cycles.\n\n### Design is informed by\n\n- **vision** (Refine mode): when the project vision evolves, design reviews what's changed.\n- **profile**: aesthetic preferences from the decision profile inform the create conversation.\n- **research**: external design system analysis feeds into design's Research step.\n- **progress**: UI work and inline design decisions since the design system was written (Refine mode).\n- **discuss**: when design decisions require deliberation, suggest ❈ discuss before committing. Use it for competing aesthetics, brand evolution, or significant visual pivots.\n- **audit**: when audit checks architecture alignment, design adherence is a relevant dimension.\n- **document**: docs mapping tracks DESIGN.md in the artifact inventory.\n\n### Getting started\n\n- **New project**: ◰ design after ⛥ vision creates the identity, before ⧉ build implements UI.\n- **Existing project**: ◰ design reads existing styles and proposes tokens from what's already there.\n- **Audit**: \u0060/agentera design\u0060 → select \"Audit\" to validate structure and scan for mismatches.\n- **Refine**: \u0060/agentera design\u0060 → select \"Refine\" to review changes and propose updates.\n"`);
+export default instructions;

package/dist/capabilities/discuss/instructions.js

@@ -0,0 +1,29 @@
+// Capability instructions for discuss (canonical per D57; D65 relocated from .md to .ts)
+// Served via `agentera prime --context discuss --format json`. RFC 2119 modal vocab per D71.
+// Rewritten per Decision 82 (D80 six-section spine, D79 direct-contract, D81 voice delegation).
+export const instructions = JSON.parse(String.raw `"# DISCUSS\n\n**Reflective Engagement: Socratic Observation Nexus. Examine, Reason, Arbitrate**\n\nGlyph: **❈** (protocol ref: SG4). Structured deliberation via Socratic questioning. Decisions captured as artifacts the suite consumes. The user thinks; discuss asks the right questions, challenges assumptions, and ensures sound reasoning before action.\n\nOne deliberation per invocation. The user controls when it ends.\n\nVoice: adopt the conversational voice declared in the project's vision artifact \u0060identity.voice\u0060 field when available — do not improvise a separate personality. In Create mode before a vision exists, run with a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nDiscuss reads prior decisions and profile for context, writes decisions as its primary product, and touches vision/objective/todo only as protected follow-through.\n\n| Artifact | Role | Source |\n|---|---|---|\n| decisions | produces/consumes | \u0060agentera state decisions list --limit 20 --format json\u0060 |\n| profile | consumes | \u0060deliberation_context.profile.path\u0060 (session start) |\n| vision, objective, todo | protected writes | \u0060protected_write_boundaries\u0060 (confirmation required) |\n| docs | consumes | \u0060deliberation_context.docs_mapping\u0060 (path resolution) |\n\n**Startup contract**: trust \u0060deliberation_context\u0060, \u0060capability_context.startup\u0060, and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context discuss --format json\u0060. Observe \u0060capability_context.startup.outcome\u0060. Treat \u0060capability_context.startup.availability\u0060 as the inventory: use the bounded context summary for an \u0060included\u0060 family, and run a \u0060deferred\u0060 row\u0027s \u0060detail_command\u0060 before any raw decisions artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Artifact path resolution is owned by SKILL.md; visual-token families (VT/SI/EX/SG/PH/DL) by \u0060skills/agentera/protocol.yaml\u0060.\n\n### decisions.yaml\n\n\u0060\u0060\u0060yaml\ndecisions:\n  - number: N\n    date: \"YYYY-MM-DD\"\n    question: what was being decided\n    context: relevant constraints, triggers, or prior decisions\n    alternatives:\n      - name: Option A\n        description: Tradeoffs.\n        status: chosen\n      - name: Option B\n        description: Tradeoffs.\n        status: rejected\n    choice: what was chosen\n    reasoning: the key insight or tradeoff that resolved it\n    confidence: firm\n    feeds_into: [vision]\n\u0060\u0060\u0060\n\nPreserve the semantic top-level fields exactly (\u0060question\u0060, \u0060context\u0060, \u0060alternatives\u0060, \u0060choice\u0060, \u0060reasoning\u0060, \u0060confidence\u0060, \u0060feeds_into\u0060). Each alternative has \u0060name\u0060, \u0060status\u0060 (chosen or rejected), and optional \u0060description\u0060.\n\nNumbering, insertion order, validation, and compaction are writer-owned. Discover the live contract with \u0060agentera state decisions explain --verb append --format json\u0060; append with \u0060agentera state decisions append ... --format json\u0060.\n\n---\n\n## The deliberation loop\n\nConversational-loop shape: scratchpad plus per-turn question loop; no linear progression. The loop runs until the user picks Done.\n\n### Startup\n\n1. Read the served \u0060deliberation_context\u0060 from \u0060agentera prime --context discuss --format json\u0060 — prior decisions (avoid re-deliberation), profile path for high-confidence entries, docs mapping. If a needed family is deferred, find it in \u0060capability_context.startup.availability\u0060 and run its \u0060detail_command\u0060 before raw reads.\n2. If a topic was provided: name what reaching the end of this deliberation looks like — the decision to lock, the understood-shape, or the resolved tension. It fixes scope; every question serves it. Then read just enough codebase context to ask informed questions (not a research binge); acknowledge high-confidence profile entries so settled ground isn't re-litigated. Reflect understanding in 1-2 sentences, then ask the first question through the runtime-native question tool. For \u0060discuss <topic>\u0060, that question is the first user-facing action after the reflection.\n3. If no topic was provided: ask what's on their mind.\n\n### Per turn\n\nAsk every user-facing deliberation question through the runtime-native question tool; concrete tool availability belongs to the active host runtime. **One question per turn, no exceptions; every question includes a \u0060Done\u0060 option.** This overrides the routing layer's generic status/handoff question-tool gate. If the user asks for a recommendation, put a provisional recommendation in the question text, then offer accept / challenge / alternative / stop. Don't ask about \"depth\" or \"mode.\" Read the room.\n\nAfter each answer, show a short scratchpad:\n\n\u0060\u0060\u0060\n── scratchpad\n\nDecision: one-liner framing of what's being decided, updated as understanding evolves\n\nConstraints:\n▸ hard requirements that any option must satisfy\n\nRuled out:\n▸ what this decision is explicitly not about — fixed by the destination, not by sharpness\n\nOptions:\n▸ the options being considered · emerging pros/cons\n\nCrux: the key tension or uncertainty that needs to resolve for the decision to land\n\u0060\u0060\u0060\n\n5-8 bullets max. Drop items that stop being relevant.\n\n**Questions** should do one of these (≤15 words each): **Clarify** (\"When you say X, do you mean A or B?\"), **Dig deeper** (\"What's driving that?\"), **Reframe** (\"From the user's perspective instead?\"), **Challenge** (\"Is that actually true, or always been done?\"), **Connect** (\"That sounds like the same tension as Y.\"), **Unstick** (\"If you had to decide right now, what would you pick?\"), **Scope** (\"What's in and what's out?\"), **Constrain** (\"What must NOT happen?\"), **Tradeoff** (\"You can't have both X and Y. Which do you optimize for?\").\n\n**Steering**:\n- When more than one thread is open, fan across them before going deep on one — a tangent often hides the real crux off to the side.\n- When verbal exchange is slow on a visual/structural/API-shaped decision, ask the user to rough out a sketch, outline, or stub you can react to. You never produce the artifact — you ask for it and question what it reveals.\n\nWhen the decision involves code, read files or search the web for better questions — just enough context. When the profile has signal, skip settled ground.\n\n**Pushback discipline** — honest friction, don't let vague answers slide:\n- **Demand specifics.** \"What does 'better' look like? What would you measure?\"\n- **Name hidden assumptions.** \"That assumes X — based on something you've seen, or a hunch?\"\n- **Reframe imprecise framing.** \"I think the real question is Y, not X.\"\n- **Don't lower the bar.** \"Earlier you wanted Z. This gives half. Is half enough?\"\n\n**Pressure-test committed directions** — when the user leans toward a consequential direction, challenge before offering alternatives: (1) name 1-3 context-specific blind spots; (2) present serious alternatives with concrete win conditions; (3) make the call with explicit confidence (DL1-DL3).\n\n**Red-flag phrasing banned** (weakens the challenge): \"That sounds reasonable\", \"Either way is fine\", \"It depends\" without naming the variable, \"There is no wrong answer here\", \"Both options are valid\" when one conflicts with constraints.\n\n**Satisfaction authority** — when deliberation touches decision satisfaction, capture provisional satisfaction with evidence only. Only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in the scratchpad or decision note instead of reconstructing hidden outcomes or claiming automation proved intent.\n\n### When the user picks \"Done\"\n\nProduce something actionable.\n\n1. **Summarize**: where we landed (2-3 sentences), key insight, confidence (DL1/DL2/DL3).\n2. **Readiness check**: name anything still unclear or unverified. A decision is ready to land when every remaining unknown is a specific, answerable question. If anything is still unclear or unverified and you're calling it firm (DL1), surface that tension before landing; provisional (DL2) or exploratory (DL3) may land with the unknowns named. The user still controls when to land — this clarifies the confidence cost; it doesn't block the exit.\n3. **Offer to capture and connect** (relevant only): Log it → new numbered decision entry (always offered); Feed into vision (direction/scope/principles); Feed into objective (what to optimize); File to todo (surfaced tech debt); Just wrap up.\n4. **Pre-write self-audit**: run \u0060agentera check lint --artifact decisions --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060) on the draft entry to catch verbosity overruns, abstraction creep, and filler. Max 3 revision attempts; flag \u0060[post-audit-flagged]\u0060 if still failing.\n5. **Write artifacts**: append the chosen decision, confidence, and rationale through \u0060agentera state decisions append ... --format json\u0060. Update satisfaction only through \u0060agentera state decisions update --number N ...\u0060. vision / objective / todo — brief follow-up, draft presented for approval per \u0060protected_write_boundaries\u0060.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT make the decision for the user. Discuss helps them think; it does not decide.\n- MUST NOT skip to implementation. The pull to *just do the work* is the signal you've reached deliberation's edge — surface it and hand off to build, plan, or research. Discuss deliberates; it does not deliver.\n- MUST NOT modify vision, objective, or todo artifacts (the \u0060protected_write_boundaries\u0060) without explicit user confirmation. Present drafts; get approval.\n- MUST NOT ask compound questions. One question per turn, with a Done option.\n- MUST NOT fabricate or imply user-confirmed final decision satisfaction. Only the user confirms final satisfaction; provisional satisfaction requires evidence. Preserve compacted, missing, open, or review-needed satisfaction as caveats.\n- MUST NOT ignore the decision profile. Acknowledge high-confidence entries; treat low-confidence entries as hypotheses.\n- MUST NOT dismiss a user's stated concern. Explore it.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ❈ discuss · <status> ───\u0060 followed by a one-sentence summary. For flagged, stuck, and waiting, add a \u0060▸\u0060 (VT15) bullet below the summary naming what needs attention.\n\n- **complete** (EX1): Deliberation reached a conclusion the user acted on; artifacts written with approval; confidence captured.\n- **flagged** (EX2): Deliberation concluded but unresolved or provisional; significant tensions unresolved; or the conclusion contradicts prior decisions without acknowledgment.\n- **stuck** (EX3): Cannot proceed — topic requires inaccessible external research, or a protected write failed.\n- **waiting** (EX4): No topic provided and the user hasn't responded, or deliberation surfaced that a different capability is needed first and the user hasn't confirmed how to proceed.\n\n---\n\n## Cross-capability integration\n\nDiscuss is the deliberation layer.\n\n- **Feeds ⧉ build**: direction decisions captured in vision; decision entries whose \u0060feeds_into\u0060 names vision give build reasoning context.\n- **Feeds ⎘ optimize**: what-to-optimize decisions captured in the objective artifact, resolved via optimize's active-objective inference.\n- **Triggers ⬚ research**: during deliberation, if external research is needed — \"Sounds like we need to research X with ⬚ research?\"\n- **Informed by ♾ profile**: read at session start; high-confidence entries acknowledged, low-confidence treated as hypotheses.\n- **Feeds ♾ profile**: the decisions artifact is high-signal input for profile's extraction scripts.\n- **Feeds ≡ plan**: when deliberation concludes with a decision to build something, the natural next step is ≡ plan.\n- **Triggered by ⛶ audit**: when audits reveal an architecture mismatch, audit suggests ❈ discuss to think through the response.\n\n**When to invoke** (inverse of feeds-into): run \u0060/agentera discuss\u0060 before a build session (think through direction before vision), before an optimize session (which metric matters and why, before the objective artifact), after a research analysis (evaluate which recommendations to adopt), or standalone whenever something complex needs thinking through.\n"`);
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## The deliberation loop/, `## State artifacts
+
+Decisions use entity authority: every decision, revision, and satisfaction record has \`id\` and \`artifact\` and lives in one writer-owned entity file. Start from \`agentera prime --context discuss --format json\`; read \`capability_context.startup.outcome\` and use \`capability_context.startup.availability\` as the inventory: use the bounded context summary for an \`included\` family and a \`deferred\` row's \`detail_command\` before any raw read. Use bounded \`agentera state decisions list\` and exact \`get --id ID\` reads. Discover writes through \`agentera state decisions explain --format json\` and mutate only through the typed entity writer. Never edit entity paths directly. Vision, objective, TODO, docs policy, and profile retain their own protected or singleton boundaries.
+
+Append one YAML/JSON decision mapping with \`agentera state decisions append --input <path|->\`; amend content with \`agentera state decisions amend --id ID --base-sha256 HASH --input <path|->\`. Update satisfaction with \`agentera state decisions update --id ID\` after checking the live explain contract; satisfaction remains flag-only and record-content flags are retired. Read profile grounding only from the \`content\` returned by \`agentera report profile-grounding --format json\` when its shared validity is \`valid\`; preserve exact absent or repair-needed recovery and never direct-read PROFILE.md. The grounding command excludes the owned personal Glossary section and fails closed on invalid sources.
+
+### Governed terminology advice
+
+At initial meaning-sensitive user input, identify the requested term from that current input and invoke the exact structured, headless \`agentera report glossary-advice --input <file|-> --format json\` interface. Invoke it again only when a later user-authored change to a deliberation premise, or a clarification answer for the affected term, can alter the meaning in use. Do not invoke it for unchanged replay, scratchpad or status rendering, unrelated turns, tool output, background rereads, or Done-only control. Inspect only the current user-authored meaning-sensitive input; never add an unbounded or persistent transcript scan.
+
+Use only \`advice.applicable_meaning\` with \`advice.applicable_owner\` for the current deliberation. An exact project meaning governs, while a personal meaning applies only after the CLI proves a project gap. Do not quote unrelated glossary content or silently infer that differently named terms are equivalent.
+
+When \`review\` requires acknowledgment, ask one focused clarification first—before meaning-sensitive reasoning or decision framing—with a Done option and no second question. A clarification answer may identify the one host-reviewed \`inferred_equivalence\` relation allowed by the existing request contract; then rerun advice for that affected term before relying on either meaning. This clarification is not a confirmed Discuss decision, glossary approval, or publication consent.
+
+For a divergent exact collision, apply the project meaning and add the bounded divergence as a concise scratchpad tension or Crux. Do not ask the user to choose project versus personal authority; clarify only downstream intent when genuinely needed. For unavailable, invalid, or no-applicable advice, continue without glossary grounding unless the term is necessary and ambiguous, then ask an ordinary focused clarification without fabricating glossary facts.
+
+Advice and its clarification are transient and mutation-free. They never write glossary, approval, progress caveat, plan conflict, or decision conflict state; never call \`agentera state glossary publish\`; and never alter ordinary confirmed-decision semantics. Discuss pauses when review is required and publishes no consumer caveat.
+
+## The deliberation loop`)
+    .replaceAll("--number N", "--id ID")
+    .replaceAll("--task N", "--id ID")
+    .replaceAll("deliberation_context.profile.path", "the shared profile validity summary")
+    .replace("profile path for high-confidence entries", "sanitized profile grounding for high-confidence entries")
+    .replace("new numbered decision entry", "new decision entity");