@aopslabs/aops 0.2.0

package/dist/utils/playbook-workspace.js

@@ -0,0 +1,479 @@
+import { compactPayload, normalizeNonEmpty } from './command.js';
+import { readLocalMemoryEntries, resolveMemoryWorkspacePaths, } from './memory-workspace.js';
+function toStringArray(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeNonEmpty(entry)).filter((entry) => Boolean(entry));
+    }
+    const normalized = normalizeNonEmpty(value);
+    return normalized ? [normalized] : [];
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function toRecordArray(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const normalized = normalizeNonEmpty(value);
+        if (!normalized)
+            continue;
+        const key = normalized.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(normalized);
+    }
+    return result;
+}
+function tagValue(tags, prefix) {
+    const normalizedPrefix = prefix.toLowerCase();
+    const match = tags.find((tag) => tag.toLowerCase().startsWith(normalizedPrefix));
+    return match ? normalizeNonEmpty(match.slice(prefix.length)) : undefined;
+}
+function hasPlaybookTag(tags) {
+    return tags.some((tag) => {
+        const normalized = tag.toLowerCase();
+        return normalized === 'playbook' || normalized.startsWith('playbook-') || normalized.startsWith('playbook:');
+    });
+}
+function contentTitle(content) {
+    const first = normalizeNonEmpty(content)?.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+    return first?.replace(/^#+\s*/, '').slice(0, 120);
+}
+function summarizeContent(content, maxLength = 240) {
+    const compact = normalizeNonEmpty(content)?.replace(/\s+/g, ' ');
+    if (!compact)
+        return undefined;
+    if (compact.length <= maxLength)
+        return compact;
+    return `${compact.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+export function normalizePlaybookScope(value) {
+    const normalized = normalizeNonEmpty(value)?.toLowerCase();
+    return normalized === 'session' ? 'session' : 'project';
+}
+export function normalizePlaybookReviewState(value) {
+    const normalized = normalizeNonEmpty(value)?.toLowerCase();
+    if (normalized === 'accepted' || normalized === 'superseded' || normalized === 'archived')
+        return normalized;
+    return 'proposed';
+}
+export function normalizePlaybookEnforcement(value) {
+    const normalized = normalizeNonEmpty(value)?.toLowerCase();
+    if (normalized === 'soft-preflight' || normalized === 'strict-opt-in')
+        return normalized;
+    return 'advisory';
+}
+export function buildPlaybookTags(params) {
+    const scope = normalizePlaybookScope(params.scope);
+    const area = normalizeNonEmpty(params.area);
+    const source = normalizeNonEmpty(params.source);
+    return uniqueStrings([
+        'playbook',
+        `playbook-scope:${scope}`,
+        area ? `playbook-area:${area}` : undefined,
+        source ? `playbook-source:${source}` : undefined,
+        ...(params.extraTags ?? []),
+    ]);
+}
+export function buildPlaybookMeta(input) {
+    const scope = normalizePlaybookScope(input.scope);
+    return compactPayload({
+        id: normalizeNonEmpty(input.id),
+        title: normalizeNonEmpty(input.title) ?? 'Untitled playbook',
+        scope,
+        area: normalizeNonEmpty(input.area),
+        appliesWhen: normalizeNonEmpty(input.appliesWhen),
+        steps: uniqueStrings(input.steps ?? []),
+        evidence: input.evidence,
+        enforcement: normalizePlaybookEnforcement(input.enforcement),
+        confidence: normalizeNonEmpty(input.confidence),
+        reviewState: normalizePlaybookReviewState(input.reviewState),
+        supersedes: normalizeNonEmpty(input.supersedes),
+        promotedFromExperienceId: normalizeNonEmpty(input.promotedFromExperienceId),
+        sessionContext: input.sessionContext && Object.keys(compactPayload(input.sessionContext)).length > 0
+            ? compactPayload(input.sessionContext)
+            : undefined,
+    });
+}
+export function isPlaybookMemoryEntry(entry) {
+    const kind = normalizeNonEmpty(entry.kind)?.toLowerCase();
+    if (kind !== 'rule' && kind !== 'constraint')
+        return false;
+    const meta = isRecord(entry.raw?.meta) ? entry.raw.meta : {};
+    const playbook = isRecord(meta.playbook) ? meta.playbook : {};
+    return Object.keys(playbook).length > 0 || hasPlaybookTag(entry.tags);
+}
+export function memoryEntryToPlaybookRecord(entry) {
+    if (!isPlaybookMemoryEntry(entry))
+        return null;
+    const meta = isRecord(entry.raw?.meta) ? entry.raw.meta : {};
+    const playbook = isRecord(meta.playbook) ? meta.playbook : {};
+    const sourceType = normalizeNonEmpty(entry.raw?.sourceType);
+    const sourceId = normalizeNonEmpty(entry.raw?.sourceId);
+    const id = normalizeNonEmpty(playbook.id) ?? entry.memoryId ?? entry.id;
+    const scope = normalizeNonEmpty(playbook.scope) ?? tagValue(entry.tags, 'playbook-scope:');
+    const area = normalizeNonEmpty(playbook.area) ?? tagValue(entry.tags, 'playbook-area:');
+    return {
+        id,
+        playbookId: id,
+        title: normalizeNonEmpty(playbook.title) ?? entry.subjectTitle ?? contentTitle(entry.content) ?? id,
+        memoryItemId: entry.memoryId ?? entry.id,
+        kind: entry.kind,
+        durability: entry.durability,
+        scope,
+        area,
+        appliesWhen: normalizeNonEmpty(playbook.appliesWhen),
+        steps: toStringArray(playbook.steps),
+        enforcement: normalizeNonEmpty(playbook.enforcement),
+        confidence: normalizeNonEmpty(playbook.confidence),
+        reviewState: normalizeNonEmpty(playbook.reviewState),
+        supersedes: normalizeNonEmpty(playbook.supersedes),
+        promotedFromExperienceId: normalizeNonEmpty(playbook.promotedFromExperienceId),
+        sessionContext: playbook.sessionContext,
+        sourceType,
+        sourceId,
+        sourceRefs: entry.sourceRefs,
+        content: entry.content,
+        tags: entry.tags,
+        updatedAt: entry.updatedAt,
+        createdAt: entry.createdAt,
+    };
+}
+export function toPlaybookBrief(record) {
+    return {
+        id: record.id ?? record.playbookId,
+        title: record.title,
+        scope: record.scope,
+        area: record.area,
+        kind: record.kind,
+        durability: record.durability,
+        reviewState: record.reviewState,
+        enforcement: record.enforcement,
+        appliesWhen: record.appliesWhen,
+        steps: record.steps ?? [],
+        contentPreview: summarizeContent(record.content),
+        tags: record.tags,
+        memoryItemId: record.memoryItemId,
+        promotedFromExperienceId: record.promotedFromExperienceId,
+        sourceType: record.sourceType,
+        sourceId: record.sourceId,
+        updatedAt: record.updatedAt ?? record.createdAt,
+    };
+}
+export function renderPlaybookMarkdown(record) {
+    const brief = toPlaybookBrief(record);
+    const lines = [`# ${brief.title ?? brief.id ?? 'Playbook'}`, ''];
+    const facts = compactPayload({
+        id: brief.id,
+        memoryItemId: brief.memoryItemId,
+        scope: brief.scope,
+        area: brief.area,
+        kind: brief.kind,
+        durability: brief.durability,
+        reviewState: brief.reviewState,
+        enforcement: brief.enforcement,
+        appliesWhen: brief.appliesWhen,
+        promotedFromExperienceId: brief.promotedFromExperienceId,
+        updatedAt: brief.updatedAt,
+    });
+    lines.push('## Facts');
+    Object.entries(facts).forEach(([key, value]) => lines.push(`- ${key}: ${String(value)}`));
+    lines.push('');
+    lines.push('## Steps');
+    if (brief.steps.length === 0) {
+        lines.push('- No structured steps recorded.');
+    }
+    else {
+        brief.steps.forEach((step) => lines.push(`- ${step}`));
+    }
+    lines.push('');
+    lines.push('## Content');
+    lines.push(normalizeNonEmpty(record.content) ?? brief.contentPreview ?? 'No content recorded.');
+    if (brief.tags.length > 0) {
+        lines.push('', '## Tags', brief.tags.map((tag) => `- ${tag}`).join('\n'));
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function filterPlaybookRecords(records, filter = {}) {
+    const id = normalizeNonEmpty(filter.id)?.toLowerCase();
+    const scope = normalizeNonEmpty(filter.scope)?.toLowerCase();
+    const areas = toStringArray(filter.area).map((entry) => entry.toLowerCase());
+    const durability = toStringArray(filter.durability).map((entry) => entry.toLowerCase());
+    const reviewState = normalizeNonEmpty(filter.reviewState)?.toLowerCase();
+    const tags = toStringArray(filter.tag).map((entry) => entry.toLowerCase());
+    const filtered = records.filter((record) => {
+        if (id) {
+            const candidates = [record.id, record.playbookId, record.memoryItemId, record.title]
+                .map((entry) => normalizeNonEmpty(entry)?.toLowerCase())
+                .filter(Boolean);
+            if (!candidates.some((candidate) => candidate === id || candidate?.startsWith(id)))
+                return false;
+        }
+        if (scope && normalizeNonEmpty(record.scope)?.toLowerCase() !== scope)
+            return false;
+        if (areas.length > 0 && !areas.includes(normalizeNonEmpty(record.area)?.toLowerCase() ?? ''))
+            return false;
+        if (durability.length > 0 && !durability.includes(normalizeNonEmpty(record.durability)?.toLowerCase() ?? ''))
+            return false;
+        if (reviewState && normalizeNonEmpty(record.reviewState)?.toLowerCase() !== reviewState)
+            return false;
+        if (tags.length > 0) {
+            const itemTags = record.tags.map((tag) => tag.toLowerCase());
+            if (!tags.every((tag) => itemTags.includes(tag)))
+                return false;
+        }
+        return true;
+    });
+    return Number.isFinite(filter.limit) && filter.limit && filter.limit > 0
+        ? filtered.slice(0, Math.trunc(filter.limit))
+        : filtered;
+}
+function getSessionContextMissionId(record) {
+    return isRecord(record.sessionContext) ? normalizeNonEmpty(record.sessionContext.missionId) : undefined;
+}
+function sourceRefsIncludeMission(record, missionId) {
+    return toRecordArray(record.sourceRefs).some((ref) => {
+        const refType = normalizeNonEmpty(ref.refType)?.toLowerCase();
+        const refId = normalizeNonEmpty(ref.refId) ?? normalizeNonEmpty(ref.id);
+        return refId === missionId && (refType === undefined || refType === 'agentspace.mission' || refType === 'mission');
+    });
+}
+function isActiveSessionPlaybook(record, missionId) {
+    if (normalizeNonEmpty(record.scope)?.toLowerCase() !== 'session')
+        return false;
+    if (!missionId)
+        return true;
+    return getSessionContextMissionId(record) === missionId || sourceRefsIncludeMission(record, missionId);
+}
+function buildSessionPlaybookSet(records, options = {}) {
+    const missionId = normalizeNonEmpty(options.missionId);
+    const reviewState = toStringArray(options.reviewState).length > 0
+        ? toStringArray(options.reviewState).map((entry) => entry.toLowerCase())
+        : ['accepted'];
+    const durability = toStringArray(options.durability).length > 0
+        ? toStringArray(options.durability).map((entry) => entry.toLowerCase())
+        : ['short', 'durable', 'sticky'];
+    const limit = Number.isFinite(options.limit) && options.limit && options.limit > 0
+        ? Math.trunc(options.limit)
+        : 8;
+    const filtered = records.filter((record) => {
+        if (!isActiveSessionPlaybook(record, missionId))
+            return false;
+        if (!durability.includes(normalizeNonEmpty(record.durability)?.toLowerCase() ?? ''))
+            return false;
+        if (!reviewState.includes(normalizeNonEmpty(record.reviewState)?.toLowerCase() ?? ''))
+            return false;
+        return true;
+    }).slice(0, limit);
+    const command = [
+        'aops-cli playbook list',
+        options.projectSlug ? `--project-slug ${options.projectSlug}` : undefined,
+        '--scope session',
+        ...reviewState.map((state) => `--review-state ${state}`),
+        '--json',
+    ].filter(Boolean).join(' ');
+    return {
+        mode: 'repo-first-playbook-set',
+        readOnly: true,
+        scope: 'session',
+        filters: {
+            scope: 'session',
+            durability,
+            reviewState,
+            ...(missionId ? { missionId } : {}),
+            limit,
+        },
+        count: filtered.length,
+        data: filtered.map(toPlaybookBrief),
+        suggestedActions: [
+            {
+                kind: 'inspect-session-playbooks',
+                mode: 'read-only',
+                applyRequired: false,
+                command,
+                policyPath: 'mission.policy.playbook.sessionSet',
+                note: missionId
+                    ? 'Review accepted session-scope playbooks attached to this mission before resuming work.'
+                    : 'Review accepted session-scope playbooks before resuming active work.',
+            },
+        ],
+        note: 'Session playbooks are read-only active-mission guidance; start/resume surfaces never promote them silently.',
+    };
+}
+export function buildProjectPlaybookSet(records, options = {}) {
+    const reviewState = toStringArray(options.reviewState).length > 0
+        ? toStringArray(options.reviewState).map((entry) => entry.toLowerCase())
+        : ['accepted'];
+    const durability = toStringArray(options.durability).length > 0
+        ? toStringArray(options.durability).map((entry) => entry.toLowerCase())
+        : ['sticky', 'durable'];
+    const limit = Number.isFinite(options.limit) && options.limit && options.limit > 0
+        ? Math.trunc(options.limit)
+        : 8;
+    const filtered = records.filter((record) => {
+        if (normalizeNonEmpty(record.scope)?.toLowerCase() !== 'project')
+            return false;
+        if (!durability.includes(normalizeNonEmpty(record.durability)?.toLowerCase() ?? ''))
+            return false;
+        if (!reviewState.includes(normalizeNonEmpty(record.reviewState)?.toLowerCase() ?? ''))
+            return false;
+        return true;
+    }).slice(0, limit);
+    const command = [
+        'aops-cli playbook project-set',
+        options.projectSlug ? `--project-slug ${options.projectSlug}` : undefined,
+        '--scope project',
+        ...reviewState.map((state) => `--review-state ${state}`),
+        '--json',
+    ].filter(Boolean).join(' ');
+    return {
+        mode: 'repo-first-playbook-set',
+        readOnly: true,
+        scope: 'project',
+        filters: {
+            scope: 'project',
+            durability,
+            reviewState,
+            limit,
+        },
+        count: filtered.length,
+        data: filtered.map(toPlaybookBrief),
+        suggestedActions: [
+            {
+                kind: 'inspect-project-playbooks',
+                mode: 'read-only',
+                applyRequired: false,
+                command,
+                policyPath: 'mission.policy.playbook.projectSet',
+                note: 'Review accepted project-scope playbooks before starting or resuming work.',
+            },
+        ],
+        note: 'Project playbooks are read-only start/resume guidance projected from sticky or durable memory rules/constraints.',
+    };
+}
+export function buildActivePlaybookNudgePack(records, options = {}) {
+    const missionId = normalizeNonEmpty(options.missionId);
+    const project = buildProjectPlaybookSet(records, {
+        projectSlug: options.projectSlug,
+        reviewState: options.reviewState,
+        durability: options.projectDurability,
+        limit: options.limit,
+    });
+    const session = buildSessionPlaybookSet(records, {
+        projectSlug: options.projectSlug,
+        missionId,
+        reviewState: options.reviewState,
+        durability: options.sessionDurability,
+        limit: options.limit,
+    });
+    const closeoutCaptureActions = [
+        {
+            kind: 'capture-closeout-experience',
+            mode: 'nudge-first',
+            applyRequired: true,
+            command: [
+                'aops-cli experience capture',
+                '--type pattern',
+                '--title "Hexagen backend playbook candidate"',
+                '--area hexagen',
+                '--tag playbook-candidate',
+                missionId ? `--mission-id ${missionId}` : undefined,
+                '--content "<reviewed closeout pattern, evidence, and applicability>"',
+                '--apply --json',
+            ].filter(Boolean).join(' '),
+            policyPath: 'mission.policy.playbook.closeoutCapture.capture',
+            note: 'At closeout, capture only reviewed operator/reviewer signal as experience; this is an explicit write.',
+        },
+        {
+            kind: 'promote-closeout-playbook',
+            mode: 'nudge-first',
+            applyRequired: true,
+            command: [
+                'aops-cli playbook promote',
+                '--id <experience-id>',
+                options.projectSlug ? `--project-slug ${options.projectSlug}` : undefined,
+                '--scope project',
+                '--area hexagen',
+                '--review-state accepted',
+                '--applies-when "A future hexagen backend slice needs the same generated-domain pattern"',
+                '--apply --json',
+            ].filter(Boolean).join(' '),
+            policyPath: 'mission.policy.playbook.closeoutCapture.promote',
+            note: 'Promote a reviewed experience into an accepted playbook only after operator/reviewer signal.',
+        },
+        {
+            kind: 'write-closeout-summary',
+            mode: 'nudge-first',
+            applyRequired: true,
+            command: 'aops-cli mem summary --closeout --durability durable --confirm --content "<outcome, validation, review evidence, next action>" --apply --json',
+            policyPath: 'mission.policy.closeout.handoff',
+            note: 'Durable closeout memory remains explicit and confirmed; it is evidence for later playbook promotion, not an automatic promotion.',
+        },
+    ];
+    const hexagenCommands = [
+        'aops-cli experience capture --type pattern --title "Hexagen backend slice pattern" --area hexagen --command "<validated generation/build/test commands>" --source-ref "<PM/RR refs>" --apply --json',
+        'aops-cli playbook promote --id <experience-id> --scope project --area hexagen --review-state accepted --step "<repeatable hexagen step>" --apply --json',
+        options.projectSlug
+            ? `aops-cli playbook project-set --project-slug ${options.projectSlug} --scope project --review-state accepted --json`
+            : 'aops-cli playbook project-set --scope project --review-state accepted --json',
+    ];
+    return {
+        mode: 'active-playbook-nudge-pack',
+        readOnly: true,
+        defaultWrite: false,
+        ...(missionId ? { missionId } : {}),
+        project,
+        session,
+        count: project.count + session.count,
+        suggestedActions: [
+            ...project.suggestedActions,
+            ...session.suggestedActions,
+            ...closeoutCaptureActions,
+        ],
+        closeoutCapture: {
+            mode: 'nudge-first',
+            defaultWrite: false,
+            triggerSignals: ['operator-closeout', 'reviewer-approved-pattern', 'validated-repeatable-hexagen-flow'],
+            suggestedActions: closeoutCaptureActions,
+            note: 'Closeout capture/promote is surfaced as opt-in commands only; no start/resume path writes experience, memory, or playbooks.',
+        },
+        examples: [
+            {
+                kind: 'hexagen-as-playbook',
+                title: 'Hexagen backend slice as accepted project playbook',
+                flow: [
+                    'Complete a hexagen backend slice and gather validation/review evidence.',
+                    'At closeout, capture the repeatable pattern as an experience item with PM/RR/source refs.',
+                    'Promote the reviewed experience into an accepted project-scope playbook.',
+                    'On the next start/resume, read the accepted project playbook through playbook project-set before implementing.',
+                ],
+                commands: hexagenCommands,
+                note: 'Example only; every write command is explicit and guarded with --apply.',
+            },
+        ],
+        note: 'Active playbooks are guidance and nudges. Start/resume reads them and suggests explicit commands; it never writes or promotes playbooks silently.',
+    };
+}
+export async function readLocalPlaybookRecordsFromContext(context) {
+    const paths = resolveMemoryWorkspacePaths(context);
+    const entries = await readLocalMemoryEntries(paths.localItemsDir);
+    return entries
+        .map(memoryEntryToPlaybookRecord)
+        .filter((entry) => Boolean(entry));
+}
+export async function buildReadOnlyProjectPlaybookSetFromContext(context) {
+    const records = await readLocalPlaybookRecordsFromContext(context);
+    return buildProjectPlaybookSet(records, { projectSlug: context.projectSlug });
+}
+export async function buildReadOnlyActivePlaybookNudgePackFromContext(context, options = {}) {
+    const records = await readLocalPlaybookRecordsFromContext(context);
+    return buildActivePlaybookNudgePack(records, {
+        projectSlug: context.projectSlug,
+        missionId: options.missionId,
+        limit: options.limit,
+    });
+}