@gitroll/tacitt-cli 0.1.0 → 0.2.0

package/skills/tacitt/scripts/journey.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto'
-import { mkdir, realpath } from 'node:fs/promises'
+import { mkdir, realpath, rm } from 'node:fs/promises'
 import { join, resolve, isAbsolute } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
@@ -18,10 +18,15 @@ import {
   resolutionEvidence,
   planResolutions,
   assertResolutionFresh,
+  uncoveredPending,
 } from './journey-state.mjs'
 import { classificationTasks } from './journey-classification-tasks.mjs'
 import { classificationEvidence, classificationFormat } from './journey-classification.mjs'
-import { consolidateClassification, classificationSubmission } from './journey-consolidation.mjs'
+import {
+  consolidateClassification,
+  classificationSubmission,
+  partialClassificationSubmission,
+} from './journey-consolidation.mjs'
 import { consolidateCards, cardSubmission } from './journey-card-consolidation.mjs'
 import {
   classificationProgress,
@@ -127,8 +132,50 @@ function packagingProgress(view) {
   }
 }
 
-async function runPhaseCore({ run, journeyId, command, stage, refresh = false, limit = 3 }, call) {
+/** One await call's bound: inside a 10-minute tool timeout; the Skill repeats it to 30 minutes. */
+export const maxAwaitMs = 540_000
+const awaitPollMs = 1000
+
+/**
+ * D0: the agent waits inside its turn for the person's next panel decision. Returns once the
+ * helper phase changes (consent recorded, the last card answered, a Work moved out of Drop
+ * needing a read) or a new card batch is due, else after `waitMs` with `changed: false`.
+ */
+async function awaitDecision(journeyId, waitMs, call, sleep) {
+  if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > maxAwaitMs)
+    throw new Error('INVALID_ARGUMENTS')
+  const started = Date.now()
+  let view = await call('journey.get', { journeyId })
+  const from = phaseOf(view)
+  for (;;) {
+    const phase = phaseOf(view)
+    const batchDue = phase === 'browser-answers' && uncoveredPending(view).length > 0
+    if (phase !== from || batchDue || Date.now() - started >= waitMs)
+      return {
+        command: 'await',
+        from,
+        phase,
+        changed: phase !== from || batchDue,
+        waitedMs: Date.now() - started,
+        revision: view.revision,
+      }
+    await sleep(Math.min(awaitPollMs, Math.max(0, waitMs - (Date.now() - started))))
+    view = await call('journey.get', { journeyId })
+  }
+}
+
+async function runPhaseCore(
+  { run, journeyId, command, stage, refresh = false, limit = 3, waitMs = 0, sleep },
+  call,
+) {
   if (!Number.isSafeInteger(limit) || limit < 1 || limit > 16) throw new Error('INVALID_ARGUMENTS')
+  if (command === 'await')
+    return awaitDecision(
+      journeyId,
+      waitMs,
+      call,
+      sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    )
   let view = await call('journey.get', { journeyId })
   if (command === 'scan-start')
     return {
@@ -197,25 +244,73 @@ async function runPhaseCore({ run, journeyId, command, stage, refresh = false, l
   const consolidationRefresh = refresh && command === 'consolidate' && stage === 'classification'
   if (
     consolidationRefresh &&
-    !['classification', 'classification-confirmation'].includes(phaseOf(view))
+    !['classification', 'classification-confirmation'].includes(phaseOf(view)) &&
+    !grouping(view)
   )
     throw new Error('STAGE_NOT_READY')
   if (consolidationRefresh && (await optional(join(active?.directory ?? run, 'receipt.json'))))
     throw new Error('CLASSIFICATION_ALREADY_SUBMITTED')
+  // A card batch (D3) whose append was accepted is finished: the next `tasks` starts another.
+  const batchDone =
+    stage === 'cards' &&
+    manifest?.batch &&
+    ['applied', 'replayed'].includes(
+      (await optional(join(active.directory, 'receipt.json')))?.status,
+    )
+  if (batchDone && command !== 'tasks') return { stage, status: 'applied', batchDone: true }
+  if (batchDone) manifest = null
   const fingerprint = stageFingerprint(view, stage)
   if (manifest?.resolutionBatches && !refresh)
     await assertResolutionFresh(active.directory, manifest, view)
-  else if (manifest && manifest.fingerprint !== fingerprint && (!refresh || consolidationRefresh))
+  // A batch names its own open values; the CLI refuses them once they are no longer open.
+  // Known Works this helper published (E2) changed the Works it fingerprinted.
+  else if (
+    manifest &&
+    !manifest.batch &&
+    !manifest.partial &&
+    manifest.fingerprint !== fingerprint &&
+    (!refresh || consolidationRefresh)
+  )
     throw new Error('STALE_TASKS')
   if (refresh && command !== 'tasks' && !consolidationRefresh) throw new Error('INVALID_ARGUMENTS')
   if (command === 'tasks') {
     const phase = phaseOf(view)
     const revisingCards =
       stage === 'cards' && refresh && ['browser-answers', 'answers-confirmation'].includes(phase)
+    // Batches start while reading continues and after earlier batches (D3).
+    const cardBatch =
+      stage === 'cards' &&
+      !refresh &&
+      view.scope.status === 'confirmed' &&
+      !['paused', 'sending', 'completed'].includes(phase) &&
+      uncoveredPending(view).length > 0
+    if (cardBatch && !manifest) {
+      const directory = join(run, stage, `batch-${randomUUID()}`)
+      await mkdir(directory, { recursive: true, mode: 0o700 })
+      manifest = {
+        format: classificationFormat,
+        stage,
+        batch: true,
+        fingerprint,
+        existingCards: view.privacy.cards.map((card) => ({
+          id: card.id,
+          question: card.question,
+          options: card.options.map(({ id, label }) => ({ id, label })),
+          answer: card.answer?.optionId ?? null,
+          termCount: card.termKeys.length,
+        })),
+        tasks: await createTasks(directory, stage, view, call, { batch: true }),
+        answersRevision: view.privacy.answersRevision,
+      }
+      await save(join(directory, 'manifest.json'), manifest)
+      await save(activePath, { directory })
+      return { stage, tasks: manifest.tasks, batch: true }
+    }
     if (
       phase !== stage &&
       !revisingCards &&
-      !(stage === 'classification' && phase === 'classification-confirmation')
+      !(cardBatch && manifest) &&
+      !(stage === 'classification' && (phase === 'classification-confirmation' || grouping(view)))
     )
       throw new Error('STAGE_NOT_READY')
     if (manifest && !refresh && stage === 'classification') {
@@ -318,6 +413,15 @@ async function runPhaseCore({ run, journeyId, command, stage, refresh = false, l
       total: manifest.resolutionBatches.length,
     }
   }
+  if (stage === 'classification' && command === 'ingest' && !manifest.partial) {
+    const readiness = manifest.consolidation
+      ? await consolidateClassification(directory, manifest)
+      : { readyForIngest: false }
+    if (!readiness.readyForIngest) {
+      const partial = await partialClassificationSubmission(manifest)
+      if (partial) return ingestKnownWorks(directory, manifest, view, call, partial)
+    }
+  }
   if (stage === 'classification' && !manifest.consolidation)
     throw new Error('CONSOLIDATION_REQUIRED')
   if (stage === 'classification') {
@@ -334,12 +438,15 @@ async function runPhaseCore({ run, journeyId, command, stage, refresh = false, l
     journeyId,
     expectedRevision: view.revision,
     idempotencyKey: randomUUID(),
-    [key]:
-      stage === 'classification'
-        ? await classificationSubmission(manifest, view)
-        : stage === 'cards'
-          ? await cardSubmission(manifest)
-          : await answers(tasks, key),
+    // After the known Works, scans keep moving the revision: bind to the classification (E2).
+    ...(stage === 'classification' && manifest.partial
+      ? { expectedClassificationRevision: manifest.partial.revision }
+      : {}),
+    ...(stage === 'classification'
+      ? { [key]: await classificationSubmission(manifest, view) }
+      : stage === 'cards'
+        ? await cardSubmission(manifest)
+        : { [key]: await answers(tasks, key) }),
     ...(stage === 'resolution' ? { answersRevision: manifest.answersRevision } : {}),
   }
   await save(join(directory, 'request.json'), request)
@@ -359,13 +466,45 @@ async function runPhaseCore({ run, journeyId, command, stage, refresh = false, l
     throw error
   }
   if (result.status === 'stale') throw new Error('REVISION_CONFLICT')
-  if (stage === 'classification') {
+  if (stage === 'classification' && !manifest.partial) {
     const latest = await call('journey.get', { journeyId })
     await publishCompleteClassification(manifest, latest, call, result.state?.revision)
   }
   return { stage, status: result.status, revision: result.state?.revision }
 }
 
+/** Classification published known Works and is still grouping the remaining roots (E2). */
+const grouping = (view) => view.works.some((work) => work.placement === 'classifying')
+
+/**
+ * E2: publishes known-project Works while unresolved roots are still being grouped, so their
+ * scan can start. Its request and receipt are kept apart from the final proposal's.
+ */
+async function ingestKnownWorks(directory, manifest, view, call, partial) {
+  const requestPath = join(directory, 'partial.request.json')
+  const request = (await optional(requestPath)) ?? {
+    journeyId: view.journeyId,
+    expectedRevision: view.revision,
+    idempotencyKey: randomUUID(),
+    ...partial,
+  }
+  await save(requestPath, request)
+  const result = await call(procedureFor('classification'), request)
+  if (result.status === 'stale') {
+    await rm(requestPath, { force: true })
+    throw new Error('REVISION_CONFLICT')
+  }
+  manifest.partial = { status: result.status, revision: result.state?.revision }
+  await save(join(directory, 'manifest.json'), manifest)
+  return {
+    stage: 'classification',
+    status: result.status,
+    partial: true,
+    pendingRoots: partial.pendingRootSessionIds.length,
+    revision: result.state?.revision,
+  }
+}
+
 const terminalClassificationErrors = new Set([
   'INVALID_SELECTION',
   'CLASSIFICATION_PROJECT_NAME_CONFLICT',
@@ -410,6 +549,7 @@ export async function main(argv) {
       stage: { type: 'string' },
       refresh: { type: 'boolean', default: false },
       limit: { type: 'string' },
+      'wait-ms': { type: 'string' },
       model: { type: 'string' },
       effort: { type: 'string' },
     },
@@ -434,6 +574,7 @@ export async function main(argv) {
         stage: values.stage,
         refresh: values.refresh,
         limit: values.limit === undefined ? 3 : Number(values.limit),
+        waitMs: values['wait-ms'] === undefined ? 300_000 : Number(values['wait-ms']),
       },
       call,
     ),

package/skills/tacitt/scripts/privacy-validator.mjs

@@ -9468,13 +9468,18 @@ const decisionCardInputSchema = object({
 		id: _enum(["hide", "keep"]),
 		label: string().trim().min(1).max(240),
 		rule: string().trim().min(1).max(2e3)
-	}).strict()).length(2).refine((options) => new Set(options.map((option) => option.id)).size === 2, { message: "Decision cards require one hide option and one keep option." })
+	}).strict()).length(2).refine((options) => new Set(options.map((option) => option.id)).size === 2, { message: "Decision cards require one hide option and one keep option." }),
+	suggestion: object({
+		optionId: _enum(["hide", "keep"]),
+		source: string().trim().min(1).max(300)
+	}).strict().optional()
 }).strict();
 const decisionCardSchema = decisionCardInputSchema.extend({ answer: object({
 	optionId: string(),
 	rule: string().max(4001),
 	additionalRule: string().max(2e3),
-	remember: boolean()
+	remember: boolean(),
+	excludedTermKeys: array(string().min(1)).max(2e4).optional()
 }).strict().nullable() }).strict();
 const journeyPrivacySchema = object({
 	terms: array(privacyTermSchema),
@@ -9490,7 +9495,14 @@ const write = object({
 	expectedRevision: count$2,
 	idempotencyKey: uuid()
 });
-write.extend({ cards: array(decisionCardInputSchema).max(20) }).strict();
+write.extend({
+	cards: array(decisionCardInputSchema).max(20),
+	mode: _enum(["replace", "append"]).optional(),
+	extend: array(object({
+		cardId: uuid(),
+		termKeys: array(string().min(1)).min(1).max(2e4)
+	}).strict()).max(20).optional()
+}).strict();
 const privacyResolveSchema = write.extend({
 	answersRevision: count$2,
 	resolutions: array(privacyTermSchema.omit({ sources: true }).extend({ disposition: _enum(["hidden", "keep"]) }).strict()).min(1).max(2e4)
@@ -9500,7 +9512,8 @@ object({
 	cardId: uuid(),
 	optionId: string().min(1),
 	rule: string().max(2e3).optional(),
-	remember: boolean()
+	remember: boolean(),
+	excludedTermKeys: array(string().min(1)).max(2e4).optional()
 }).strict();
 object({
 	kind: literal("cards-confirm"),
@@ -9815,7 +9828,11 @@ const journeyWorkSchema = object({
 		"explicit",
 		"delegate"
 	]),
-	placement: _enum(["placed", "unsorted"]),
+	placement: _enum([
+		"placed",
+		"unsorted",
+		"classifying"
+	]),
 	suggestion: journeyWorkSuggestionSchema.nullable(),
 	classificationRecommendation: object({
 		access: journeyAccessSchema,
@@ -9862,7 +9879,9 @@ const journeyWorkSchema = object({
 	staticReview: object({
 		snapshotId: journeyDigestSchema,
 		inputRevision: count$1.min(1),
-		digest: journeyDigestSchema
+		digest: journeyDigestSchema,
+		/** Images the Work's sessions leave out (D7); absent when a session receipt predates it. */
+		imagesOmitted: count$1.optional()
 	}).strict().optional(),
 	totalBatches: count$1,
 	completedBatches: count$1,

package/skills/tacitt/scripts/review.mjs

@@ -1,4 +1,4 @@
-import { phaseOf } from './journey-state.mjs'
+import { cardBatchOpen, phaseOf, uncoveredPending } from './journey-state.mjs'
 import { startReviewStream } from './review-stream-client.mjs'
 import { createHash, randomUUID } from 'node:crypto'
 import {
@@ -398,7 +398,7 @@ export function renderGuidance(guidance) {
         "## The person's instructions",
         'A hide instruction is a requirement: report every value it covers under the closest type. A keep instruction is context, not proof that other text is public.',
         instructions.join('\n') || '(none)',
-        'Remembered rules (apply only when the context fits):',
+        'Remembered rules and answered questions (apply only when the context fits). A value that fits an answered question takes its answer: disposition hidden for Hide, keep for Keep, not pending.',
         ...(guidance?.rules ?? []),
       ].join('\n\n'),
     ) + '\n'
@@ -1317,7 +1317,7 @@ const termRequest = (ctx, units, terms, completeUnits = true) => ({
 
 /** Per-Work scan progress; final preview and render also require the Work's Track B review. */
 export function workProgress(view) {
-  const finalPreview = ['final-preview-and-confirmation', 'package', 'send'].includes(phaseOf(view))
+  const finalPreview = ['ready-to-send', 'send'].includes(phaseOf(view))
   return view.works.map((work) => {
     const selected = work.access !== 'drop' && work.rootSessionIds.length > 0
     const proof = work.emptyReview
@@ -1384,9 +1384,12 @@ export function questionsReady(view) {
 /** Reading and question state after this command's recordings. */
 async function progressOf(ctx) {
   const view = await call(ctx, 'journey.get', { journeyId: ctx.journeyId })
+  const uncovered = uncoveredPending(view).length
   return {
     readingComplete: view.readingComplete,
     questionsReady: questionsReady(view),
+    // E3: a card is raised as soon as a value needs one, unless a batch is still being drafted.
+    cardBatch: { uncovered, ready: uncovered > 0 && !(await cardBatchOpen(ctx.run)) },
     works: workProgress(view),
     blockedWorks: blockedWorks(view),
   }
@@ -1512,6 +1515,24 @@ export async function withJourneyCli(run, operation) {
   }
 }
 
+/**
+ * A CLI binding without the run lock, for a child that only publishes progress (BL-202) while
+ * the agent's helper holds the lock.
+ */
+export async function withUnlockedJourneyCli(run, operation) {
+  const config = await readJson(join(run, 'config.json'), null)
+  if (!config) fail('RUN_NOT_INITIALIZED')
+  const ctx = { run, config, journeyId: config.journeyId }
+  try {
+    return await operation(
+      (procedure, input, options) => call(ctx, procedure, input, options),
+      config,
+    )
+  } finally {
+    await Promise.all((ctx.streams ?? []).map((item) => item.close()))
+  }
+}
+
 export async function main(argv) {
   const { values, positionals } = parseArgs({
     args: argv,