import { assertProgressAllowed } from '../core/lifecycle.js'; import path from 'node:path'; import { readdir } from 'node:fs/promises'; import { CONFIDENCE_LEVELS, SCOPES, WORK_TYPES } from './constants.js'; import { resolveWorkflowPolicy } from './policy.js'; import { exists, readText } from '../utils/fs.js'; import { getCurrentState, nextWorkId, workSections, workspacePath, writeCurrentState } from '../core/workspace.js'; import { readYaml, writeYaml } from '../core/yaml.js'; import { REGISTRY_VERSION } from '../skills/constants.js'; import { resolveSkills } from '../skills/resolver.js'; import { KNOWLEDGE_POLICY_VERSION } from '../knowledge/constants.js'; import { loadWorkProgress } from '../core/progress.js'; import { intentFixed } from '../delivery/policy.js'; import { raiseImpact } from '../delivery/impact.js'; import { recordWorkMemoryBase } from '../shared/memory.js'; import { assertEngineeringWorkAllowed } from '../baseline/understanding.js'; import { appendRedactedText, writeRedactedText } from '../security/redact.js'; const ROUTING_FIELDS = new Set(['work_type', 'scope', 'confidence', 'reason', 'title']); export function validateRoutingDecision(input) { if (!input || typeof input !== 'object' || Array.isArray(input)) { throw new Error('Routing decision must be an object.'); } const unknown = Object.keys(input).filter((key) => !ROUTING_FIELDS.has(key)); if (unknown.length) throw new Error(`Unknown routing field(s): ${unknown.join(', ')}.`); if (!WORK_TYPES.includes(input.work_type)) { throw new Error(`work_type must be one of: ${WORK_TYPES.join(', ')}; received ${JSON.stringify(input.work_type)}.`); } if (!SCOPES.includes(input.scope)) { throw new Error(`scope must be one of: ${SCOPES.join(', ')}; received ${JSON.stringify(input.scope)}.`); } if (!CONFIDENCE_LEVELS.includes(input.confidence)) { throw new Error(`confidence must be one of: ${CONFIDENCE_LEVELS.join(', ')}; received ${JSON.stringify(input.confidence)}.`); } if (typeof input.reason !== 'string' || !input.reason.trim()) { throw new Error('reason must be a non-empty string.'); } if (input.title !== undefined && (typeof input.title !== 'string' || !input.title.trim())) { throw new Error('title must be a non-empty string when supplied.'); } return { work_type: input.work_type, scope: input.scope, confidence: input.confidence, reason: input.reason, ...(input.title !== undefined ? { title: input.title.trim() } : {}) }; } // The one canonical way to create classified work: exactly `start` → `route` // (createPendingIntake + routeWorkItem), so every entry path — `start`/`route`, // file intake, and the direct `feature`/`bug`/`investigate`/... shortcuts — gets the // same workflow policy, pinned Behavior Contract, Skill Registry version, read-only // policy, knowledge policy, and initial stage. The decision and its policy are // validated before anything is written, so an invalid classification mutates nothing. export async function createRoutedWork(root, rawRequest, decision, options = {}) { const validated = validateRoutingDecision(decision); resolveWorkflowPolicy(validated.work_type, validated.scope); const pending = await createPendingIntake(root, rawRequest, options); return routeWorkItem(root, pending.id, decision); } export async function createPendingIntake(root, rawRequest, options = {}) { if (typeof rawRequest !== 'string' || !rawRequest.trim()) { throw new Error('A non-empty raw request is required.'); } // v0.3.10-internal.4: no normal engineering work before Brownfield understanding is // approved — refused here, before an ID is allocated or anything is written. await assertEngineeringWorkAllowed(root, { request: options.titleHint ?? rawRequest }); // A work item may reference more than one source at once (`yallaflow intake // file1.docx file2.xlsx`) and more over time (`yallaflow intake add`); `sources` // is therefore always an array. const linkedAt = new Date().toISOString(); const sources = options.sources !== undefined ? options.sources.map((source) => validateSourceRef({ ...source, linkedAt, workStatusAtLink: 'PENDING', relationship: 'work-input' })) : undefined; const titleHint = options.titleHint !== undefined ? normalizeTitleHint(options.titleHint) : undefined; const attestation = options.attestation ? { recordedVia: options.attestation.recordedVia, verified: false, ...(options.attestation.requestId ? { requestId: options.attestation.requestId } : {}), at: new Date().toISOString() } : null; const keptActive = options.keepActive ? await unfinishedActiveWork(root) : null; const id = await nextWorkId(root); const now = new Date().toISOString(); const meta = { id, type: null, scope: null, routingStatus: 'pending', rawRequest, status: null, readOnly: true, ...(sources?.length ? { sources } : {}), ...(titleHint ? { titleHint } : {}), ...(attestation ? { attestation } : {}), // --keep-active: creation never activates (owner decision, 1.2.0). keptActive records // the unfinished item that stays in focus, or null when none is active. ...(options.keepActive ? { activation: { deferred: true, keptActive, at: new Date().toISOString() } } : {}), knowledgePolicy: { version: KNOWLEDGE_POLICY_VERSION, reviewRequired: true }, createdAt: now, updatedAt: now }; const workDir = path.join(workspacePath(root), 'work', id); // Sparse workspace (v0.3.6): no optional artifact directory (evidence/, attachments/, // execution/) exists until the first artifact that needs it is written. await writeYaml(path.join(workDir, 'meta.yaml'), meta); await writeRedactedText(path.join(workDir, 'work.md'), pendingWorkTemplate(meta)); await writeRedactedText(path.join(workDir, 'progress.md'), `# Work Ledger — ${id}\n\nCreated: ${now}\n\n- ${now} Routing: pending\n${meta.attestation ? `- ${now} Created from the YallaFlow console (local user, identity not verified)\n` : ''}${meta.activation?.deferred ? `- ${now} Not made the active work item${meta.activation.keptActive ? `: ${meta.activation.keptActive} stays active in this checkout` : ''} (yallaflow activate ${id} makes it active)\n` : ''}`); // Shared Project: the project-memory state this work starts from (no-op otherwise). await recordWorkMemoryBase(root, id, now); if (!meta.activation?.deferred) { await writeCurrentState(root, { schemaVersion: 1, activeWork: id, stage: null, updatedAt: now }); } return meta; } // v1.2.0 `start --keep-active`: the checkout's unfinished active work item, if any. An item // created with keepActive is always deferred; this only records what stayed in focus. async function unfinishedActiveWork(root) { const state = await getCurrentState(root); if (!state.activeWork) return null; const metaFile = path.join(workspacePath(root), 'work', state.activeWork, 'meta.yaml'); if (!await exists(metaFile)) return null; const active = await readYaml(metaFile); return active.status === 'DONE' ? null : active.id; } // v1.2.0: the work item a console request already created (request IDs make retries safe). // Called under the workspace lock, so a concurrent retry sees the first one's item. export async function findWorkByRequestId(root, requestId) { const workDir = path.join(workspacePath(root), 'work'); if (!requestId || !await exists(workDir)) return null; for (const entry of await readdir(workDir, { withFileTypes: true })) { if (!entry.isDirectory()) continue; const metaFile = path.join(workDir, entry.name, 'meta.yaml'); if (!await exists(metaFile)) continue; try { const meta = await readYaml(metaFile); if (meta.attestation?.requestId === requestId) return meta; } catch { // an unreadable item cannot own this request; doctor reports it } } return null; } // v1.2.0 `yallaflow activate `: the only explicit way to change which work item // is this checkout's active focus. It clears a deferral and changes no other record. export async function activateWorkItem(root, workId) { const metaFile = path.join(workspacePath(root), 'work', workId, 'meta.yaml'); if (!await exists(metaFile)) throw new Error(`Work item ${workId} was not found.`); const meta = await readYaml(metaFile); if (meta.status === 'DONE') throw new Error(`${workId} is DONE. Reopen it with \`yallaflow reopen\` to work on it again.`); assertProgressAllowed(meta, 'activating it'); const state = await getCurrentState(root); const previous = state.activeWork ?? null; const now = new Date().toISOString(); if (meta.activation?.deferred) { meta.activation = { ...meta.activation, deferred: false, activatedAt: now }; meta.updatedAt = now; await writeYaml(metaFile, meta); } await writeCurrentState(root, { schemaVersion: 1, activeWork: workId, stage: meta.routingStatus === 'pending' ? null : meta.status, updatedAt: now }); if (previous !== workId) await appendRedactedText(path.join(workspacePath(root), 'work', workId, 'progress.md'), `- ${now} Activated: now the active work item${previous ? ` (was ${previous})` : ''}\n`, 'utf8'); return { id: workId, previous }; } export async function routeWorkItem(root, workId, input) { const decision = validateRoutingDecision(input); const policy = resolveWorkflowPolicy(decision.work_type, decision.scope); const workDir = path.join(workspacePath(root), 'work', workId); const metaFile = path.join(workDir, 'meta.yaml'); if (!await exists(metaFile)) throw new Error(`Work item ${workId} was not found.`); const meta = await readYaml(metaFile); if (meta.routingStatus !== 'pending') { throw new Error(`${workId} is not awaiting routing.`); } // A pending intake created before the gate (or by an older YallaFlow) is not routed // into normal engineering work until project understanding is approved. await assertEngineeringWorkAllowed(root, { request: meta.rawRequest }); const now = new Date().toISOString(); const behaviorContract = { registryVersion: REGISTRY_VERSION, skills: resolveSkills(policy.requiredCapabilities) }; const title = decision.title ?? meta.titleHint ?? `${capitalize(decision.work_type)} work`; Object.assign(meta, { title, type: decision.work_type, scope: decision.scope, routingStatus: 'routed', routingConfidence: decision.confidence, routingReason: decision.reason, routedAt: now, workflow: policy.workflow, requiredCapabilities: policy.requiredCapabilities, behaviorContract, status: policy.initialStage, readOnly: policy.readOnly, updatedAt: now }); await writeYaml(metaFile, meta); const workFile = path.join(workDir, 'work.md'); const currentWork = await readText(workFile); await writeRedactedText(workFile, currentWork.replace(/^# .*$/m, `# ${meta.id} — ${title}`)); await appendRedactedText(workFile, routedWorkAppendix(meta), 'utf8'); await appendRedactedText(path.join(workDir, 'progress.md'), `- ${now} Routing: routed as ${meta.type} + ${meta.scope} (${meta.routingConfidence})\n`, 'utf8'); // A deferred item (created with --keep-active) never takes the checkout's focus by being // routed; only `yallaflow activate` does. Everything else keeps the pre-1.2.0 behavior. if (!meta.activation?.deferred) { await writeCurrentState(root, { schemaVersion: 1, activeWork: workId, stage: policy.initialStage, updatedAt: now }); } return meta; } // Attaches an additional source to an existing work item (pending or already routed) // without disturbing anything else about it — the missing half of the source-input // model that per-file `intake` alone doesn't cover (`yallaflow intake add`). // Every link records when it was made and the work's status at that moment. A source // attached after DONE is a recovered source: it requires a reason, is marked as such, // and never reopens or rewrites the completed work — work.md (the historical record of // the work as executed) is left untouched; only the append-only progress ledger and // the source list gain an entry, so it can never look as if it existed during // execution. export function assertSourceLinkAllowed(meta, reason) { if (meta.status === 'DONE' && !isNonEmptyString(reason)) { throw new Error( `${meta.id} is DONE. Attaching a source now records it as a recovered source (added after completion) and requires --reason, ` + `e.g. yallaflow intake add ${meta.id} --reason "Original screenshot from the request was not captured during the work."\n\nNo files were changed.` ); } } export async function addSourceToWork(root, workId, source, now = new Date().toISOString(), { reason } = {}) { const workDir = path.join(workspacePath(root), 'work', workId); const metaFile = path.join(workDir, 'meta.yaml'); if (!await exists(metaFile)) throw new Error(`Work item ${workId} was not found.`); const meta = await readYaml(metaFile); assertSourceLinkAllowed(meta, reason); const recovered = meta.status === 'DONE'; const validated = validateSourceRef({ ...source, linkedAt: now, workStatusAtLink: meta.routingStatus === 'pending' ? 'PENDING' : meta.status, relationship: recovered ? 'recovered-source' : 'work-input', ...(isNonEmptyString(reason) ? { reason: reason.trim() } : {}) }); // v0.3.8: a source attached after the approved intent was fixed may change it. The // CLI cannot know whether it does, so it raises a pending impact (before the link is // written) for the Agent to assess; it never judges the source's meaning. if (!recovered && meta.routingStatus === 'routed') { const progress = await loadWorkProgress(root, meta); if (intentFixed(meta, progress.contract, progress.ledger)) await raiseImpact(root, meta, { type: 'source', source: validated.id }, now); } meta.sources = [...(meta.sources ?? []), validated]; meta.updatedAt = now; await writeYaml(metaFile, meta); if (recovered) { await appendRedactedText(path.join(workDir, 'progress.md'), `- ${now} Recovered source attached after DONE: ${validated.id} (${validated.name}) — ${validated.reason}\n`, 'utf8'); } else { await appendRedactedText(path.join(workDir, 'work.md'), sourceAddedSection(validated), 'utf8'); await appendRedactedText(path.join(workDir, 'progress.md'), `- ${now} Source attached: ${validated.id} (${validated.name})\n`, 'utf8'); } return meta; } // Shared by revision and the read model. Classification alone does not start work; // leaving INTAKE or recording checkpoint activity does. History also prevents a // checkpoint reset from making previously started work editable again. export function canReviseRequest(meta, progress = null) { if (['on_hold', 'closed'].includes(meta.lifecycle?.state) || meta.status === 'DONE') return false; if (meta.routingStatus === 'pending') return true; if (meta.status !== 'INTAKE' || !progress) return false; return !progress.ledger.history?.length && Object.values(progress.ledger.skills).every( (checkpoint) => checkpoint.status === 'pending' && !checkpoint.startedAt && !checkpoint.completedAt ); } // The canonical, audited correction path before work starts. Sources, the classified // title and workflow stay intact; earlier request versions remain durable history. export async function reviseRequest(root, workId, input, now = new Date().toISOString()) { const workDir = path.join(workspacePath(root), 'work', workId); const metaFile = path.join(workDir, 'meta.yaml'); if (!await exists(metaFile)) throw new Error(`Work item ${workId} was not found.`); const meta = await readYaml(metaFile); assertProgressAllowed(meta, 'revising its request'); const progress = meta.routingStatus === 'pending' ? null : await loadWorkProgress(root, meta); if (!canReviseRequest(meta, progress)) { throw new Error(`${workId} has already started; its request can only be edited before work starts (pending or untouched INTAKE).`); } if (!isNonEmptyString(input.text)) throw new Error('--text must be a non-empty replacement request.'); if (!isNonEmptyString(input.reason)) throw new Error('Revising a request requires a non-empty --reason.'); const previousRequest = meta.rawRequest; const nextRequest = input.text.trim(); meta.requestHistory = [...(meta.requestHistory ?? []), { previousRequest, reason: input.reason.trim(), revisedAt: now }]; meta.rawRequest = nextRequest; meta.updatedAt = now; await writeYaml(metaFile, meta); await appendRedactedText(path.join(workDir, 'work.md'), requestRevisedSection(previousRequest, nextRequest, input.reason, now), 'utf8'); await appendRedactedText(path.join(workDir, 'progress.md'), `- ${now} Request revised: ${input.reason.trim()}\n`, 'utf8'); return meta; } function requestRevisedSection(previousRequest, nextRequest, reason, now) { return `\n## Request Revised\n\n**Previous request:** ${previousRequest}\n**Revised request:** ${nextRequest}\n**Reason:** ${reason.trim()}\n**Timestamp:** ${now}\n`; } function pendingWorkTemplate(meta) { const intakeSection = meta.sources?.length ? `## Sources\n\n${meta.sources.map(sourceDetail).join('\n\n')}\n` : `## Raw Request\n\n${meta.rawRequest}\n`; return `# ${meta.id} — Pending Intake\n\n${intakeSection}\n## Routing\n\n**Status:** pending\n\nThe coding agent must classify this request using the YallaFlow routing contract.\n`; } export const SOURCE_RELATIONSHIPS = Object.freeze(['work-input', 'recovered-source']); function sourceAddedSection(source) { return `\n## Source Added\n\n${sourceDetail(source)}\n`; } function sourceDetail(source) { return `**Source ID:** ${source.id}\n**Type:** ${source.type}\n**Name:** ${source.name}\n\nRaw source preserved in: \`.yallaflow/sources/${source.id}/${source.name}\`. Read it directly; it is not duplicated here.`; } function validateSourceRef(source) { if (!source || typeof source !== 'object' || Array.isArray(source)) throw new Error('source must be an object.'); const { id, type, name, detectedFormat, contentAvailability, linkedAt, workStatusAtLink, relationship, reason } = source; if (!isNonEmptyString(id) || !isNonEmptyString(type) || !isNonEmptyString(name)) { throw new Error('source requires non-empty id, type, and name.'); } if (relationship !== undefined && !SOURCE_RELATIONSHIPS.includes(relationship)) { throw new Error(`source relationship must be one of: ${SOURCE_RELATIONSHIPS.join(', ')}.`); } return { id, type, name, ...(detectedFormat !== undefined ? { detectedFormat } : {}), ...(contentAvailability !== undefined ? { contentAvailability } : {}), // v0.3.6 link audit metadata (absent on earlier links, which are treated as work inputs). ...(linkedAt !== undefined ? { linkedAt } : {}), ...(workStatusAtLink !== undefined ? { workStatusAtLink } : {}), ...(relationship !== undefined ? { relationship } : {}), ...(reason !== undefined ? { reason } : {}) }; } function normalizeTitleHint(value) { if (!isNonEmptyString(value)) throw new Error('titleHint must be a non-empty string when supplied.'); return value.trim(); } function isNonEmptyString(value) { return typeof value === 'string' && value.trim().length > 0; } function routedWorkAppendix(meta) { return `\n## Routing Decision\n\n**Status:** routed\n**Work type:** ${meta.type}\n**Scope:** ${meta.scope}\n**Confidence:** ${meta.routingConfidence}\n**Reason:** ${meta.routingReason}\n**Timestamp:** ${meta.routedAt}\n**Workflow:** ${meta.workflow}\n**Required capabilities:** ${meta.requiredCapabilities.join(', ')}\n**Behavior contract:** registry v${meta.behaviorContract.registryVersion}\n**Skills:** ${meta.behaviorContract.skills.join(', ')}\n**Read-only:** ${meta.readOnly ? 'yes' : 'no'}\n\n${workSections(meta.workflow, meta.scope)}`; } function capitalize(value) { return `${value[0].toUpperCase()}${value.slice(1)}`; }