@aopslabs/aops 0.2.0

package/dist/commands/official-catalog.js

@@ -0,0 +1,134 @@
+import path from 'node:path';
+import { Command } from 'commander';
+import { verifyAndLoadCommunityCatalogReleaseInputs } from '../lib/agent-assets/release-input.js';
+import { createHostedOfficialCatalogAdapterV1 } from '../lib/official-catalog-gateway.js';
+import { buildOfficialCatalogPackageImports, OFFICIAL_CATALOG_SCOPE_V1, OFFICIAL_CATALOG_TOOL_IDS_V1, OfficialCatalogError, reconcileOfficialCatalog, rollbackOfficialCatalog, } from '../lib/official-catalog.js';
+export const OFFICIAL_CATALOG_SETUP_SURFACE_V1 = 'official-catalog-setup-v1';
+function required(value, flag) {
+    const normalized = value?.trim();
+    if (!normalized)
+        throw new OfficialCatalogError('catalog_release_invalid', `${flag} is required.`);
+    return normalized;
+}
+function releaseRoot(value) {
+    const normalized = required(value, '--from-release');
+    if (/\0|\r|\n/.test(normalized) || /^[a-z][a-z0-9+.-]*:\/\//i.test(normalized)) {
+        throw new OfficialCatalogError('catalog_release_invalid', '--from-release must be a local verified release directory.');
+    }
+    return path.resolve(normalized);
+}
+function mode(options) {
+    if (options.preview && options.apply) {
+        throw new OfficialCatalogError('catalog_release_invalid', '--preview and --apply are mutually exclusive.');
+    }
+    return options.apply === true ? 'apply' : 'preview';
+}
+async function resolveAdapter(options, dependencies) {
+    if (dependencies.adapter)
+        return dependencies.adapter;
+    return createHostedOfficialCatalogAdapterV1(options);
+}
+function print(command, mutationFree, result) {
+    console.log(JSON.stringify({
+        schemaVersion: 1,
+        surface: OFFICIAL_CATALOG_SETUP_SURFACE_V1,
+        command,
+        mutationFree,
+        scope: OFFICIAL_CATALOG_SCOPE_V1,
+        result,
+    }, null, 2));
+}
+export async function runOfficialCatalogStatus(options = {}, dependencies = {}) {
+    const adapter = await resolveAdapter(options, dependencies);
+    const result = await adapter.inspect();
+    print('setup.catalog.status', true, result);
+    return result;
+}
+export async function runOfficialCatalogReconcile(options = {}, dependencies = {}) {
+    const selectedMode = mode(options);
+    const loadRelease = dependencies.loadRelease ?? verifyAndLoadCommunityCatalogReleaseInputs;
+    const inputs = await loadRelease({
+        releaseRoot: releaseRoot(options.fromRelease),
+        verificationMode: 'offline',
+    });
+    const packages = buildOfficialCatalogPackageImports(inputs);
+    const adapter = await resolveAdapter(options, dependencies);
+    const result = await reconcileOfficialCatalog({
+        adapter,
+        packages,
+        mode: selectedMode,
+        idempotencyKey: options.idempotencyKey,
+    });
+    print('setup.catalog.reconcile', selectedMode === 'preview' || result.kind === 'aops-official-catalog-reconcile-plan-v1', result);
+    return result;
+}
+export async function runOfficialCatalogRollback(options = {}, dependencies = {}) {
+    const selectedMode = mode(options);
+    if (selectedMode === 'apply' && options.confirm !== true) {
+        throw new OfficialCatalogError('catalog_release_invalid', 'Rollback requires --apply --confirm.');
+    }
+    const adapter = await resolveAdapter(options, dependencies);
+    const result = await rollbackOfficialCatalog({
+        adapter,
+        receiptId: required(options.receipt, '--receipt'),
+        mode: selectedMode,
+        idempotencyKey: options.idempotencyKey,
+    });
+    print('setup.catalog.rollback', selectedMode === 'preview', result);
+    return result;
+}
+function addRemoteOptions(command) {
+    return command
+        .option('--api-base-url <url>', 'Local or remote AOPS server URL')
+        .option('--timeout-ms <ms>', 'Hosted operation timeout', (value) => Number.parseInt(String(value), 10))
+        .option('--tenant-id <id>', 'Tenant routing header; catalog scope remains fixed')
+        .option('--json', 'Output the stable official-catalog-setup-v1 envelope');
+}
+export function makeOfficialCatalogSetupCommand(dependencies = {}) {
+    const command = new Command('catalog')
+        .description(`Inspect or reconcile the inert signed AOPS official server catalog in the fixed ${OFFICIAL_CATALOG_SCOPE_V1.slug} scope (server contract: ${OFFICIAL_CATALOG_TOOL_IDS_V1.reconcile})`);
+    addRemoteOptions(command.command('status')
+        .description('Inspect only the reserved official catalog scope')
+        .action(async (options) => {
+        await runOfficialCatalogStatus(options, dependencies);
+    }));
+    addRemoteOptions(command.command('reconcile')
+        .description('Preview or apply an append-only reconcile from one verified Community release')
+        .requiredOption('--from-release <path>', 'Local signed Community release directory')
+        .option('--idempotency-key <key>', 'Explicit replay key; otherwise derived from release and reserved-scope revision')
+        .option('--preview', 'Preview only (default)')
+        .option('--apply', 'Append versions and update only the reserved current-version map')
+        .action(async (options) => {
+        await runOfficialCatalogReconcile(options, dependencies);
+    }));
+    addRemoteOptions(command.command('rollback')
+        .description('Restore a prior reserved current-version map without deleting history')
+        .requiredOption('--receipt <id>', 'Exact reconcile receipt to restore')
+        .option('--idempotency-key <key>', 'Explicit rollback replay key')
+        .option('--preview', 'Preview only (default)')
+        .option('--apply', 'Apply the receipt-targeted current-version rollback')
+        .option('--confirm', 'Confirm the rollback; required with --apply')
+        .action(async (options) => {
+        await runOfficialCatalogRollback(options, dependencies);
+    }));
+    command.addHelpText('after', `
+The reserved scope is fixed to ${OFFICIAL_CATALOG_SCOPE_V1.slug}. It is routing
+identity only: official trust comes from the verified Community release and the
+package/release digests persisted in SkillVersion meta. Import is inert and does
+not select a discipline, mutate a mission policy, or touch user/project scopes.
+
+Agentspace owns the atomic composite operations and durable receipts. Inspect
+their exact server contracts with:
+  aops-cli agent schema --tool ${OFFICIAL_CATALOG_TOOL_IDS_V1.inspect} --summary
+  aops-cli agent schema --tool ${OFFICIAL_CATALOG_TOOL_IDS_V1.reconcile} --summary
+  aops-cli agent schema --tool ${OFFICIAL_CATALOG_TOOL_IDS_V1.rollback} --summary
+
+Examples:
+  aops-cli setup catalog status --json
+  aops-cli setup catalog reconcile --from-release <path> --preview --json
+  aops-cli setup catalog reconcile --from-release <path> --apply --json
+  aops-cli setup catalog rollback --receipt <id> --preview --json
+  aops-cli setup catalog rollback --receipt <id> --apply --confirm --json
+`);
+    return command;
+}

package/dist/commands/plan.js

@@ -0,0 +1,84 @@
+import { Command } from 'commander';
+import { applyCommonOptions } from '../utils/command.js';
+import { GUIDE_PATHS } from '../utils/guide-paths.js';
+import { collectRepeatedOption, runPmPlanCreate, runPmPlanGet, runPmPlanList, runPmPlanUpdate, } from './pm/projectman.js';
+function applyPlanContextOptions(cmd) {
+    applyCommonOptions(cmd, { withProject: false });
+    cmd.option('--scope-id <id>', 'Canonical owner scope override');
+    cmd.option('--project-id <id>', 'Project id used to resolve the canonical owner scope');
+    cmd.option('--project-name <name>', 'Project name override for repo-aware scope resolution');
+    cmd.option('--project-slug <slug>', 'Project slug from repo project registry; hosted-only links write through the hosted gateway');
+    cmd.option('--tenant-id <id>', 'Tenant id header (x-tenant-id)');
+    cmd.option('--locale <locale>', 'Locale header (x-locale)');
+    cmd.option('--fallback-locale <locale>', 'Fallback locale header (x-fallback-locale)');
+    cmd.addHelpText('after', `\nGuide:\n  ${GUIDE_PATHS.projectman}\n`);
+    return cmd;
+}
+function applyWriteOptions(cmd) {
+    cmd.option('--preview', 'Return a validated preflight summary without executing the tool');
+    cmd.option('--apply', 'Explicitly allow guarded write operations');
+    cmd.option('--idempotency-key <key>', 'Optional guarded-write idempotency key');
+    return cmd;
+}
+function applyMemoryCadenceOptions(cmd) {
+    cmd.option('--write-memory', 'Write an opt-in local memory side-effect after the main repo-first operation succeeds');
+    cmd.option('--memory-mode <mode>', 'Memory mode override: kickoff, resume, decision, blocker, closeout, rule');
+    cmd.option('--memory-content <text>', 'Optional explicit memory content override');
+    cmd.option('--memory-next-action <text>', 'Optional next action for the memory side-effect');
+    cmd.option('--memory-validation-state <text>', 'Optional validation state for the memory side-effect');
+    return cmd;
+}
+export function makePlanCommand() {
+    const cmd = new Command('plan')
+        .description('Sprint-backed Projectman implementation plan commands')
+        .addHelpText('after', '\nNotes:\n' +
+        '  implementation-plan is a facade over Projectman sprint documents; the plan id is the sprint id.\n' +
+        '  This command does not create a second plan table or app-local plan store.\n' +
+        '  For one-item checklist edits, use `aops-cli pm utask ...` until top-level plan microtask sugar is added.\n');
+    applyPlanContextOptions(applyMemoryCadenceOptions(applyWriteOptions(cmd
+        .command('create')
+        .description('Create a sprint-backed implementation plan for a kanban task')
+        .requiredOption('--task <id>', 'Kanban task id')
+        .requiredOption('--name <name>', 'Plan name')
+        .requiredOption('--goal <text>', 'Plan goal')
+        .option('--reference <value>', 'Repeatable reference item', collectRepeatedOption, [])
+        .option('--scope-item <value>', 'Repeatable scope item', collectRepeatedOption, [])
+        .option('--validation-item <value>', 'Repeatable validation item', collectRepeatedOption, [])
+        .option('--notes <text>', 'Optional notes'))).action(async (options) => {
+        await runPmPlanCreate(options);
+    }));
+    applyPlanContextOptions(cmd
+        .command('list')
+        .description('List sprint-backed implementation plans')
+        .option('--task <id>', 'Optional kanban task id filter')
+        .option('--name <name>', 'Optional plan name filter')
+        .option('--status <value>', 'Optional plan status filter')
+        .option('--limit <n>', 'Maximum records to return after filtering')
+        .option('--summary', 'Return compact plan rows instead of full sprint plans')
+        .option('--include-archived', 'Include plans whose backing sprint has archivedAt set')
+        .action(async (options) => {
+        await runPmPlanList(options);
+    }));
+    applyPlanContextOptions(cmd
+        .command('get')
+        .description('Get a sprint-backed implementation plan by selector')
+        .requiredOption('--id <id>', 'Plan selector: full id, 8+ id prefix, slug, or exact name/title')
+        .action(async (options) => {
+        await runPmPlanGet(options);
+    }));
+    applyPlanContextOptions(applyMemoryCadenceOptions(applyWriteOptions(cmd
+        .command('update')
+        .description('Patch a sprint-backed implementation plan, including phases and microtasks')
+        .requiredOption('--id <id>', 'Plan id')
+        .option('--name <name>', 'Updated plan name')
+        .option('--goal <text>', 'Updated plan goal')
+        .option('--reference <value>', 'Repeatable reference item patch', collectRepeatedOption, [])
+        .option('--scope-item <value>', 'Repeatable scope item patch', collectRepeatedOption, [])
+        .option('--validation-item <value>', 'Repeatable validation item patch', collectRepeatedOption, [])
+        .option('--notes <text>', 'Updated plan notes')
+        .option('--phases-json <json-or-@file>', 'JSON array or @file.json array for nested phase+microtask plan; quote @file values in PowerShell')
+        .option('--expected-updated-at <timestamp>', 'Optional optimistic concurrency timestamp from a previous plan snapshot'))).action(async (options) => {
+        await runPmPlanUpdate(options);
+    }));
+    return cmd;
+}

package/dist/commands/playbook.js

@@ -0,0 +1,415 @@
+import { Command } from 'commander';
+import { logError, logSuccess } from '@aopslabs/xf-cli-ui';
+import { applyCommonOptions, compactPayload, normalizeNonEmpty } from '../utils/command.js';
+import { runExperiencePromote } from './experience.js';
+import { buildProjectPlaybookSet, filterPlaybookRecords, renderPlaybookMarkdown, toPlaybookBrief, } from '../utils/playbook-workspace.js';
+import { invokeHostedToolWithApiState, requireApiState, unwrapHostedToolResult, } from '../utils/agent-gateway.js';
+import { preferProjectNameBinding, resolveOwnerScopeIdFromBinding, resolveOwnerScopeIdFromProjectRecord, resolveProjectBindingContext, } from '../utils/project-context.js';
+const PLAYBOOK_TOOL_ID = 'agentspace.playbook.list';
+function collectRepeatedOption(value, previous = []) {
+    const normalized = normalizeNonEmpty(value);
+    return normalized ? [...previous, normalized] : previous;
+}
+function parseInteger(value) {
+    return Number.parseInt(value, 10);
+}
+function applyProjectSlugOption(cmd) {
+    if (cmd.options.some((option) => option.long === '--project-slug'))
+        return cmd;
+    return cmd.option('--project-slug <slug>', 'Project slug from repo project registry');
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function toStringArray(values) {
+    return Array.isArray(values)
+        ? values.map((entry) => normalizeNonEmpty(entry)).filter((entry) => Boolean(entry))
+        : [];
+}
+function buildResolvedContextRecord(context) {
+    return compactPayload({
+        repoRoot: context.repoRoot,
+        configPath: context.configPath,
+        configFound: context.configFound,
+        scopeId: context.scopeId,
+        projectId: context.projectId,
+        projectName: context.projectName,
+    });
+}
+function buildEnvelope(params) {
+    return {
+        command: params.command,
+        toolId: PLAYBOOK_TOOL_ID,
+        resolvedContext: buildResolvedContextRecord(params.resolvedContext),
+        input: params.input,
+        result: params.result,
+    };
+}
+function emitResult(options, message, envelope, plainResult) {
+    if (options.json) {
+        console.log(JSON.stringify(envelope, null, 2));
+        return;
+    }
+    logSuccess(message);
+    console.log(JSON.stringify(plainResult, null, 2));
+}
+function buildGatewayOptions(options, resolvedContext) {
+    return {
+        ...options,
+        ...preferProjectNameBinding(resolvedContext),
+    };
+}
+async function resolvePlaybookContext(options) {
+    const resolved = await resolveProjectBindingContext(options, { requireProject: false });
+    const scopeId = normalizeNonEmpty(options.scopeId) ?? resolveOwnerScopeIdFromBinding(resolved);
+    return { ...resolved, scopeId };
+}
+async function hydrateProjectScopeContext(apiState, options, resolvedContext) {
+    const projectId = normalizeNonEmpty(resolvedContext.projectId);
+    if (!projectId) {
+        return resolvedContext;
+    }
+    if (normalizeNonEmpty(resolvedContext.scopeId) === projectId && normalizeNonEmpty(resolvedContext.projectName)) {
+        return resolvedContext;
+    }
+    try {
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            toolId: 'agentspace.project.get-by-id',
+            input: { id: projectId },
+        });
+        const result = unwrapHostedToolResult(payload);
+        const project = isRecord(result) && Object.prototype.hasOwnProperty.call(result, 'data')
+            ? result.data
+            : result;
+        if (!isRecord(project)) {
+            return resolvedContext;
+        }
+        const scopeId = resolveOwnerScopeIdFromProjectRecord(project, resolvedContext.scopeId ?? projectId);
+        const projectName = normalizeNonEmpty(project.name) ?? resolvedContext.projectName;
+        return {
+            ...resolvedContext,
+            scopeId: scopeId ?? resolvedContext.scopeId,
+            projectName,
+        };
+    }
+    catch {
+        return resolvedContext;
+    }
+}
+function extractHostedRows(result) {
+    const data = isRecord(result) && Object.prototype.hasOwnProperty.call(result, 'data') ? result.data : result;
+    if (Array.isArray(data))
+        return data.filter(isRecord);
+    if (Array.isArray(result))
+        return result.filter(isRecord);
+    return [];
+}
+function hostedProjectionToPlaybookRecord(row) {
+    const id = normalizeNonEmpty(row.id) ?? normalizeNonEmpty(row.playbookId);
+    return {
+        id,
+        playbookId: normalizeNonEmpty(row.playbookId) ?? id,
+        title: normalizeNonEmpty(row.title) ?? id,
+        memoryItemId: normalizeNonEmpty(row.memoryItemId) ?? normalizeNonEmpty(row.sourceMemoryItemId),
+        kind: normalizeNonEmpty(row.kind),
+        durability: normalizeNonEmpty(row.durability),
+        scope: normalizeNonEmpty(row.scope),
+        area: normalizeNonEmpty(row.area),
+        appliesWhen: normalizeNonEmpty(row.appliesWhen),
+        steps: toStringArray(row.steps),
+        enforcement: normalizeNonEmpty(row.enforcement),
+        confidence: normalizeNonEmpty(row.confidence),
+        reviewState: normalizeNonEmpty(row.reviewState),
+        supersedes: normalizeNonEmpty(row.supersedes),
+        promotedFromExperienceId: normalizeNonEmpty(row.promotedFromExperienceId),
+        sessionContext: row.sessionContext,
+        sourceType: normalizeNonEmpty(row.sourceType),
+        sourceId: normalizeNonEmpty(row.sourceId),
+        sourceRefs: Array.isArray(row.sourceRefs) ? row.sourceRefs : undefined,
+        content: normalizeNonEmpty(row.content),
+        tags: toStringArray(row.tags),
+        updatedAt: normalizeNonEmpty(row.updatedAt),
+        createdAt: normalizeNonEmpty(row.createdAt),
+    };
+}
+async function loadPlaybooks(apiState, context, options) {
+    const input = compactPayload({
+        filter: compactPayload({
+            scopeId: context.scopeId,
+            scopeResolution: 'cascade',
+            projectId: context.projectId,
+        }),
+    });
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, context),
+        tenantId: options.tenantId,
+        locale: options.locale,
+        fallbackLocale: options.fallbackLocale,
+        timeoutMs: options.timeoutMs,
+        apiBaseUrl: options.apiBaseUrl,
+        accessToken: options.accessToken,
+        refreshToken: options.refreshToken,
+        toolId: PLAYBOOK_TOOL_ID,
+        input,
+    });
+    const result = unwrapHostedToolResult(payload);
+    return extractHostedRows(result)
+        .map(hostedProjectionToPlaybookRecord)
+        .sort((left, right) => (right.updatedAt ?? right.createdAt ?? '').localeCompare(left.updatedAt ?? left.createdAt ?? ''));
+}
+function emitPlaybookCommandError(params) {
+    const message = params.error instanceof Error ? params.error.message : String(params.error);
+    if (params.options.json) {
+        console.log(JSON.stringify({
+            command: params.command,
+            toolId: PLAYBOOK_TOOL_ID,
+            resolvedContext: params.resolvedContext ? buildResolvedContextRecord(params.resolvedContext) : {},
+            input: params.input ?? {},
+            result: { error: { message } },
+        }, null, 2));
+    }
+    else {
+        logError(message);
+    }
+    process.exitCode = 1;
+}
+export async function runPlaybookList(options = {}) {
+    let context;
+    let apiState;
+    try {
+        apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        context = await resolvePlaybookContext(options);
+        context = await hydrateProjectScopeContext(apiState, options, context);
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const playbooks = filterPlaybookRecords(await loadPlaybooks(apiState, context, options), {
+            scope: options.scope,
+            area: options.area,
+            durability: options.durability,
+            reviewState: options.reviewState,
+            tag: options.tag,
+            limit: options.limit,
+        });
+        const result = {
+            data: playbooks.map((record) => ({ ...record, brief: toPlaybookBrief(record) })),
+            count: playbooks.length,
+            filters: compactPayload({
+                scope: options.scope,
+                area: options.area,
+                durability: options.durability,
+                reviewState: options.reviewState,
+                tag: options.tag,
+                limit: options.limit,
+            }),
+        };
+        emitResult(options, 'Hosted playbook list completed.', buildEnvelope({ command: 'playbook.list', resolvedContext: context, input: compactPayload({ hostedFirst: true, ...options }), result }), result);
+    }
+    catch (error) {
+        emitPlaybookCommandError({ options, command: 'playbook.list', resolvedContext: context, error });
+    }
+}
+export async function runPlaybookGet(options = {}) {
+    let context;
+    let apiState;
+    try {
+        const id = normalizeNonEmpty(options.id);
+        if (!id)
+            throw new Error('Provide --id.');
+        apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        context = await resolvePlaybookContext(options);
+        context = await hydrateProjectScopeContext(apiState, options, context);
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const id = normalizeNonEmpty(options.id);
+        const [record] = filterPlaybookRecords(await loadPlaybooks(apiState, context, options), { id });
+        if (!record)
+            throw new Error('Hosted playbook was not found.');
+        const result = { data: { ...record, brief: toPlaybookBrief(record) } };
+        emitResult(options, 'Hosted playbook loaded.', buildEnvelope({ command: 'playbook.get', resolvedContext: context, input: { id, hostedFirst: true }, result }), result);
+    }
+    catch (error) {
+        emitPlaybookCommandError({ options, command: 'playbook.get', resolvedContext: context, input: compactPayload({ id: normalizeNonEmpty(options.id) }), error });
+    }
+}
+export async function runPlaybookShow(options = {}) {
+    let context;
+    let apiState;
+    try {
+        const id = normalizeNonEmpty(options.id);
+        if (!id)
+            throw new Error('Provide --id.');
+        apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        context = await resolvePlaybookContext(options);
+        context = await hydrateProjectScopeContext(apiState, options, context);
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const id = normalizeNonEmpty(options.id);
+        const [record] = filterPlaybookRecords(await loadPlaybooks(apiState, context, options), { id });
+        if (!record)
+            throw new Error('Hosted playbook was not found.');
+        const markdown = renderPlaybookMarkdown(record);
+        const result = { data: { ...record, brief: toPlaybookBrief(record) }, markdown };
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'playbook.show',
+                resolvedContext: context,
+                input: { id, hostedFirst: true },
+                result,
+            }), null, 2));
+            return;
+        }
+        process.stdout.write(markdown);
+    }
+    catch (error) {
+        emitPlaybookCommandError({ options, command: 'playbook.show', resolvedContext: context, input: compactPayload({ id: normalizeNonEmpty(options.id) }), error });
+    }
+}
+export async function runPlaybookProjectSet(options = {}) {
+    let context;
+    let apiState;
+    try {
+        apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        context = await resolvePlaybookContext(options);
+        context = await hydrateProjectScopeContext(apiState, options, context);
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const records = filterPlaybookRecords(await loadPlaybooks(apiState, context, options), {
+            scope: normalizeNonEmpty(options.scope) ?? 'project',
+            area: options.area,
+            durability: options.durability,
+            reviewState: options.reviewState,
+            tag: options.tag,
+            limit: options.limit,
+        });
+        const result = buildProjectPlaybookSet(records, {
+            projectSlug: context.projectSlug,
+            reviewState: options.reviewState ? [options.reviewState] : undefined,
+            durability: options.durability,
+            limit: options.limit,
+        });
+        emitResult(options, 'Hosted project playbook set loaded.', buildEnvelope({
+            command: 'playbook.project-set',
+            resolvedContext: context,
+            input: compactPayload({ hostedFirst: true, scope: options.scope ?? 'project', reviewState: options.reviewState, limit: options.limit }),
+            result,
+        }), result);
+    }
+    catch (error) {
+        emitPlaybookCommandError({ options, command: 'playbook.project-set', resolvedContext: context, error });
+    }
+}
+export async function runPlaybookPromote(options = {}) {
+    await runExperiencePromote({
+        ...options,
+        asPlaybook: true,
+        playbookScope: normalizeNonEmpty(options.scope) ?? normalizeNonEmpty(options.playbookScope),
+        playbookArea: normalizeNonEmpty(options.area) ?? normalizeNonEmpty(options.playbookArea),
+    });
+}
+export function makePlaybookCommand() {
+    const cmd = new Command('playbook')
+        .description('List reviewed playbooks projected from hosted Agentspace memory rules/constraints (server-first)');
+    applyCommonOptions(cmd, { withAuth: false, withProject: true, withYes: true, withJson: true });
+    applyProjectSlugOption(cmd);
+    cmd.addHelpText('after', `
+Playbooks are prescriptive methods/patterns/rules stored as hosted memory items
+and read server-first through the hosted playbook.list projection:
+  Source of truth (hosted):
+    agentspace.playbook.list (projects memory items kind=rule|constraint with meta.playbook)
+  Storage contract:
+    kind=rule|constraint, tags include playbook/playbook-scope:*, meta.playbook
+  Local .aops is a read-only cache only; it is never read as truth or rewritten.
+
+Experience stays descriptive. Promote reviewed experience into a playbook explicitly:
+  aops-cli experience promote --id <experience-id> --as-playbook --playbook-area backend --apply --json
+Operator alias:
+  aops-cli playbook promote --id <experience-id> --area backend --review-state accepted --apply --json
+`);
+    const list = cmd.command('list')
+        .description('List hosted playbook projections')
+        .option('--scope <scope>', 'Filter by playbook scope: session or project')
+        .option('--area <area>', 'Filter by playbook area; repeatable', collectRepeatedOption, [])
+        .option('--durability <durability>', 'Filter by memory durability; repeatable', collectRepeatedOption, [])
+        .option('--review-state <state>', 'Filter by review state')
+        .option('--tag <tag>', 'Filter by tag; repeatable', collectRepeatedOption, [])
+        .option('--limit <n>', 'Limit result count', parseInteger)
+        .action((options) => runPlaybookList({ ...cmd.opts(), ...options }));
+    applyCommonOptions(list, { withAuth: false, withProject: true, withYes: true, withJson: true });
+    applyProjectSlugOption(list);
+    const get = cmd.command('get')
+        .description('Get one hosted playbook projection')
+        .requiredOption('--id <id>', 'Playbook id, memory id, or title prefix')
+        .action((options) => runPlaybookGet({ ...cmd.opts(), ...options }));
+    applyCommonOptions(get, { withAuth: false, withProject: true, withYes: true, withJson: true });
+    applyProjectSlugOption(get);
+    const show = cmd.command('show')
+        .description('Render one hosted playbook as agent-readable markdown')
+        .requiredOption('--id <id>', 'Playbook id, memory id, or title prefix')
+        .action((options) => runPlaybookShow({ ...cmd.opts(), ...options }));
+    applyCommonOptions(show, { withAuth: false, withProject: true, withYes: true, withJson: true });
+    applyProjectSlugOption(show);
+    const projectSet = cmd.command('project-set')
+        .description('Load accepted sticky/durable project-scope playbooks for start/resume guidance')
+        .option('--scope <scope>', 'Playbook scope (default: project)', 'project')
+        .option('--area <area>', 'Filter by playbook area; repeatable', collectRepeatedOption, [])
+        .option('--durability <durability>', 'Filter by memory durability; repeatable', collectRepeatedOption, [])
+        .option('--review-state <state>', 'Filter by review state (default: accepted)', 'accepted')
+        .option('--tag <tag>', 'Filter by tag; repeatable', collectRepeatedOption, [])
+        .option('--limit <n>', 'Limit result count (default: 8)', parseInteger)
+        .action((options) => runPlaybookProjectSet({ ...cmd.opts(), ...options }));
+    applyCommonOptions(projectSet, { withAuth: false, withProject: true, withYes: true, withJson: true });
+    applyProjectSlugOption(projectSet);
+    const promote = cmd.command('promote')
+        .description('Promote reviewed experience into a playbook memory rule/constraint')
+        .requiredOption('--id <experience-id>', 'Experience id')
+        .option('--kind <kind>', 'Memory kind: rule or constraint (default: rule)')
+        .option('--durability <durability>', 'Memory durability: durable or sticky (default: durable)')
+        .option('--content <text>', 'Reviewed promoted playbook content')
+        .option('--tag <tag>', 'Extra memory tag; repeatable', collectRepeatedOption, [])
+        .option('--playbook-id <id>', 'Stable playbook id (default: experience id)')
+        .option('--scope <scope>', 'Playbook scope: session or project (default: project)')
+        .option('--playbook-scope <scope>', 'Compatibility alias for --scope')
+        .option('--area <area>', 'Playbook area tag, such as backend or hexagen')
+        .option('--playbook-area <area>', 'Compatibility alias for --area')
+        .option('--applies-when <text>', 'When this playbook should be applied')
+        .option('--step <text>', 'Playbook step; repeatable (default: experience commands)', collectRepeatedOption, [])
+        .option('--enforcement <level>', 'Playbook enforcement: advisory | soft-preflight | strict-opt-in')
+        .option('--review-state <state>', 'Playbook review state: proposed | accepted | superseded | archived')
+        .option('--supersedes <id>', 'Older playbook id this one supersedes')
+        .option('--preview', 'Preview the hosted promotion without applying')
+        .option('--apply', 'Write the memory item')
+        .option('--idempotency-key <key>', 'Idempotency key for the hosted write')
+        .action((options) => runPlaybookPromote({ ...cmd.opts(), ...options }));
+    applyCommonOptions(promote, { withAuth: false, withProject: true, withYes: true, withJson: true });
+    applyProjectSlugOption(promote);
+    return cmd;
+}

package/dist/commands/pm/context.js

@@ -0,0 +1,6 @@
+import { resolveProjectBindingContext, } from '../../utils/project-context.js';
+export async function resolvePmContext(options, params = {}) {
+    return resolveProjectBindingContext(options, {
+        requireProject: params.requireProject !== false,
+    });
+}