@agenticprimitives/devkit 0.0.0-alpha.1

package/dist/rules/web-no-direct-mcp.js

@@ -0,0 +1,37 @@
+import { isCommentLine } from '../fs.js';
+const FORBIDDEN = [
+    { re: /(?<!\/a2a)\/mcp\/native/, what: 'native MCP tool ingress (/mcp/native) — go through /a2a/*' },
+    { re: /(?<!\/a2a)\/mcp(["'`])/, what: 'OAuth MCP tool ingress (POST /mcp) — go through /a2a/*' },
+    { re: /(?<!\/a2a)\/tools\//, what: 'raw MCP tool path (/tools/...) — go through /a2a/tools/... instead' },
+];
+const SKIP = new Set(['dist', 'node_modules', 'coverage', 'test', 'tests', '__tests__', '.next']);
+export const webNoDirectMcp = {
+    id: 'web-no-direct-mcp',
+    spec: 'ADR-0044',
+    twin: 'check:no-direct-mcp-in-web',
+    describe: 'browser apps reach MCP data only via the same-origin /a2a/* surface',
+    run(ctx, cfg) {
+        const findings = [];
+        let scanned = 0;
+        for (const app of cfg.browserApps) {
+            const src = `${app}/src`;
+            if (!ctx.exists(src))
+                continue;
+            for (const file of ctx.walk(src, { skipDirs: SKIP, file: (n) => /\.(ts|tsx)$/.test(n) && !n.endsWith('.d.ts') })) {
+                const text = ctx.read(ctx.rel(file));
+                if (cfg.allowMarkers.some((m) => text.includes(m)))
+                    continue;
+                scanned += 1;
+                text.split('\n').forEach((line, i) => {
+                    if (isCommentLine(line))
+                        return;
+                    for (const { re, what } of FORBIDDEN)
+                        if (re.test(line))
+                            findings.push({ file: ctx.rel(file), line: i + 1, message: what, tag: 'direct-mcp' });
+                });
+            }
+        }
+        return { summary: findings.length ? `${findings.length} direct-MCP reference(s) in browser code` : `${scanned} browser files reach MCP only via /a2a/*`, findings };
+    },
+};
+//# sourceMappingURL=web-no-direct-mcp.js.map

package/dist/rules/web-no-direct-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-no-direct-mcp.js","sourceRoot":"","sources":["../../src/rules/web-no-direct-mcp.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAgD;IAC7D,EAAE,EAAE,EAAE,yBAAyB,EAAE,IAAI,EAAE,2DAA2D,EAAE;IACpG,EAAE,EAAE,EAAE,wBAAwB,EAAE,IAAI,EAAE,wDAAwD,EAAE;IAChG,EAAE,EAAE,EAAE,qBAAqB,EAAE,IAAI,EAAE,oEAAoE,EAAE;CAC1G,CAAC;AACF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;AAElG,MAAM,CAAC,MAAM,cAAc,GAA+C;IACxE,EAAE,EAAE,mBAAmB;IACvB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,4BAA4B;IAClC,QAAQ,EAAE,qEAAqE;IAC/E,GAAG,CAAC,GAAG,EAAE,GAAG;QACV,MAAM,QAAQ,GAAkB,EAAE,CAAC;QACnC,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC/B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;gBACjH,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;gBACrC,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;oBAAE,SAAS;gBAC7D,OAAO,IAAI,CAAC,CAAC;gBACb,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;oBACnC,IAAI,aAAa,CAAC,IAAI,CAAC;wBAAE,OAAO;oBAChC,KAAK,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,SAAS;wBAAE,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;4BAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;gBACjJ,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,0CAA0C,CAAC,CAAC,CAAC,GAAG,OAAO,0CAA0C,EAAE,QAAQ,EAAE,CAAC;IACtK,CAAC;CACF,CAAC"}

package/dist/rules-projection.d.ts

@@ -0,0 +1,58 @@
+export interface RuleSidecarEntry {
+    description: string;
+    globs?: string[];
+    alwaysApply?: boolean;
+    /** Project to `.cursor/rules/<name>.mdc`. Default false: a rule without a Cursor mirror today stays without one. */
+    cursor?: boolean;
+}
+export type RulesSidecar = Record<string, RuleSidecarEntry>;
+export interface RuleSource {
+    name: string;
+    body: string;
+    digest: string;
+}
+export interface RulesCorpus {
+    sourceDir: string;
+    rules: RuleSource[];
+    sidecar: RulesSidecar;
+}
+/** The corpus bundled with this package: copies of the Ring-0 agent-rules, synced at build (`scripts/sync-rules.mjs`). */
+export declare const BUNDLED_RULES_DIR: string;
+export declare function ruleDigest(body: string): string;
+/** The hard-rules block of a root guide, as one rule body — the second source id (399 §3.4). */
+export declare function extractHardRules(guideText: string): string | null;
+export declare function loadRulesCorpus(opts: {
+    root: string;
+    source?: string;
+    sidecar?: string;
+    hardRulesFrom?: string;
+}): RulesCorpus;
+export declare function rulesLockEntries(corpus: RulesCorpus): Record<string, string>;
+/** The Cursor rule file: frontmatter from the sidecar, blank line, body verbatim. */
+export declare function renderMdc(entry: RuleSidecarEntry, body: string): string;
+export declare const RULES_BLOCK_START = "<!-- ap:rules -->";
+export declare const RULES_BLOCK_END = "<!-- /ap:rules -->";
+/** The managed block for AGENTS.md / CLAUDE.md: the table of rules with their digests. */
+export declare function renderRulesBlock(corpus: RulesCorpus, opts: {
+    sourceLabel: string;
+}): string;
+export declare function replaceRulesBlock(text: string, block: string): string | null;
+export interface ProjectionResult {
+    path: string;
+    status: 'unchanged' | 'would-write' | 'written' | 'unmanaged' | 'absent' | 'skipped';
+    reason?: string;
+}
+export interface ProjectOptions {
+    root: string;
+    corpus: RulesCorpus;
+    cursorRules?: string;
+    agentsMd?: string;
+    claudeMd?: string;
+    write: boolean;
+    /** Project every rule to Cursor, not only those the sidecar marks `cursor: true`. */
+    all?: boolean;
+    /** Create `.cursor/rules` when it does not exist (a fresh product repo). Default: only project into an existing dir. */
+    createCursorDir?: boolean;
+}
+export declare function projectRules(o: ProjectOptions): ProjectionResult[];
+//# sourceMappingURL=rules-projection.d.ts.map

package/dist/rules-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-projection.d.ts","sourceRoot":"","sources":["../src/rules-projection.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oHAAoH;IACpH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AACD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE5D,MAAM,WAAW,UAAU;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC1E,MAAM,WAAW,WAAW;IAAG,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE;AAE9F,0HAA0H;AAC1H,eAAO,MAAM,iBAAiB,QAA+D,CAAC;AAE9F,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAkB9H;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5E;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAgB3F;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,qFAAqF;IACrF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,wHAAwH;IACxH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,cAAc,GAAG,gBAAgB,EAAE,CA+BlE"}

package/dist/rules-projection.js

@@ -0,0 +1,135 @@
+// RULES PROJECTION — spec 399 §3.4 / spec 398 §10.5 / ADR-0063 §8. ONE source (the agent-rules corpus: a directory
+// of `<name>.md`, optionally plus the hard-rules block of a root CLAUDE.md), projected to three targets:
+//
+//   .cursor/rules/<name>.mdc   frontmatter from the SIDECAR (description · globs · alwaysApply) + a blank line + the
+//                              body byte-for-byte — regenerating a repo's existing files is a no-op (the §3.4 gate)
+//   AGENTS.md / CLAUDE.md      ONLY the block between `<!-- ap:rules -->` and `<!-- /ap:rules -->`; a file without
+//                              the markers is UNMANAGED and never rewritten (Ring 0's own CLAUDE.md is hand-written)
+//
+// A product repo may not restate a rule in its own words: it carries the projection and the digest.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The corpus bundled with this package: copies of the Ring-0 agent-rules, synced at build (`scripts/sync-rules.mjs`). */
+export const BUNDLED_RULES_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'rules');
+export function ruleDigest(body) {
+    return `sha256:${createHash('sha256').update(body.replace(/\r\n/g, '\n')).digest('hex')}`;
+}
+/** The hard-rules block of a root guide, as one rule body — the second source id (399 §3.4). */
+export function extractHardRules(guideText) {
+    const m = /^## Hard rules\n([\s\S]*?)(?=^## )/m.exec(guideText);
+    return m ? `# Hard rules (root CLAUDE.md)\n\n${m[1].trim()}\n` : null;
+}
+export function loadRulesCorpus(opts) {
+    const sourceDir = opts.source ? join(opts.root, opts.source) : BUNDLED_RULES_DIR;
+    const rules = [];
+    if (existsSync(sourceDir)) {
+        for (const f of readdirSync(sourceDir).sort()) {
+            if (!f.endsWith('.md') || f === 'README.md')
+                continue;
+            const body = readFileSync(join(sourceDir, f), 'utf8');
+            rules.push({ name: f.slice(0, -3), body, digest: ruleDigest(body) });
+        }
+    }
+    // Ring 0: the hard rules live in the root guide, not in the corpus dir; the bundled copy already carries them.
+    if (opts.source && opts.hardRulesFrom && existsSync(join(opts.root, opts.hardRulesFrom)) && !rules.some((r) => r.name === 'hard-rules')) {
+        const body = extractHardRules(readFileSync(join(opts.root, opts.hardRulesFrom), 'utf8'));
+        if (body)
+            rules.push({ name: 'hard-rules', body, digest: ruleDigest(body) });
+    }
+    const sidecarPath = opts.sidecar ? join(opts.root, opts.sidecar) : existsSync(join(sourceDir, 'sidecar.json')) ? join(sourceDir, 'sidecar.json') : join(BUNDLED_RULES_DIR, 'sidecar.json');
+    const sidecar = existsSync(sidecarPath) ? JSON.parse(readFileSync(sidecarPath, 'utf8')) : {};
+    return { sourceDir, rules, sidecar };
+}
+export function rulesLockEntries(corpus) {
+    return Object.fromEntries(corpus.rules.map((r) => [r.name, r.digest]));
+}
+/** The Cursor rule file: frontmatter from the sidecar, blank line, body verbatim. */
+export function renderMdc(entry, body) {
+    const fm = [`description: ${entry.description}`];
+    if (entry.globs?.length)
+        fm.push('globs:', ...entry.globs.map((g) => `  - "${g}"`));
+    fm.push(`alwaysApply: ${entry.alwaysApply ?? true}`);
+    return `---\n${fm.join('\n')}\n---\n\n${body}`;
+}
+export const RULES_BLOCK_START = '<!-- ap:rules -->';
+export const RULES_BLOCK_END = '<!-- /ap:rules -->';
+/** The managed block for AGENTS.md / CLAUDE.md: the table of rules with their digests. */
+export function renderRulesBlock(corpus, opts) {
+    const rows = corpus.rules.map((r) => {
+        const s = corpus.sidecar[r.name];
+        const cursor = s?.cursor ? ` · \`.cursor/rules/${r.name}.mdc\`` : '';
+        return `| ${s?.description ?? r.name} | \`${opts.sourceLabel}/${r.name}.md\`${cursor} | \`${r.digest.slice(0, 19)}…\` |`;
+    });
+    return [
+        RULES_BLOCK_START,
+        '<!-- Generated by `ap doctor --rules --write` from the pinned rules source; edit the source, never this block (ADR-0063 §8). -->',
+        '',
+        '| Rule | Source | Digest |',
+        '| --- | --- | --- |',
+        ...rows,
+        '',
+        RULES_BLOCK_END,
+    ].join('\n');
+}
+export function replaceRulesBlock(text, block) {
+    const a = text.indexOf(RULES_BLOCK_START);
+    const b = text.indexOf(RULES_BLOCK_END);
+    if (a === -1 || b === -1 || b < a)
+        return null;
+    return text.slice(0, a) + block + text.slice(b + RULES_BLOCK_END.length);
+}
+export function projectRules(o) {
+    const out = [];
+    const emit = (path, next) => {
+        const abs = join(o.root, path);
+        const current = existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+        if (current === next) {
+            out.push({ path, status: 'unchanged' });
+            return;
+        }
+        if (!o.write) {
+            out.push({ path, status: 'would-write', reason: current === null ? 'missing' : 'content' });
+            return;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, next);
+        out.push({ path, status: 'written' });
+    };
+    const cursorDir = o.cursorRules ?? '.cursor/rules';
+    const cursorExists = existsSync(join(o.root, cursorDir));
+    if (cursorExists || o.createCursorDir) {
+        for (const r of o.corpus.rules) {
+            const s = o.corpus.sidecar[r.name];
+            if (!s) {
+                out.push({ path: `${cursorDir}/${r.name}.mdc`, status: 'skipped', reason: 'no sidecar entry' });
+                continue;
+            }
+            if (!s.cursor && !o.all) {
+                out.push({ path: `${cursorDir}/${r.name}.mdc`, status: 'skipped', reason: 'sidecar: cursor=false' });
+                continue;
+            }
+            emit(`${cursorDir}/${r.name}.mdc`, renderMdc(s, r.body));
+        }
+    }
+    else
+        out.push({ path: cursorDir, status: 'absent' });
+    const sourceLabel = o.corpus.sourceDir.startsWith(o.root) ? o.corpus.sourceDir.slice(o.root.length + 1) : '@agenticprimitives/devkit/rules';
+    const block = renderRulesBlock(o.corpus, { sourceLabel });
+    for (const path of [o.agentsMd ?? 'AGENTS.md', o.claudeMd ?? 'CLAUDE.md']) {
+        const abs = join(o.root, path);
+        if (!existsSync(abs)) {
+            out.push({ path, status: 'absent' });
+            continue;
+        }
+        const next = replaceRulesBlock(readFileSync(abs, 'utf8'), block);
+        if (next === null) {
+            out.push({ path, status: 'unmanaged', reason: 'no <!-- ap:rules --> block' });
+            continue;
+        }
+        emit(path, next);
+    }
+    return out;
+}
+//# sourceMappingURL=rules-projection.js.map

package/dist/rules-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-projection.js","sourceRoot":"","sources":["../src/rules-projection.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,yGAAyG;AACzG,EAAE;AACF,qHAAqH;AACrH,oHAAoH;AACpH,mHAAmH;AACnH,qHAAqH;AACrH,EAAE;AACF,oGAAoG;AACpG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAczC,0HAA0H;AAC1H,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAE9F,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC5F,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,MAAM,CAAC,GAAG,qCAAqC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAChE,OAAO,CAAC,CAAC,CAAC,CAAC,oCAAoC,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAiF;IAC/G,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC;IACjF,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC9C,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,WAAW;gBAAE,SAAS;YACtD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IACD,+GAA+G;IAC/G,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,aAAa,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;QACxI,MAAM,IAAI,GAAG,gBAAgB,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACzF,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;IAC3L,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/G,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IAClD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,SAAS,CAAC,KAAuB,EAAE,IAAY;IAC7D,MAAM,EAAE,GAAG,CAAC,gBAAgB,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM;QAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACpF,EAAE,CAAC,IAAI,CAAC,gBAAgB,KAAK,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC,CAAC;IACrD,OAAO,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEpD,0FAA0F;AAC1F,MAAM,UAAU,gBAAgB,CAAC,MAAmB,EAAE,IAA6B;IACjF,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAClC,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,OAAO,KAAK,CAAC,EAAE,WAAW,IAAI,CAAC,CAAC,IAAI,QAAQ,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,QAAQ,MAAM,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC;IAC3H,CAAC,CAAC,CAAC;IACH,OAAO;QACL,iBAAiB;QACjB,kIAAkI;QAClI,EAAE;QACF,4BAA4B;QAC5B,qBAAqB;QACrB,GAAG,IAAI;QACP,EAAE;QACF,eAAe;KAChB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,KAAa;IAC3D,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAC3E,CAAC;AAqBD,MAAM,UAAU,YAAY,CAAC,CAAiB;IAC5C,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,IAAY,EAAQ,EAAE;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACnE,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QAC1E,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;YAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QACtH,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACzB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACxC,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,CAAC,CAAC,WAAW,IAAI,eAAe,CAAC;IACnD,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;IACzD,IAAI,YAAY,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAC/B,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,CAAC,EAAE,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,IAAI,CAAC,CAAC,IAAI,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBAAC,SAAS;YAAC,CAAC;YACtH,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,IAAI,CAAC,CAAC,IAAI,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC,CAAC;gBAAC,SAAS;YAAC,CAAC;YAC5I,IAAI,CAAC,GAAG,SAAS,IAAI,CAAC,CAAC,IAAI,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;;QAAM,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvD,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,iCAAiC,CAAC;IAC5I,MAAM,KAAK,GAAG,gBAAgB,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IAC1D,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC,CAAC,QAAQ,IAAI,WAAW,CAAC,EAAE,CAAC;QAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACzE,MAAM,IAAI,GAAG,iBAAiB,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC;QACjE,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QAC/G,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/upgrade.d.ts

@@ -0,0 +1,37 @@
+export type UpgradeMode = 'canary' | 'pin';
+export interface UpgradeChange {
+    manifest: string;
+    field: string;
+    dep: string;
+    from: string;
+    to: string;
+}
+export interface UpgradePlan {
+    mode: UpgradeMode;
+    /** The dist-tag or version asked for. */
+    target: string;
+    changes: UpgradeChange[];
+    /** dep → resolved version. */
+    resolved: Record<string, string>;
+    unresolved: string[];
+    /** Canary only: true when every resolved canary carries the same commit suffix. */
+    coherent: boolean;
+    notes: string[];
+}
+/** dist-tags for a package, as `npm view <pkg> dist-tags --json` returns them. */
+export type DistTagResolver = (pkg: string) => Promise<Record<string, string>>;
+export declare const npmDistTags: DistTagResolver;
+export declare function planUpgrade(opts: {
+    root: string;
+    mode: UpgradeMode;
+    pin?: string;
+    scope?: string;
+    resolveDistTags?: DistTagResolver;
+    includeWorkspaceAliases?: boolean;
+}): Promise<UpgradePlan>;
+/** Apply a plan: rewrite the manifests and the lock's `packages` set. Returns the manifests touched. */
+export declare function applyUpgradePlan(root: string, plan: UpgradePlan, opts?: {
+    devkitVersion?: string;
+}): string[];
+export declare function formatUpgradePlan(plan: UpgradePlan): string;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,KAAK,CAAC;AAC3C,MAAM,WAAW,aAAa;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACzG,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mFAAmF;IACnF,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE/E,eAAO,MAAM,WAAW,EAAE,eAOzB,CAAC;AAIF,wBAAsB,WAAW,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAAC,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAwCrM;AAED,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,EAAE,CAoBjH;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAM3D"}

package/dist/upgrade.js

@@ -0,0 +1,116 @@
+// `ap upgrade --canary | --pin <version|tag>` — spec 399 §3.1 / §5.2. Rewrites every @agenticprimitives/* dependency
+// across the workspace manifests to ONE coherent exact set, then the caller installs, dedupes and runs doctor.
+// Planning is pure over an injected resolver; applying writes manifests and the lock. Stopping for review when a
+// contract's authority or effects change (398 §10.3) is NOT implemented in W0 — see CLAUDE.md, it is named there.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { DevkitError, ERROR_CODES } from './errors.js';
+import { readLock, writeLock } from './lock.js';
+import { workspaceManifests } from './workspace.js';
+export const npmDistTags = async (pkg) => {
+    try {
+        const out = execFileSync('npm', ['view', pkg, 'dist-tags', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        return JSON.parse(out);
+    }
+    catch (e) {
+        throw new DevkitError(ERROR_CODES.E_RESOLVE, `npm view ${pkg} dist-tags failed: ${e.message.split('\n')[0]}`);
+    }
+};
+const EXACT = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+export async function planUpgrade(opts) {
+    const scope = opts.scope ?? '@agenticprimitives/';
+    const target = opts.mode === 'canary' ? 'canary' : opts.pin ?? '';
+    if (opts.mode === 'pin' && !target)
+        throw new DevkitError(ERROR_CODES.E_USAGE, '--pin needs a version or a dist-tag (latest | alpha | canary | 1.2.3)');
+    const resolve = opts.resolveDistTags ?? npmDistTags;
+    const manifests = workspaceManifests(opts.root);
+    const deps = new Set();
+    for (const m of manifests)
+        for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+            for (const [dep, spec] of Object.entries(m.json[field] ?? {})) {
+                if (!dep.startsWith(scope))
+                    continue;
+                if (spec.startsWith('workspace:') && !opts.includeWorkspaceAliases)
+                    continue;
+                deps.add(dep);
+            }
+        }
+    const resolved = {};
+    const unresolved = [];
+    const notes = [];
+    for (const dep of [...deps].sort()) {
+        if (opts.mode === 'pin' && EXACT.test(target)) {
+            resolved[dep] = target;
+            continue;
+        }
+        let tags;
+        try {
+            tags = await resolve(dep);
+        }
+        catch (e) {
+            unresolved.push(`${dep}: ${e.message}`);
+            continue;
+        }
+        const v = tags[target];
+        if (!v) {
+            unresolved.push(`${dep}: no "${target}" dist-tag (has ${Object.keys(tags).join(', ') || 'none'})`);
+            continue;
+        }
+        resolved[dep] = v;
+    }
+    const changes = [];
+    for (const m of manifests)
+        for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+            for (const [dep, spec] of Object.entries(m.json[field] ?? {})) {
+                const to = resolved[dep];
+                if (!to || spec === to)
+                    continue;
+                changes.push({ manifest: m.file, field, dep, from: spec, to });
+            }
+        }
+    let coherent = true;
+    if (opts.mode === 'canary') {
+        const shas = new Set(Object.values(resolved).map((v) => /-canary-([0-9a-f]+)$/.exec(v)?.[1] ?? v));
+        coherent = shas.size <= 1;
+        if (!coherent)
+            notes.push(`the newest canaries span ${shas.size} commits (a canary publishes only what changed) — the set is newest-per-package, review before trusting it as one commit`);
+    }
+    return { mode: opts.mode, target, changes, resolved, unresolved, coherent, notes };
+}
+/** Apply a plan: rewrite the manifests and the lock's `packages` set. Returns the manifests touched. */
+export function applyUpgradePlan(root, plan, opts = {}) {
+    const touched = new Set();
+    const byManifest = new Map();
+    for (const c of plan.changes)
+        byManifest.set(c.manifest, [...(byManifest.get(c.manifest) ?? []), c]);
+    for (const [file, changes] of byManifest) {
+        const abs = join(root, file);
+        const json = JSON.parse(readFileSync(abs, 'utf8'));
+        for (const c of changes) {
+            const section = json[c.field];
+            if (section && section[c.dep] !== undefined)
+                section[c.dep] = c.to;
+        }
+        writeFileSync(abs, `${JSON.stringify(json, null, 2)}\n`);
+        touched.add(file);
+    }
+    const lock = readLock(root) ?? { lockVersion: 1, packages: {}, rules: {} };
+    lock.packages = { ...lock.packages, ...plan.resolved };
+    if (opts.devkitVersion)
+        lock.devkit = opts.devkitVersion;
+    writeLock(root, lock);
+    touched.add('agentic.lock.json');
+    return [...touched];
+}
+export function formatUpgradePlan(plan) {
+    const lines = [`ap upgrade --${plan.mode}${plan.mode === 'pin' ? ` ${plan.target}` : ''} · ${plan.changes.length} change(s), ${Object.keys(plan.resolved).length} package(s) resolved${plan.mode === 'canary' ? `, ${plan.coherent ? 'coherent' : 'NOT coherent'}` : ''}`];
+    for (const c of plan.changes)
+        lines.push(`  ${c.manifest}  ${c.field}.${c.dep}: ${c.from} → ${c.to}`);
+    for (const u of plan.unresolved)
+        lines.push(`  ✗ unresolved ${u}`);
+    for (const n of plan.notes)
+        lines.push(`  ⚠ ${n}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/upgrade.js.map

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

package/dist/workspace.d.ts

@@ -0,0 +1,18 @@
+export interface PackageManifest {
+    name?: string;
+    version?: string;
+    private?: boolean;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    [k: string]: unknown;
+}
+export interface WorkspaceManifest {
+    file: string;
+    dir: string;
+    json: PackageManifest;
+}
+export declare function workspaceGlobs(root: string): string[];
+export declare function workspaceManifests(root: string): WorkspaceManifest[];
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE;AAEvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAerD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAoBpE"}

package/dist/workspace.js

@@ -0,0 +1,56 @@
+// Workspace manifest discovery — the root package.json plus every package.json a `pnpm-workspace.yaml` glob names.
+// Deliberately small: the globs pnpm uses here are `dir/*` and literal dirs, and a full glob engine is not a
+// dependency this package wants.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { rel } from './fs.js';
+export function workspaceGlobs(root) {
+    const p = join(root, 'pnpm-workspace.yaml');
+    if (!existsSync(p))
+        return [];
+    const out = [];
+    let inPackages = false;
+    for (const raw of readFileSync(p, 'utf8').split('\n')) {
+        const line = raw.replace(/#.*$/, '').trimEnd();
+        if (/^packages:\s*$/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages) {
+            const m = /^\s+-\s*['"]?([^'"]+?)['"]?\s*$/.exec(line);
+            if (m?.[1])
+                out.push(m[1]);
+            else if (line.trim() && !line.startsWith(' '))
+                inPackages = false;
+        }
+    }
+    return out;
+}
+export function workspaceManifests(root) {
+    const out = [];
+    const add = (dir) => {
+        const file = join(dir, 'package.json');
+        if (!existsSync(file))
+            return;
+        out.push({ file: rel(root, file) || 'package.json', dir, json: JSON.parse(readFileSync(file, 'utf8')) });
+    };
+    add(root);
+    for (const g of workspaceGlobs(root)) {
+        if (g.startsWith('!'))
+            continue;
+        if (g.endsWith('/*')) {
+            const base = join(root, g.slice(0, -2));
+            if (!existsSync(base))
+                continue;
+            for (const e of readdirSync(base).sort()) {
+                const d = join(base, e);
+                if (statSync(d).isDirectory() && e !== 'node_modules')
+                    add(d);
+            }
+        }
+        else if (!g.includes('*'))
+            add(join(root, g));
+    }
+    return out;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@agenticprimitives/devkit",
+  "version": "0.0.0-alpha.1",
+  "description": "The Developer Kit core (spec 398 §10 / spec 399 §3): `ap doctor` runs the doctrine gates as data + pure rules over any tree, `ap doctor --rules` projects one pinned rules source into AGENTS.md / CLAUDE.md / .cursor/rules by digest, `ap upgrade` rewrites every @agenticprimitives/* pin to one coherent exact set, and `ap conform` / `ap test` dispatch to the packages that own conformance and live gates.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/devkit"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "ap": "./bin/ap.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "bin",
+    "rules",
+    "spec.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agenticprimitives/capability-claims": "0.0.0-alpha.19"
+  },
+  "peerDependencies": {
+    "@agenticprimitives/a2a": "0.0.0-alpha.19",
+    "@agenticprimitives/evaluation": "0.0.0-alpha.1",
+    "@agenticprimitives/mcp-protocol": "0.0.0-alpha.1"
+  },
+  "peerDependenciesMeta": {
+    "@agenticprimitives/a2a": {
+      "optional": true
+    },
+    "@agenticprimitives/evaluation": {
+      "optional": true
+    },
+    "@agenticprimitives/mcp-protocol": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "agentic",
+    "primitives",
+    "devkit",
+    "doctor",
+    "developer-kit",
+    "cli"
+  ],
+  "scripts": {
+    "sync-rules": "node scripts/sync-rules.mjs",
+    "build": "node scripts/sync-rules.mjs && rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

package/rules/coordination-vs-orchestration.md

@@ -0,0 +1,31 @@
+# Coordination vs orchestration (ADR-0044 + ADR-0054)
+
+Two planning planes. Never collapse them. Full doc: `docs/architecture/coordination-vs-orchestration.md`.
+
+## One sentence
+
+**Agentic coordination** schedules work **between agents** (durable Endeavor + shared CoordinationPlan, participants resolved through **discovery** at the **capability level**); **agent orchestration** sequences work **within one agent** (run-specific ExecutionPlan, informed by **Agent Skill packages / `SKILL.md`** and injected MCP tools).
+
+## Plane map
+
+| | Coordination | Orchestration |
+| --- | --- | --- |
+| Scope | between agents, multi-principal | within one agent, one executor |
+| Package | `@agenticprimitives/coordination` | `@agenticprimitives/orchestration` (+ `-anthropic` adapter) |
+| Ontology | `apcoord:` | `apexec:` (+ `apguide:` playbooks) |
+| Plan | `CoordinationPlan` — durable, versioned, adopted by decision | `ExecutionPlan` — one goal, one run |
+| Actors | found via discovery: `agent-naming`, `registry-kit`, `apdisc:` capability matching | given: harness-activated `SKILL.md` packages + `ToolInvoker` tools |
+| Needs stated as | `aps:Capability` requirement on a `PlanStep` | MCP tool invocation guided by a playbook |
+| Binding act | signed `ContributionCommitment` against an exact plan revision hash | `p-plan:correspondsToStep` + qualified association |
+
+## Rules
+
+1. **Name the plane.** Bare "scheduling" is ambiguous: say **allocation** (between agents) or **step ordering** (within a run).
+2. **Discovery is coordination-plane only.** The orchestration core never imports/queries naming, registry, or `apdisc:` — tools and playbooks are injected through its ports.
+3. **Coordination speaks capabilities; orchestration speaks tools/playbooks.** MCP tool ids and `SKILL.md` content never appear in `apcoord:` records; capability requirements never appear in `ToolSpec`s.
+4. **`CoordinationPlan` ≠ `apexec:ExecutionPlan`.** Related only through compilation provenance (`prov:wasDerivedFrom` + `ep-plan:isDecomposedAsPlan` + `p-plan:correspondsToStep`). Never subclass or synonymize.
+5. **No back-edges.** `coordination` and `orchestration` never import each other; the a2a runtime composes both.
+6. **Runs never mutate coordination state.** Execution outcomes enter an Endeavor only as signed commands through the coordination reducer.
+7. **Neither plane is authority** (ADR-0054 §4): allocation, commitment, adoption, playbook activation grant nothing; no gate reads `apcoord:`/`apexec:` terms.
+
+**Source:** ADR-0044, ADR-0054, spec 330, spec 332, `plan.ttl`, coordination-vs-orchestration.md.