@guyghost/swarm-dao-core 0.4.0 → 0.6.0

package/dist/delivery/ship-audit.js

@@ -0,0 +1,155 @@
+// ============================================================
+// Swarm DAO Core — Ship Audit Delivery (fingerprint + gate)
+// ============================================================
+// Deterministic glue between the ship handler and the audit machine:
+// - computeShipFingerprint: canonical sha256 over the proposal's
+//   decision-relevant content (anything that changes the decision must
+//   re-challenge — INV-2). Uses node:crypto; lives OUTSIDE src/models to
+//   respect the models purity contract.
+// - evaluateShipAuditChallenge: the gate the handler consults before
+//   ShipProposalUseCase. Never mutates proposal state. The challenge binds
+//   the decision fingerprint AND the ship options (cascade): changing the
+//   operation between challenge and confirmation re-issues the challenge.
+//   The read→transition→write sequence runs under an exclusive cross-process
+//   claim, so one confirmation can never authorize concurrent ships (INV-6).
+import { createHash } from "node:crypto";
+import { computeShipAuditDecision, createShipAuditActor, } from "../models/ship-audit.machine.js";
+/** Canonical decision-relevant content of a proposal. Pure data selection. */
+function decisionContent(proposal) {
+    const control = proposal.riskZone ? { riskZone: proposal.riskZone } : {};
+    return {
+        id: proposal.id,
+        title: proposal.title,
+        type: proposal.type,
+        description: proposal.description,
+        status: proposal.status,
+        dependsOn: proposal.dependsOn ?? [],
+        votes: (proposal.votes ?? []).map((vote) => ({
+            agentId: vote.agentId,
+            position: vote.position,
+            weight: vote.weight,
+        })),
+        control,
+    };
+}
+/** sha256 over canonical JSON of the decision content. Deterministic. */
+export function computeShipFingerprint(proposal) {
+    const canonical = JSON.stringify(decisionContent(proposal), null, 0);
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * The challenge binds the decision fingerprint plus the operation options:
+ * a single-proposal command must not morph into a cascading execution (or
+ * the reverse) under one confirmation.
+ */
+function requestSignature(fingerprint, options) {
+    return createHash("sha256")
+        .update(`${fingerprint}|${JSON.stringify({ cascade: options.cascade === true })}`)
+        .digest("hex");
+}
+const REQUEST = (fingerprint) => ({ type: "SHIP_REQUESTED", source: "system", fingerprint, occurredAt: "1970-01-01T00:00:00.000Z" });
+function snapshotOf(actor, count) {
+    const snap = actor.getSnapshot();
+    return {
+        proposalId: snap.context.proposalId,
+        state: String(snap.value),
+        status: String(snap.status),
+        context: { ...snap.context, challengeCount: count },
+    };
+}
+/**
+ * Rebuild a live actor from a persisted snapshot by deterministic replay:
+ * challenged = one request with the persisted signature, confirmed = two.
+ * Terminal contexts never block later cycles (review: cycle semantics) — a
+ * new ship call on a still-controlled proposal starts fresh.
+ */
+function hydrate(persisted, proposalId) {
+    const count = persisted?.context.challengeCount ?? 0;
+    const actor = createShipAuditActor(proposalId);
+    const fingerprint = persisted?.context.fingerprint ?? null;
+    if (!fingerprint)
+        return { actor, count };
+    if (persisted?.state === "challenged") {
+        actor.send(REQUEST(fingerprint));
+    }
+    else if (persisted?.state === "confirmed") {
+        actor.send(REQUEST(fingerprint));
+        actor.send(REQUEST(fingerprint));
+    }
+    return { actor, count };
+}
+/**
+ * The deterministic ship gate (models/ship-audit.md):
+ * - challenge disabled → proceed unchanged (N1)
+ * - force → human bypass, recorded (N6) — the record MUST persist, so a
+ *   store failure blocks the bypass instead of silently losing evidence
+ * - first call → AUDIT_REQUIRED, nothing executes (N2)
+ * - unchanged call (same decision AND same options) → proceed, with a
+ *   `consume()` that spends the single confirmation (N3, INV-6)
+ * - changed decision or options → re-challenge (N4)
+ * - concurrent gate for the same proposal → blocked while claimed (INV-6)
+ */
+export async function evaluateShipAuditChallenge(input) {
+    if (!input.challengeEnabled)
+        return { proceed: true };
+    const claim = await input.store.claim(input.proposal.id);
+    if (!claim.acquired) {
+        return {
+            proceed: false,
+            message: `A concurrent ship gate for proposal #${input.proposal.id} is in flight; retry once it completes.`,
+        };
+    }
+    try {
+        return await gate(input);
+    }
+    finally {
+        await claim.release();
+    }
+}
+async function gate(input) {
+    const persisted = await input.store.load(input.proposal.id).catch(() => null);
+    const { actor, count } = hydrate(persisted, input.proposal.id);
+    if (input.force) {
+        actor.send({
+            type: "FORCE_OVERRIDE",
+            source: "human",
+            reason: input.forceReason ?? "operator force",
+            occurredAt: input.occurredAt ?? new Date().toISOString(),
+        });
+        // A bypass is only as good as its record: fail closed if it cannot persist.
+        await input.store.save(snapshotOf(actor, count));
+        return { proceed: true, note: "ship audit bypassed by force (recorded)" };
+    }
+    const fingerprint = computeShipFingerprint(input.proposal);
+    const signature = requestSignature(fingerprint, input.options ?? {});
+    actor.send({ ...REQUEST(signature), occurredAt: input.occurredAt ?? new Date().toISOString() });
+    // The historical challenge counter lives here (the actor's own counter is
+    // per-cycle): a new challenge — first of a cycle or a re-challenge after a
+    // changed decision or options — increments it; a confirmation does not.
+    const stateAfterRequest = String(actor.getSnapshot().value);
+    const liveCount = stateAfterRequest === "challenged" ? count + 1 : count;
+    await input.store.save(snapshotOf(actor, liveCount));
+    const decision = computeShipAuditDecision(actor.getSnapshot().value);
+    if (decision === "PROCEED") {
+        return {
+            proceed: true,
+            consume: async () => {
+                actor.send({ type: "SHIP_CONSUMED", source: "system", occurredAt: new Date().toISOString() });
+                await input.store.save(snapshotOf(actor, liveCount));
+            },
+        };
+    }
+    if (decision === "BLOCKED") {
+        const state = String(actor.getSnapshot().value);
+        return { proceed: false, message: `Ship audit context is ${state}; start a new audit cycle.` };
+    }
+    return {
+        proceed: false,
+        message: [
+            `AUDIT_REQUIRED — ship challenge ${liveCount} for proposal #${input.proposal.id}.`,
+            "The first call never executes. Re-read the proposal and the control results, then call dao_ship again unchanged — the same decision AND the same options (cascade).",
+            `Fingerprint: ${fingerprint.slice(0, 12)}… — any change to the decision (votes, gates, scope) or the options re-issues the challenge.`,
+        ].join("\n"),
+    };
+}
+//# sourceMappingURL=ship-audit.js.map

package/dist/delivery/ship-audit.js.map

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

package/dist/domain/dry-run.d.ts

@@ -0,0 +1,3 @@
+import type { DryRunResult, Proposal } from "../types/index.js";
+export declare function analyzeProposalDryRun(proposal: Proposal): DryRunResult;
+//# sourceMappingURL=dry-run.d.ts.map

package/dist/domain/dry-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../../src/domain/dry-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAWhE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAetE"}

package/dist/domain/dry-run.js

@@ -0,0 +1,28 @@
+import { PROPOSAL_TYPE } from "../types/index.js";
+const DURATION_BY_TYPE = {
+    [PROPOSAL_TYPE.PRODUCT_FEATURE]: "3-7 days",
+    [PROPOSAL_TYPE.SECURITY_CHANGE]: "1-2 weeks",
+    [PROPOSAL_TYPE.TECHNICAL_CHANGE]: "2-5 days",
+    [PROPOSAL_TYPE.RELEASE_CHANGE]: "1-3 days",
+    [PROPOSAL_TYPE.GOVERNANCE_CHANGE]: "1-2 days",
+};
+export function analyzeProposalDryRun(proposal) {
+    const filesAffected = [...(proposal.affectedPaths ?? [])];
+    const risks = [];
+    if (proposal.type === PROPOSAL_TYPE.SECURITY_CHANGE)
+        risks.push("Security-sensitive changes require extra review");
+    if (proposal.riskZone === "red")
+        risks.push("Red-zone proposal: high risk detected");
+    if (!proposal.acceptanceCriteria?.length)
+        risks.push("No acceptance criteria defined");
+    const estimatedDuration = DURATION_BY_TYPE[proposal.type];
+    return {
+        proposalId: proposal.id,
+        preview: `This proposal would modify ${filesAffected.length || "unknown number of"} files and requires ${estimatedDuration}.`,
+        filesAffected,
+        risks,
+        estimatedDuration,
+        canProceed: !risks.some((risk) => risk.includes("high risk") || risk.includes("Security-sensitive")),
+    };
+}
+//# sourceMappingURL=dry-run.js.map

package/dist/domain/dry-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run.js","sourceRoot":"","sources":["../../src/domain/dry-run.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,gBAAgB,GAAqC;IACzD,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,UAAU;IAC3C,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,WAAW;IAC5C,CAAC,aAAa,CAAC,gBAAgB,CAAC,EAAE,UAAU;IAC5C,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,UAAU;IAC1C,CAAC,aAAa,CAAC,iBAAiB,CAAC,EAAE,UAAU;CAC9C,CAAC;AAEF,MAAM,UAAU,qBAAqB,CAAC,QAAkB;IACtD,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa,CAAC,eAAe;QAAE,KAAK,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;IACnH,IAAI,QAAQ,CAAC,QAAQ,KAAK,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACrF,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IACvF,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1D,OAAO;QACL,UAAU,EAAE,QAAQ,CAAC,EAAE;QACvB,OAAO,EAAE,8BAA8B,aAAa,CAAC,MAAM,IAAI,mBAAmB,uBAAuB,iBAAiB,GAAG;QAC7H,aAAa;QACb,KAAK;QACL,iBAAiB;QACjB,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;KACrG,CAAC;AACJ,CAAC"}

package/dist/domain/index.d.ts

@@ -0,0 +1,6 @@
+export * from "../delivery/dependencies.js";
+export * from "../governance/lifecycle.js";
+export * from "../governance/scoring.js";
+export * from "../governance/voting.js";
+export * from "./dry-run.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/domain/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAEA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC"}

package/dist/domain/index.js

@@ -0,0 +1,7 @@
+// Pure domain surface. These modules contain calculations and rules only.
+export * from "../delivery/dependencies.js";
+export * from "../governance/lifecycle.js";
+export * from "../governance/scoring.js";
+export * from "../governance/voting.js";
+export * from "./dry-run.js";
+//# sourceMappingURL=index.js.map

package/dist/domain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC"}

package/dist/governance/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/governance/agents.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD,eAAO,MAAM,cAAc,EAAE,QAAQ,EAgSpC,CAAC;AA4DF,gFAAgF;AAChF,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AA8BD,wBAAsB,gCAAgC,CACpD,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,QAAQ,EAAmB,GACtC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAuCrB;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAuB9G;AAED,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAKtE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAM5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAMvD;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE/D"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/governance/agents.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD,eAAO,MAAM,cAAc,EAAE,QAAQ,EAoJpC,CAAC;AAgEF,gFAAgF;AAChF,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AA+DD,wBAAsB,gCAAgC,CACpD,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,QAAQ,EAAmB,GACtC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAiDrB;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA2B9G;AA2BD,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAStE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAM5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAMvD;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE/D"}

package/dist/governance/agents.js

@@ -4,6 +4,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { filterEnabledAgents } from "../config.js";
+import { AGENT_CHARTER, composeSystemPrompt } from "./charter.js";
 export const DEFAULT_AGENT_MODEL = "z.ai/GLM-5.1";
 export const DEFAULT_AGENTS = [
     {
@@ -20,27 +21,7 @@ For each proposal, analyze:
 1. Strategic alignment — does this fit the product vision?
 2. Objectives — which OKRs or goals does this advance?
 3. Hypotheses — what assumptions underlie this proposal?
-4. Opportunity cost — what are we NOT doing if we do this?
-
-Output format:
-## Analysis
-[Your strategic analysis]
-
-## Vote
-for | against | abstain
-
-## Reasoning
-[Why you voted this way]
-
-## Composite Score Inputs (0-10)
-- userImpact: [0-10]
-- businessImpact: [0-10]
-- effort: [0-10] (lower = less effort)
-- securityRisk: [0-10] (lower = less risk)
-- confidence: [0-10]
-
-## Risk Score (1-10)
-[Overall risk assessment]`,
+4. Opportunity cost — what are we NOT doing if we do this?`,
         riskLevel: "medium",
         councils: [{ council: "product-council", role: "lead" }],
         enabled: true,
@@ -59,27 +40,7 @@ For each proposal, research:
 1. Market context — trends, market size, growth
 2. Competition — what are competitors doing?
 3. User signals — feedback, requests, pain points
-4. Data availability — do we have evidence to support this?
-
-Output format:
-## Analysis
-[Your research findings]
-
-## Vote
-for | against | abstain
-
-## Reasoning
-[Why you voted this way]
-
-## Composite Score Inputs (0-10)
-- userImpact: [0-10]
-- businessImpact: [0-10]
-- effort: [0-10]
-- securityRisk: [0-10]
-- confidence: [0-10]
-
-## Risk Score (1-10)
-[Overall risk assessment]`,
+4. Data availability — do we have evidence to support this?`,
         riskLevel: "low",
         councils: [{ council: "product-council", role: "member" }],
         enabled: true,
@@ -99,27 +60,7 @@ For each proposal, analyze:
 2. Architecture impact — how does this affect system design?
 3. Tradeoffs — what are the key technical tradeoffs?
 4. Technical debt — will this create or reduce debt?
-5. Scalability — will this scale with our growth?
-
-Output format:
-## Analysis
-[Your technical analysis]
-
-## Vote
-for | against | abstain
-
-## Reasoning
-[Why you voted this way]
-
-## Composite Score Inputs (0-10)
-- userImpact: [0-10]
-- businessImpact: [0-10]
-- effort: [0-10]
-- securityRisk: [0-10]
-- confidence: [0-10]
-
-## Risk Score (1-10)
-[Overall risk assessment]`,
+5. Scalability — will this scale with our growth?`,
         riskLevel: "medium",
         councils: [{ council: "delivery-council", role: "lead" }],
         enabled: true,
@@ -139,27 +80,7 @@ For each proposal, scrutinize:
 2. Edge cases — what scenarios aren't covered?
 3. Guardrails — are sufficient protections in place?
 4. Downside — what's the worst-case outcome?
-5. Unknown unknowns — what haven't we considered?
-
-Output format:
-## Analysis
-[Your risk analysis and objections]
-
-## Vote
-for | against | abstain
-
-## Reasoning
-[Why you voted this way]
-
-## Composite Score Inputs (0-10)
-- userImpact: [0-10]
-- businessImpact: [0-10]
-- effort: [0-10]
-- securityRisk: [0-10]
-- confidence: [0-10]
-
-## Risk Score (1-10)
-[Overall risk assessment]`,
+5. Unknown unknowns — what haven't we considered?`,
         riskLevel: "high",
         councils: [
             { council: "security-council", role: "lead" },
@@ -182,27 +103,7 @@ For each proposal, score:
 2. Cost — implementation effort, maintenance burden
 3. Risk — probability of failure, downside exposure
 4. Roadmap fit — does this belong in our current sequence?
-5. Urgency — how time-sensitive is this?
-
-Output format:
-## Analysis
-[Your prioritization analysis]
-
-## Vote
-for | against | abstain
-
-## Reasoning
-[Why you voted this way]
-
-## Composite Score Inputs (0-10)
-- userImpact: [0-10]
-- businessImpact: [0-10]
-- effort: [0-10]
-- securityRisk: [0-10]
-- confidence: [0-10]
-
-## Risk Score (1-10)
-[Overall risk assessment]`,
+5. Urgency — how time-sensitive is this?`,
         riskLevel: "low",
         councils: [{ council: "product-council", role: "member" }],
         enabled: true,
@@ -222,27 +123,7 @@ For each proposal, assess:
 2. Completeness — what's missing from the spec?
 3. Testability — can we write acceptance criteria?
 4. User stories — can this be broken into stories?
-5. Edge cases — are boundary conditions defined?
-
-Output format:
-## Analysis
-[Your specification analysis]
-
-## Vote
-for | against | abstain
-
-## Reasoning
-[Why you voted this way]
-
-## Composite Score Inputs (0-10)
-- userImpact: [0-10]
-- businessImpact: [0-10]
-- effort: [0-10]
-- securityRisk: [0-10]
-- confidence: [0-10]
-
-## Risk Score (1-10)
-[Overall risk assessment]`,
+5. Edge cases — are boundary conditions defined?`,
         riskLevel: "low",
         councils: [{ council: "product-council", role: "advisor" }],
         enabled: true,
@@ -262,27 +143,7 @@ For each proposal, plan:
 2. Task breakdown — what are the key tasks?
 3. Effort estimate — rough timeline and resources
 4. CI/CD impact — how does this affect pipelines?
-5. Dependencies — what must happen first?
-
-Output format:
-## Analysis
-[Your delivery analysis]
-
-## Vote
-for | against | abstain
-
-## Reasoning
-[Why you voted this way]
-
-## Composite Score Inputs (0-10)
-- userImpact: [0-10]
-- businessImpact: [0-10]
-- effort: [0-10]
-- securityRisk: [0-10]
-- confidence: [0-10]
-
-## Risk Score (1-10)
-[Overall risk assessment]`,
+5. Dependencies — what must happen first?`,
         riskLevel: "medium",
         councils: [{ council: "delivery-council", role: "member" }],
         enabled: true,
@@ -291,7 +152,7 @@ for | against | abstain
 function parseAgentFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match?.[1])
-        return {};
+        return { body: content.trim() || undefined };
     const parsed = {};
     for (const line of match[1].split("\n")) {
         const field = line.match(/^([A-Za-z0-9_-]+):\s*(.+)$/);
@@ -321,6 +182,11 @@ function parseAgentFrontmatter(content) {
                 break;
         }
     }
+    // The markdown body is the per-agent project layer (## Project
+    // Instructions); frontmatter fields still override agent metadata.
+    const body = content.slice(match[0].length).trim();
+    if (body)
+        parsed.body = body;
     return parsed;
 }
 const agentDefinitionCache = new Map();
@@ -334,23 +200,48 @@ export function __resetAgentDefinitionCache() {
 function withDefaultModel(agents) {
     return agents.map((agent) => ({ ...agent, model: agent.model ?? DEFAULT_AGENT_MODEL }));
 }
-async function readAndMergeMarkdownAgents(absDir, daoEntries, baseAgents) {
+async function readAndMergeMarkdownAgents(absDir, daoEntries, baseAgents, base) {
     const markdownAgents = new Map();
-    for (const entry of daoEntries) {
+    const parsedEntries = await Promise.all(daoEntries.map(async (entry) => {
         const content = await fs.readFile(path.join(absDir, entry), "utf-8");
-        const frontmatter = parseAgentFrontmatter(content);
+        return parseAgentFrontmatter(content);
+    }));
+    for (const frontmatter of parsedEntries) {
         if (frontmatter.id) {
             markdownAgents.set(frontmatter.id, frontmatter);
         }
     }
-    return baseAgents.map((agent) => {
+    // The per-project charter layer applies to every agent (swarm-forge
+    // local-* convention: layers add to the shared law, never replace it).
+    // The closest directory wins: .dao/agents beats the repo's agents/.
+    let projectCharter = base.projectCharter;
+    if (projectCharter === null) {
+        try {
+            const charter = await fs.readFile(path.join(absDir, "charter.md"), "utf-8");
+            if (charter.trim())
+                projectCharter = charter.trim();
+        }
+        catch {
+            // No project charter here — keep looking in the remaining dirs.
+        }
+    }
+    const agents = baseAgents.map((agent) => {
         const override = markdownAgents.get(agent.id);
+        if (!override)
+            return agent;
+        // The markdown body is the agent's role definition — it REPLACES the
+        // default role prompt (consistent with the frontmatter, which already
+        // overrides name/role/model/weight). The shared charter is never
+        // replaceable: composition always prepends it.
+        const { body: _body, ...fields } = override;
         return {
             ...agent,
-            ...(override ?? {}),
-            model: override?.model ?? agent.model ?? DEFAULT_AGENT_MODEL,
+            ...fields,
+            ...(override.body ? { systemPrompt: override.body } : {}),
+            model: override.model ?? agent.model ?? DEFAULT_AGENT_MODEL,
         };
     });
+    return { agents, projectCharter };
 }
 export async function loadAgentDefinitionsFromMarkdown(agentsDir, baseAgents = DEFAULT_AGENTS) {
     const absDir = path.resolve(agentsDir);
@@ -360,15 +251,21 @@ export async function loadAgentDefinitionsFromMarkdown(agentsDir, baseAgents = D
         entries = await fs.readdir(absDir);
     }
     catch {
-        // Directory missing/unreadable: behave exactly as before and do NOT cache.
-        return withDefaultModel(baseAgents);
+        // Directory missing/unreadable: do NOT cache, but still compose — a
+        // missing directory must yield the same charter-backed prompts as an
+        // existing empty one.
+        return withComposedPrompts(withDefaultModel(baseAgents), null);
     }
     const daoEntries = entries.filter((entry) => entry.startsWith("dao-") && entry.endsWith(".md"));
-    // Build a signature over the dao-*.md entries and their stat metadata so the
-    // cache invalidates whenever an agent file is added, removed, or modified.
+    // Build a signature over the dao-*.md entries (and charter.md, which is
+    // also a cached layer) and their stat metadata so the cache invalidates
+    // whenever a file is added, removed, or modified.
     let signature;
     try {
-        const parts = await Promise.all(daoEntries.map(async (entry) => {
+        const signatureEntries = [...daoEntries];
+        if (entries.includes("charter.md"))
+            signatureEntries.push("charter.md");
+        const parts = await Promise.all(signatureEntries.map(async (entry) => {
             const fileStat = await fs.stat(path.join(absDir, entry));
             return `${entry}:${fileStat.mtimeMs}:${fileStat.size}`;
         }));
@@ -383,7 +280,12 @@ export async function loadAgentDefinitionsFromMarkdown(agentsDir, baseAgents = D
         // Cache hit: return the merged result without re-reading files.
         return cached.result;
     }
-    const result = await readAndMergeMarkdownAgents(absDir, daoEntries, baseAgents);
+    const layers = await readAndMergeMarkdownAgents(absDir, daoEntries, withDefaultModel(baseAgents), {
+        agents: withDefaultModel(baseAgents),
+        projectCharter: null,
+    });
+    // Composition happens exactly once, at the exit.
+    const result = withComposedPrompts(layers.agents, layers.projectCharter);
     agentDefinitionCache.set(cacheKey, { signature, result });
     return result;
 }
@@ -393,24 +295,60 @@ export async function loadAgentDefinitions(daoRoot, projectConfig) {
         path.join(daoRoot, "..", "agents"),
         path.join(daoRoot, "..", "..", "agents"),
     ];
-    let agents = initializeAgents();
+    // Layer collection over the candidate dirs, closest first. Composition
+    // happens exactly once, after collection, so the shared charter is never
+    // duplicated across the chain.
+    let layers = {
+        agents: withDefaultModel(DEFAULT_AGENTS),
+        projectCharter: null,
+    };
     for (const agentsDir of candidateDirs) {
-        const loaded = await loadAgentDefinitionsFromMarkdown(agentsDir, agents);
-        const hasMarkdownOverrides = loaded.some((agent, index) => agent.model !== agents[index]?.model ||
-            agent.name !== agents[index]?.name ||
-            agent.role !== agents[index]?.role);
-        if (hasMarkdownOverrides) {
-            agents = loaded;
+        const merged = await readMarkdownLayers(agentsDir, layers);
+        // Closest layer wins: the first candidate directory holding agent
+        // definitions or a charter fully shadows the further ones, so project
+        // overrides (.dao/agents) are never replaced by repo defaults (agents/).
+        if (merged) {
+            layers = merged;
             break;
         }
     }
+    const agents = withComposedPrompts(layers.agents, layers.projectCharter);
     return projectConfig ? filterEnabledAgents(agents, projectConfig) : agents;
 }
+/** Apply the charter + project layers to role-level agents (composition exit). */
+function withComposedPrompts(agents, projectCharter) {
+    // Per-agent: mixed lists (some prompts already composed, some not) compose
+    // exactly the ones that need it — composeSystemPrompt is idempotent.
+    return agents.map((agent) => ({
+        ...agent,
+        systemPrompt: composeSystemPrompt(agent.systemPrompt, { projectCharter }),
+    }));
+}
+/** Read and merge one directory's markdown layers; null when it has none. */
+async function readMarkdownLayers(agentsDir, base) {
+    const absDir = path.resolve(agentsDir);
+    let entries;
+    try {
+        entries = await fs.readdir(absDir);
+    }
+    catch {
+        return null;
+    }
+    const daoEntries = entries.filter((entry) => entry.startsWith("dao-") && entry.endsWith(".md"));
+    const hasCharter = entries.includes("charter.md");
+    if (daoEntries.length === 0 && !hasCharter)
+        return null;
+    return readAndMergeMarkdownAgents(absDir, daoEntries, base.agents, base);
+}
 export function initializeAgents(customAgents) {
     if (customAgents && customAgents.length > 0) {
         return customAgents;
     }
-    return DEFAULT_AGENTS.map((a) => ({ ...a, model: a.model ?? DEFAULT_AGENT_MODEL }));
+    return DEFAULT_AGENTS.map((a) => ({
+        ...a,
+        systemPrompt: composeSystemPrompt(a.systemPrompt),
+        model: a.model ?? DEFAULT_AGENT_MODEL,
+    }));
 }
 export function formatAgentsTable(agents) {
     let table = "| Agent | Weight | Role |\n|-------|--------|------|\n";
@@ -427,6 +365,6 @@ export function formatAgentCard(agent) {
 - **Description:** ${agent.description}`;
 }
 export function getDefaultAgentPrompts() {
-    return Object.fromEntries(DEFAULT_AGENTS.map((a) => [a.id, a.systemPrompt]));
+    return Object.fromEntries(DEFAULT_AGENTS.map((a) => [a.id, composeSystemPrompt(a.systemPrompt)]));
 }
 //# sourceMappingURL=agents.js.map