@gitroll/tacitt-cli 0.1.0 → 0.3.0

package/skills/tacitt/scripts/journey-classification-validation.mjs

@@ -1,40 +1,61 @@
 const types = ['work', 'side', 'coursework', 'personal', 'scratch', 'other']
 const access = ['public', 'private', 'drop']
+const unknownField = (value, allowed) => {
+  const field = Object.keys(value).find((name) => !allowed(name))
+  return field && `unknown field ${field}`
+}
 const text = (value, max) =>
   typeof value === 'string' && value.trim().length > 0 && value.length <= max
 
 export function validateClassificationJudgment(value, key) {
-  if (
-    !value ||
-    value.rootKey !== key ||
-    !text(value.projectName, 240) ||
-    !text(value.workIntent, 240) ||
-    !text(value.groupingBasis, 200) ||
-    (value.targetProjectId !== undefined &&
-      (typeof value.targetProjectId !== 'string' || !value.targetProjectId)) ||
-    Object.keys(value).some(
-      (field) =>
-        !['rootKey', 'projectName', 'workIntent', 'groupingBasis', 'targetProjectId'].includes(
-          field,
-        ),
-    )
-  )
-    throw new Error('CLASSIFICATION_JUDGMENT_INVALID')
+  const problem = !value
+    ? 'missing'
+    : value.rootKey !== key
+      ? 'rootKey does not match'
+      : !text(value.projectName, 240)
+        ? 'projectName must be 1-240 characters'
+        : !text(value.workIntent, 240)
+          ? 'workIntent must be 1-240 characters'
+          : !text(value.groupingBasis, 200)
+            ? 'groupingBasis must be 1-200 characters'
+            : value.targetProjectId !== undefined &&
+                (typeof value.targetProjectId !== 'string' || !value.targetProjectId)
+              ? 'targetProjectId must be a non-empty string'
+              : unknownField(value, (field) =>
+                  [
+                    'rootKey',
+                    'projectName',
+                    'workIntent',
+                    'groupingBasis',
+                    'targetProjectId',
+                  ].includes(field),
+                )
+  if (problem)
+    throw new Error('CLASSIFICATION_JUDGMENT_INVALID', {
+      cause: problem,
+    })
 }
 
 export function validateClassificationProject(value, projectId) {
-  if (
-    !value ||
-    value.projectId !== projectId ||
-    !text(value.description, 1000) ||
-    !types.includes(value.projectType) ||
-    !access.includes(value.recommendation?.access) ||
-    !text(value.recommendation?.reason, 200) ||
-    Object.keys(value).some(
-      (field) => !['projectId', 'description', 'projectType', 'recommendation'].includes(field),
-    )
-  )
-    throw new Error('PROJECT_METADATA_INVALID')
+  const problem = !value
+    ? 'missing'
+    : value.projectId !== projectId
+      ? 'projectId does not match'
+      : !text(value.description, 1000)
+        ? 'description must be 1-1000 characters'
+        : !types.includes(value.projectType)
+          ? `projectType must be one of ${types.join(', ')}`
+          : !access.includes(value.recommendation?.access)
+            ? `recommendation.access must be one of ${access.join(', ')}`
+            : !text(value.recommendation?.reason, 200)
+              ? 'recommendation.reason must be 1-200 characters'
+              : unknownField(value, (field) =>
+                  ['projectId', 'description', 'projectType', 'recommendation'].includes(field),
+                )
+  if (problem)
+    throw new Error('PROJECT_METADATA_INVALID', {
+      cause: problem,
+    })
 }
 
 export function validateConsolidationAnswer(answer, descriptor) {

package/skills/tacitt/scripts/journey-classification.mjs

@@ -74,9 +74,13 @@ export async function classificationEvidence(directory, manifest, view, call, li
       const root = state.roots.find((entry) => entry.key === key)
       const source = state.unknown.find((entry) => entry.rootKey === key)
       if (!root || !source) throw new Error('INVALID_EVIDENCE_ROOTS')
+      // After the known Works (E2), unresolved roots sit in the "Still being grouped" Work.
+      const workId =
+        view.works.find((work) => work.rootSessionIds?.includes(root.rootSessionId))?.id ??
+        root.workId
       const page = await call('journey.classificationSessions', {
         journeyId: view.journeyId,
-        workId: root.workId,
+        workId,
         includeProjectEvidence: true,
         projectEvidenceRootSessionIds: [root.rootSessionId],
         rootsOnly: true,
@@ -97,7 +101,7 @@ export async function classificationEvidence(directory, manifest, view, call, li
         for (let pageNumber = 0; pageNumber < 2; pageNumber++) {
           const content = await call('journey.classificationRead', {
             journeyId: view.journeyId,
-            workId: root.workId,
+            workId,
             rootSessionId: root.rootSessionId,
             ...(cursor ? { cursor } : {}),
           })

package/skills/tacitt/scripts/journey-consolidation-submit.mjs

@@ -1,17 +1,15 @@
 import { readFile } from 'node:fs/promises'
 import { createHash } from 'node:crypto'
 import { answers } from './journey-tasks.mjs'
+import { optional } from './journey-state.mjs'
 import {
   validateClassificationProject,
   validateConsolidationAnswer,
   compileAssignments,
 } from './journey-classification-validation.mjs'
 
-/** Expand short handles and fixed catalog membership only after exact coverage validation. */
-export async function classificationSubmission(manifest) {
-  const classification = manifest.classification
-  if (!classification?.complete || !manifest.consolidation)
-    throw new Error('CONSOLIDATION_REQUIRED')
+/** Known-project Works with their fixed catalog membership and answered metadata. */
+async function knownProjects(classification, manifest) {
   const projectMetadata = new Map()
   for (const item of manifest.tasks.filter((entry) => entry.projectKeys)) {
     const results = await answers([item], 'items')
@@ -49,6 +47,40 @@ export async function classificationSubmission(manifest) {
       projectId: project.projectId,
     }
   })
+  return result
+}
+
+/**
+ * E2: once every known project has its metadata, its Works are published while the unresolved
+ * roots are still being grouped; they wait as `pendingRootSessionIds`. Null while metadata is
+ * missing or when nothing remains to group.
+ */
+export async function partialClassificationSubmission(manifest) {
+  const classification = manifest.classification
+  if (
+    !classification?.complete ||
+    !classification.unknown.length ||
+    !classification.projects.length
+  )
+    return null
+  for (const item of manifest.tasks.filter((entry) => entry.projectKeys))
+    if (!(await optional(item.answer))) return null
+  const known = await knownProjects(classification, manifest)
+  const rootByKey = new Map(classification.roots.map((root) => [root.key, root.rootSessionId]))
+  const pendingRootSessionIds = classification.unknown.map((item) => {
+    const id = rootByKey.get(item.rootKey)
+    if (!id) throw new Error('CLASSIFICATION_ROOT_COVERAGE_INVALID')
+    return id
+  })
+  return { items: normalized(known), pendingRootSessionIds }
+}
+
+/** Expand short handles and fixed catalog membership only after exact coverage validation. */
+export async function classificationSubmission(manifest) {
+  const classification = manifest.classification
+  if (!classification?.complete || !manifest.consolidation)
+    throw new Error('CONSOLIDATION_REQUIRED')
+  const result = await knownProjects(classification, manifest)
   let answerText
   let unknown
   if (manifest.consolidation.automatic) unknown = { groups: [], assignments: {} }
@@ -171,6 +203,11 @@ export async function classificationSubmission(manifest) {
     JSON.stringify(expectedRootIds) !== JSON.stringify(submittedRootIds)
   )
     throw new Error('CLASSIFICATION_ROOT_COVERAGE_INVALID')
+  return normalized(result)
+}
+
+/** Trimmed submission items; one project name never carries two different metadata sets. */
+function normalized(result) {
   const normalizedNames = new Map()
   const output = result.map(({ projectId: _projectId, ...item }) => ({
     ...item,

package/skills/tacitt/scripts/journey-consolidation.d.mts

@@ -7,3 +7,8 @@ export function consolidateClassification(
 export function classificationSubmission(
   manifest: Record<string, unknown>,
 ): Promise<Array<Record<string, unknown>>>
+
+export function partialClassificationSubmission(manifest: Record<string, unknown>): Promise<{
+  items: Array<Record<string, unknown>>
+  pendingRootSessionIds: string[]
+} | null>

package/skills/tacitt/scripts/journey-consolidation.mjs

@@ -221,4 +221,7 @@ export async function consolidateClassification(directory, manifest, { refresh =
   }
 }
 
-export { classificationSubmission } from './journey-consolidation-submit.mjs'
+export {
+  classificationSubmission,
+  partialClassificationSubmission,
+} from './journey-consolidation-submit.mjs'

package/skills/tacitt/scripts/journey-panel-host.d.mts

@@ -0,0 +1,9 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process'
+
+export function ensureDetachedHost(
+  cli: string[],
+  journeyId: string,
+  options?: {
+    spawnChild?: (command: string, args: string[], options: SpawnOptions) => ChildProcess
+  },
+): Promise<{ url: string; pid: number; started: boolean }>

package/skills/tacitt/scripts/journey-panel-host.mjs

@@ -0,0 +1,56 @@
+import { spawn } from 'node:child_process'
+import { windowsArgument } from './review-stream-client.mjs'
+
+/** `journey.serve --detach` waits up to 60 s for the host; leave room for the CLI's startup. */
+const detachTimeoutMs = 90_000
+
+/**
+ * ADR 0227: before the agent ends its turn at Ready to send, a detached panel host must own the
+ * panel, because some agent hosts (Codex) stop the processes of a turn when it ends. Runs the
+ * paired CLI's `journey.serve --detach`, which reuses a detached host already serving the journey
+ * and otherwise starts one. Resolves `{url, pid, started}`; `started` means the panel moved to
+ * a new URL.
+ */
+export function ensureDetachedHost(cli, journeyId, { spawnChild = spawn } = {}) {
+  const [command, ...prefix] = cli
+  const shell = process.platform === 'win32' && !/\.(exe|com)$/iu.test(command)
+  const args = [...prefix, 'journey.serve', '--detach', '--input', '-']
+  return new Promise((resolve, reject) => {
+    const fail = () => reject(new Error('PANEL_HOST_DETACH_FAILED'))
+    const child = spawnChild(command, shell ? args.map(windowsArgument) : args, {
+      stdio: ['pipe', 'pipe', 'ignore'],
+      shell,
+    })
+    let output = ''
+    const timer = setTimeout(() => child.kill(), detachTimeoutMs)
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk) => (output += chunk))
+    child.once('error', () => {
+      clearTimeout(timer)
+      fail()
+    })
+    child.once('close', (code) => {
+      clearTimeout(timer)
+      const ready = output
+        .split('\n')
+        .flatMap((line) => {
+          try {
+            return [JSON.parse(line)]
+          } catch {
+            return []
+          }
+        })
+        .find((line) => line?.ok === true && line.event === 'ready')?.result
+      if (
+        code !== 0 ||
+        ready?.journeyId !== journeyId ||
+        typeof ready.url !== 'string' ||
+        !Number.isSafeInteger(ready.pid)
+      )
+        return fail()
+      resolve({ url: ready.url, pid: ready.pid, started: ready.reused !== true })
+    })
+    child.stdin.on('error', () => {})
+    child.stdin.end(JSON.stringify({ journeyId }))
+  })
+}

package/skills/tacitt/scripts/journey-state.d.mts

@@ -1,4 +1,5 @@
 export function save(path: string, value: unknown): Promise<void>
+export function cardBatchOpen(run: string): Promise<boolean>
 export function hash(value: unknown): string
 export function definiteWriteRejection(error: unknown): boolean
 export function stageFingerprint(view: unknown, stage: string): string

package/skills/tacitt/scripts/journey-state.mjs

@@ -36,7 +36,8 @@ export function phaseOf(view) {
   if (view.scope.status !== 'confirmed') return 'classification-confirmation'
   if (!view.readingComplete) return 'scan'
   const pending = activeTerms(view).some((term) => term.disposition === 'pending')
-  if (pending && !view.privacy.cards.length) return 'cards'
+  // Card batches (D3) leave values no card covers yet for the next batch.
+  if (uncoveredPending(view).length) return 'cards'
   if (view.privacy.cards.length) {
     if (view.privacy.cards.some((card) => !card.answer)) return 'browser-answers'
     if (view.privacy.confirmedAnswersRevision !== view.privacy.answersRevision)
@@ -46,20 +47,51 @@ export function phaseOf(view) {
   const selected = view.works.filter((work) => work.access !== 'drop' && work.rootSessionIds.length)
   // Track B builds each Work's private packaging base in the background (ADR 0171).
   if (selected.some((work) => !work.staticReview)) return 'static-finishing'
-  if (!view.privacy.packageApproval) return 'final-preview-and-confirmation'
-  if (selected.some((work) => work.artifact?.revision !== work.revision)) return 'package'
+  // The person's Send click packages and uploads (D5); the agent has nothing left to run.
+  if (
+    !view.privacy.packageApproval ||
+    selected.some((work) => work.artifact?.revision !== work.revision)
+  )
+    return 'ready-to-send'
   return 'send'
 }
+/**
+ * A card batch (E3) whose append is not yet accepted. While one is open, newly uncovered values
+ * wait for the next batch, so cards come as soon as they are needed without overlapping.
+ */
+export async function cardBatchOpen(run) {
+  const active = await optional(join(run, 'cards-active.json'))
+  if (!active) return false
+  const manifest = await optional(join(active.directory, 'manifest.json'))
+  if (!manifest?.batch) return false
+  const receipt = await optional(join(active.directory, 'receipt.json'))
+  // A refused batch is retired and an emptied one finished: neither holds the next batch back.
+  return !['applied', 'replayed', 'skipped', 'rejected'].includes(receipt?.status)
+}
+/** Pending values that no published card covers yet: the input of the next card batch. */
+export function uncoveredPending(view) {
+  const covered = new Set(view.privacy.cards.flatMap((card) => card.termKeys))
+  return activeTerms(view).filter(
+    (term) =>
+      term.disposition === 'pending' &&
+      !covered.has(term.key ?? JSON.stringify([term.type, term.value?.normalize('NFC')])),
+  )
+}
+/**
+ * Classification tasks depend on grouping, not on scan progress: the known Works' scan keeps
+ * moving their input revision and the person may change access, so neither retires them.
+ */
 export function stageFingerprint(view, stage) {
+  const classification = stage === 'classification'
   return hash({
     snapshotId: view.snapshotId,
     guidance: view.guidanceDigest,
     works: view.works.map((work) => [
       work.id,
-      work.inputRevision,
+      classification ? null : work.inputRevision,
       work.rootSessionIds,
-      work.access,
-      stage === 'classification'
+      classification ? null : work.access,
+      classification
         ? [
             work.title,
             work.projectName,

package/skills/tacitt/scripts/journey-tasks.mjs

@@ -79,13 +79,15 @@ export async function answers(tasks, key) {
   }
   return entries
 }
-export async function createTasks(directory, stage, view, call) {
+export async function createTasks(directory, stage, view, call, { batch = false } = {}) {
   const tasks = [],
     journeyId = view.journeyId
   const cards = await call('journey.cardsRead', { journeyId })
   const guidance = stage === 'resolution' ? await call('review.guidance', { journeyId }) : null
+  // A card batch drafts only values no published card covers yet (D3).
+  const covered = new Set(batch ? cards.cards.flatMap((card) => card.termKeys) : [])
   const pending = cards.terms
-    .filter((term) => term.disposition === 'pending')
+    .filter((term) => term.disposition === 'pending' && !covered.has(term.key))
     .sort((a, b) => a.type.localeCompare(b.type))
   // Card drafting groups by meaning: a short ref replaces the long key, one excerpt replaces
   // full source evidence. The publisher maps refs back to exact keys.
@@ -120,7 +122,7 @@ export async function createTasks(directory, stage, view, call) {
   for (const group of groups) {
     const instruction =
       stage === 'cards'
-        ? 'INTERNAL decision-card drafting for Main (not browser publication): return {cards:[{id,question,examples,termRefs,options:[{id,label,rule}]}]}. Use UUID card IDs. termRefs lists the supplied term refs (for example "T12"); cover every supplied ref exactly once. Ask a concise contextual retention question with exactly two options: id hide (hide the covered values) and id keep (retain the covered values). Keep their rules meaningful for final resolution. Group by broad privacy-information category and shared retention policy. Specific projects, tools, filenames and capabilities belong in examples, not separate question topics. Main alone reads the complete candidate catalog and reconciles drafts globally into 5–10 final questions for the entire journey, never more than 20. Preserve coherent decision boundaries and exact disjoint keys; batch boundaries must never become final questions. Identify affected Work names only as context. Never answer for the person.'
+        ? "INTERNAL decision-card drafting for Main (not browser publication): return {cards:[{id,question,examples,termRefs,options:[{id,label,rule}]}]}. Use UUID card IDs. termRefs lists the supplied term refs (for example \"T12\"); cover every supplied ref exactly once. Write the question, option labels, rules and any context in English whatever language the conversation uses; keep example values exactly as they appear in the source. Ask a concise contextual retention question with exactly two options: id hide (hide the covered values) and id keep (retain the covered values). Keep their rules meaningful for final resolution. Group by broad privacy-information category and shared retention policy. Specific projects, tools, filenames and capabilities belong in examples, not separate question topics. Never put the person's own identity and other people on one card: an own-identity card covers only values tied to the person's own signals (own-identity terms, the session author, local account, own handle, email or domain); when unsure whose a value is, put it on the other-people card. Common review or chat jargon (for example LGTM, PTAL, nit, WIP) and generic words are not privacy values: never use them as examples or as a question's subject, and cover their refs on the card that fits the context they came from. Examples show short values, never sentences: list each value once, ignoring case, spacing, hyphens and underscores, and cut a long value with a trailing ellipsis. Main alone reads the complete candidate catalog and reconciles drafts globally into 5–10 final questions for the entire journey, never more than 20. Preserve coherent decision boundaries and exact disjoint keys; batch boundaries must never become final questions. Identify affected Work names only as context. Never answer for the person."
         : 'Final privacy resolution: return {resolutions:[{type,value,disposition,reason}]}. Resolve every supplied term strictly by the confirmed card answer: Hide gives "hidden" and Keep gives "keep" for every covered term; never override the answer of the person with your own judgment; when the same value is also under another card answered Hide, the CLI makes it Hidden, so still resolve by the answer of this card (credentials and contact details are masked separately and never reach these tasks). Use guidance only for a term the answer does not settle. disposition MUST be exactly the string "hidden" or "keep" (the card option id "hide" means "hidden"), never pending. If rules cannot settle a value, report explicit failure instead of inventing an answer.'
     const base = stage === 'cards' ? {} : { card: { ...group.card, termKeys: undefined }, guidance }
     const dataFor = (terms) => {

package/skills/tacitt/scripts/journey.d.mts

@@ -33,6 +33,10 @@ export function runPhase(
     stage?: string
     refresh?: boolean
     limit?: number
+    waitMs?: number
+    sleep?: (ms: number) => Promise<void>
+    /** Ensures a detached panel host at a handoff phase (ADR 0227). */
+    ensureHost?: () => Promise<{ url: string; pid: number; started: boolean }>
   },
   call: (procedure: string, input: unknown) => Promise<unknown>,
 ): Promise<Record<string, unknown>>