ultra-builder-pro-cli 0.16.0 → 0.17.0

package/docs/WORKFLOW-LIFECYCLE.md

@@ -9,9 +9,9 @@ host and project owner. It is the operational companion to
 
 | Surface | Owns | Must not own |
 |---|---|---|
-| Active host and owner | Product judgment, research content, implementation, review findings, release authorization | Durable workflow status or fabricated evidence digests |
+| Active host and owner | Product judgment, research content, implementation, review findings, and authorization for destructive or external effects | Durable workflow status or fabricated evidence digests |
 | Skill | One reusable procedure and its evidence requirements | Project state, static product doctrine, host-specific tool fiction |
-| MCP | IDs, transitions, task contracts, evidence references, output hashes, gate verdicts, next action | Research prose, code generation, memory, or model calls |
+| MCP | IDs, valid transitions, hard recovery requirements, task contracts, evidence references, output hashes, and gate verdicts | Semantic route selection, research prose, code generation, memory, or model calls |
 | `.ultra/state.db` | Baseline, change, decision, task, workflow, session, event, incident, projection, and evidence authority | Prompts, transcripts, external memory, or code-graph payloads |
 | Generated JSON and Markdown | Read-only projections and durable artifacts | Independent lifecycle authority |
 | Hook | Compact DB-derived lifecycle observation, minimal event metadata, and projection protection | Generic engineering judgment, prompt/transcript capture, parallel lifecycle logs, or arbitrary edit blocking |
@@ -20,7 +20,8 @@ Prompt input can supply facts, content paths, reasons, owner decisions, and
 evidence references. MCP reads the current repository and DB, validates those
 inputs, hashes outputs, and derives status. Prompt input cannot override a task's
 public seam, verification command, context references, workflow summary, gate
-verdict, output digest, or next action.
+verdict, output digest, or transition validity. A host recommendation is never stored
+as MCP authority.
 
 Load-bearing owner choices are normalized through `decision.*`; Prompt prose is not
 durable authority. The host acquires observable facts autonomously, exposes one
@@ -34,10 +35,12 @@ authority, and no new stage may start on an archived or cancelled change. Doctor
 recovers a legacy change without this link into an explicitly blocked workflow;
 it does not fabricate the missing provenance.
 
-Ultra does not select an MVP. Product scope and delivery posture are owner
-decisions. A reduced research mode is valid only for an explicitly bounded active
-change with a recorded selection reason; initial greenfield and brownfield
-baselines always use all seventeen research steps.
+Ultra does not select an MVP. Product scope and material delivery posture are owner
+decisions. The seventeen research areas are a coverage catalog, not a forced
+questionnaire. Initial greenfield and brownfield research must disposition every area
+as `execute`, `verify_existing`, `reuse`, `not_applicable`, or accepted `deferred`;
+only selected necessary work executes. Bounded change research records the same
+selection rationale over its smaller scope.
 
 ## 2. How `ultra-init` classifies a repository
 
@@ -65,9 +68,22 @@ worktree digests and accepted dirty files are restricted to that scope.
 
 Classification and readiness are separate. Initialization immediately creates
 or resumes `.ultra/state.db`, installs only the required scaffold, records the
-classification, opens an `init` workflow, and opens `full` research for
-greenfield or `adoption` research for brownfield. Empty templates are not an
-approved baseline.
+classification, and completes an `init` workflow after read-back verification. It
+does not create a research run. A later explicit `ultra-research` invocation selects
+`full` for greenfield or `adoption` for brownfield, records coverage dispositions, and
+works toward baseline readiness. Empty templates are not an approved baseline.
+
+With `git_mode: auto`, initialization preserves an existing repository and HEAD.
+When Git is absent it initializes `main` and adds the symlink-safe `.ultra` rule to
+`.gitignore`; an existing repository keeps its tracked ignore file unchanged. Init
+does not create a commit, remote, tag, or push. The resulting `unborn` worktree state
+is durable authority, not equivalent to a non-Git workspace. Full/adoption research
+must obtain explicit approval for one local checkpoint commit before
+`baseline.record`; until then `BASELINE_GIT_HEAD_REQUIRED` blocks convergence.
+
+Init completion means only that local authority, Git state, scaffold, and
+classification are usable. Baseline readiness is a separate research and convergence
+outcome; failure there never reopens or blocks the completed init workflow.
 
 ## 3. Durable status machines
 
@@ -124,6 +140,40 @@ traceability, slice kind, public seam, exact verification command, acceptance
 checks, context references, resolved documentation impact, owner, and valid
 dependencies.
 
+A semantic Change update marks all derived tasks stale. Clearing that marker requires
+one complete execution-contract rebind through `task.update`; a marker-only clear is
+rejected. MCP validates the resulting contract and appends
+`task_contract_reconciled` with the current Change authority digest before a new plan
+may converge.
+
+A session process and a task have different status machines. Process exit zero closes
+the execution transport but leaves the task `in_progress` until development,
+integration, test, and review gates converge. Process failure marks the task `blocked`
+and records failure/circuit evidence. `session.close` preserves the worktree by
+default. Explicit removal succeeds only after Git proves it is clean and its commit is
+integrated into the current checkout.
+
+Dependency-wave automation advances only when every task in the current wave is
+`completed` or `expanded` in the DB. A successful worker exit with open gates emits
+`wave_paused` and `plan_paused`; it cannot start dependent work. Re-running the plan
+resumes the first unfinished wave. Explicit auto-merge is additionally gated by task
+completion, an exact completion commit, a ready dev workflow, a current task review,
+clean committed work, and successful integration; otherwise the worktree remains
+recoverable. Legacy tasks without change ownership retain their compatibility path,
+but cannot satisfy the current change workflow contract.
+
+Every session worktree resolves its ignored `.ultra` entry to the project authority
+directory. Automated workers receive the central DB path and the isolated checkout
+root separately; their supplied environment cannot override those bindings. If a
+legacy `.ultra/` rule does not ignore the link itself, Ultra adds a repository-local
+`info/exclude` entry without changing tracked files. A missing, tracked, still
+unignored, or conflicting authority entry fails before the session row or worker is
+created and the provisional worktree is removed. A process that already has
+`UBP_SESSION_ID` must reuse that lease and worktree; nested spawn and worker-side close
+are rejected, so the supervising parent alone settles the lease from the real process
+exit. Authority drift detected after wave selection pauses the plan without recording
+execution failure.
+
 ### Workflow run and step
 
 ```text
@@ -160,19 +210,19 @@ case. It never stores the conversation transcript.
 
 ## 4. Write and verification lifecycle
 
-| Stage | Authoritative writes | Completion verification | Next route |
+| Stage | Authoritative writes | Completion verification | Available continuation |
 |---|---|---|---|
-| `init` | Baseline classification/scope, init run, research run, initialization event, projection job | DB/schema opens, scaffold/projection succeeds; baseline convergence later completes init | `research`, re-adoption, or `change` for an already-ready baseline |
-| `research` | Ordered step evidence, decision threads/checkpoints, typed semantic records with source digests, one immutable report per selected step, output paths and SHA-256 digests | Every load-bearing owner decision is confirmed; every report has the required structure; semantic kinds/attributes/source anchors are valid and current; full/adoption synthesis binds the current three specifications and distillate; all digests remain current | `baseline.record`, then approval/convergence; bounded change research returns to its change |
+| `init` | Baseline classification/scope, Git bootstrap state, completed init run, initialization event, projection job | DB/schema opens, scaffold/projection and read-back succeed; existing Git is preserved or missing local Git is initialized | Explicitly chosen `research`, `status`, or `doctor`; an already-ready project may also enter `change` |
+| `research` | Coverage dispositions, selected step evidence, material decision checkpoints, typed semantic records with source digests, immutable reports, output paths and SHA-256 digests | Every coverage area is dispositioned; only executed/verified/reused areas require work evidence; synthesis binds current specifications and distillate; all material decisions and digests are current | Baseline record/convergence for initial research; bounded change research returns to its owning change |
 | baseline convergence | Spec/source/runtime refs, verification results, known failures, unknowns, gaps, branch/HEAD/worktree, approval | Full/adoption research complete; required discovery/product/architecture refs current; revision/worktree exact; blocking gaps resolved or explicitly accepted where allowed | `change` for every initial or daily outcome |
-| `change` | Baseline-bound alignment checkpoint, complete Change Contract, profile/risk rationale, research disposition, intent/delta artifacts, linked change run, initial context snapshot | The linked alignment thread is confirmed; selected change research is current; current plan task set matches DB; task-bound context is ready; one next action is derived | selected `research`, then `plan`, or `dev` for an already approved current plan |
-| `plan` | Plan decision checkpoint, plan-step evidence, complete change-owned task rows, acceptance coverage matrix, change-bound `.ultra/execution-plan.json`, explicit plan approval | Blocking planning choices are confirmed; every Change acceptance id is owned by a task; task trace targets resolve; quick has one task; ownership/dependencies valid; no cycles; exported topology and digest exactly match the current change task set | `dev` for the first dependency-ready task |
-| `dev` | Task/session transitions, step evidence, immutable implementation context, completion/review references | Task completed; no live session; task contract unchanged; starting context and review artifacts valid; completion commits remain ancestors of current HEAD | Next task, then aggregate `test` |
-| `test` | Immutable checking context and `.ultra/reports/tests/<workflow-id>.json` | Report change/task set, full HEAD, worktree digest, context digest, commands, public seam, blockers, and all acceptance/regression/integration/static/build/performance/security/recovery dimensions agree; every omission has a not-applicable rationale | `review` when passing, otherwise resume `dev`/`test` |
-| `review` | Immutable review context, `task`/`change`/`plan` mode, worker selection provenance, two specialist axes, coordinated summary | Current diff/HEAD and context match; selected/skipped workers match recorded rationale; both axes complete; P0/P1 and axis verdicts deterministically derive final verdict | `deliver` only from approved `change` mode, otherwise resume implementation |
-| `deliver` | Convergence context, verified learning resolutions, schema-validated semantic reconciliation manifest, change archive, durable release-authorization decision, immutable delivery report | Tasks/test/change-review current; every baseline update has an anchored before/after semantic record; `change.converge` derives evidence from DB and accepts no Prompt verdicts; archive and baseline transaction agree; external actions have evidence | Report completion or start the next `change` |
-| `status` | None | Reads doctor, baseline, workflows, breadcrumb, tasks, sessions, Git, and DB-referenced reports | One exact current route |
-| `doctor` | None by default; explicit repair writes only mechanical recovery state | Re-runs integrity, schema, workflow-output, projection, session, incident, archive, and install checks | Exact repair, restore/rebaseline decision, or workflow route |
+| `change` | Complete Change Contract, profile/risk rationale, research disposition, intent/delta artifacts, and a completed capture run; a decision thread only when material intent remains unresolved | Intent, acceptance, recovery, classification, and research disposition are complete and bound to the baseline | Host selects among bounded `research`, `plan`, current `dev`, `think`, or `status` using allowed transitions |
+| `plan` | Selected planning evidence, complete change-owned task rows, acceptance coverage matrix, and change-bound `.ultra/execution-plan.json`; approval only for a material owner decision | Every Change acceptance id is owned by a task; trace targets, ownership, dependencies, topology, task contracts, and exported digest match current authority | Any dependency-ready task may enter `dev` |
+| `dev` | Task/session transitions, real worktree, step evidence, immutable implementation context, completion/review references | Task completed; no live session; task contract unchanged; starting context and review artifacts valid; completion commits are integrated and remain ancestors of current HEAD | Next task, then aggregate `test` |
+| `test` | Immutable checking context, an explicit risk-selected verification profile, and `.ultra/reports/tests/<workflow-id>.json` | Selected dimensions and acceptance pass; every excluded dimension has a rationale; report change/task set, HEAD, worktree, context, commands, blockers, and digests agree | `review` when passing, otherwise resume `dev`/`test` |
+| `review` | Immutable review context, `task`/`change`/`plan` mode, risk-selected worker provenance, two mandatory specialist axes, and coordinated summary | Current diff/HEAD and context match; the complete worker roster is selected or skipped with rationale; completed workers match specialist artifacts; both axes complete; findings and axis verdicts derive the final verdict | `deliver` only from a passing `change` review, otherwise resume implementation or checking |
+| `deliver` | Convergence context, verified learning resolutions, semantic reconciliation manifest, local change archive, and immutable delivery report | Tasks/test/change-review are current; baseline semantic updates are anchored; archive and baseline transaction agree; the report contains no release action | Report local completion or start the next `change`; publish/deploy/push are separate explicitly authorized operations |
+| `status` | None | Reads doctor, baseline, workflows, breadcrumb, tasks, sessions, Git, and DB-referenced reports | Shows allowed transitions, any hard required transition, and a host-owned recommendation |
+| `doctor` | None by default; explicit repair writes only mechanical recovery state | Re-runs integrity, schema, workflow-output, projection, session, incident, archive, and install checks | Mechanically required recovery when unique; otherwise a set of safe recovery capabilities |
 
 Every mutating MCP operation appends an event and enqueues projection work when
 the corresponding read-only view can change. Projection failure is recorded as
@@ -183,28 +233,30 @@ emitted by their owning DB mutation and never act as a substitute state transiti
 ## 5. Human-agent alignment lifecycle
 
 The host first reads `decision.list` and resumes matching authority. It starts a new
-thread only for a new decision cluster. For every current decision it must:
+thread only for a new material decision cluster. Before asking, it must:
 
 1. inspect repository, runtime, tests, specifications, and primary-source evidence;
 2. resolve evidence-answerable facts without asking the owner;
-3. call `decision.open` for the earliest unresolved owner choice with a recommendation,
-   no more than three credible alternatives, evidence refs, and durable effects;
-4. present that one choice and end the turn;
-5. normalize the next owner response with `decision.resolve`, explicit reversible
+3. normalize an unambiguous decision already present in the current user request
+   instead of asking for redundant confirmation;
+4. ask only when the remaining choice changes intent, public behavior, compatibility,
+   security, material cost, external effects, or recovery. Use the host-native
+   question surface declared by `spec/interaction-contract.json`;
+5. present the earliest dependent choice with a recommendation, credible alternatives,
+   evidence refs, and durable effects. Up to three independent low-load facts may be
+   grouped when that reduces inconsistency;
+6. normalize the owner response with `decision.resolve`, explicit reversible
    delegation with `decision.delegate`, or a consequence-bearing deferral with
    `decision.defer`;
-6. prepare one compact checkpoint, obtain one owner approval, update the affected
-   artifact, and confirm the checkpoint with its current digest. Workflow- and
-   change-bound threads must bind an artifact. If a shared specification will keep
-   evolving, bind a stable per-thread decision projection rather than the mutable
-   working draft.
+7. prepare a compact checkpoint only when a material decision cluster changes a
+   durable contract and interruption recovery needs an artifact-bound boundary.
 
 `ultra-think` owns this interaction protocol. `ultra-research`, `ultra-change`, and
 `ultra-plan` invoke it at their decision boundaries. `ultra-dev`, `ultra-test`,
 `ultra-review`, and `ultra-deliver` stop and route back to the same thread when new
 owner authority is required; they never answer on the owner's behalf. `ultra-status`
-shows only the current decision and exact route, while `ultra-doctor` diagnoses stale
-checkpoint artifacts and recovery state.
+shows only the current decision and transition set, while `ultra-doctor` diagnoses
+stale checkpoint artifacts and recovery state.
 
 When only a bound artifact changes, the same resolved thread is prepared and approved
 again against the current digest; this is checkpoint renewal, not a fabricated decision
@@ -213,7 +265,7 @@ opens one replacement.
 
 ## 6. Context and prompt follow-through
 
-`change.context` compiles an immutable Context Manifest v2 snapshot. It combines:
+`change.context` compiles an immutable Context Manifest v3 snapshot. It combines:
 
 - the bound baseline/change/task identity;
 - a role and lifecycle gate;
@@ -221,13 +273,14 @@ opens one replacement.
 - local file hashes, current HEAD, branch, and worktree digest;
 - optional metadata-only external memory or graph references;
 - advisory file/token/context-share budgets;
-- readiness blockers and one DB-derived next action.
+- the current Change and task authority digests;
+- readiness blockers, `allowed_transitions`, and a `required_transition` only for a
+  unique hard-recovery path.
 
 Critical stage workflows bind a matching snapshot as a durable output:
 
 | Workflow | Required role | Required gate |
 |---|---|---|
-| `change` | `plan` or `implement` | `planning` or `implementation` |
 | `dev` | `implement` | `implementation` |
 | `test` | `check` | `verification` |
 | `review` | `review` | `review` |
@@ -236,13 +289,18 @@ Critical stage workflows bind a matching snapshot as a durable output:
 The snapshot path and digest are then carried into test, review, and delivery
 reports. This prevents a later Prompt from claiming evidence gathered under a
 different context. File and token budgets warn; they do not block legitimate
-work. Missing authority, required refs, task contracts, outputs, approval, or
+work. Missing authority, required refs, task contracts, outputs, required owner
+decisions, or
 current gate evidence do block.
 
 ## 7. Invalidation rules
 
 - Changing a task contract invalidates contexts and gates that depended on the
   former contract.
+- Changing accepted Change intent, contract, classification, research disposition,
+  provider evidence, or documentation impact marks all derived tasks stale and
+  invalidates compiled contexts. Planning or task reconciliation must explicitly
+  clear staleness before execution.
 - Changing required source/spec content invalidates the recorded output or
   context digest.
 - Changing a research semantic source invalidates that workflow even when its immutable
@@ -266,21 +324,25 @@ current gate evidence do block.
 ### New project
 
 ```text
-ultra-init -> full research (17 steps with one-decision checkpoints) -> baseline approval
--> initial change alignment -> plan checkpoint -> dev per task -> test -> review -> deliver
+ultra-init -> Git/scaffold/authority verification -> init completed
+-> explicit ultra-research -> disposition 17 coverage areas -> selected evidence work
+-> local checkpoint when Git is unborn -> baseline approval
+-> ultra-change -> optional bounded research/plan -> dev -> risk-selected test/review
+-> local deliver/archive
 ```
 
 ### Existing project
 
 ```text
-ultra-init -> brownfield adoption research (17 steps with one-decision checkpoints)
--> characterization and known-red evidence -> gap ledger -> owner approval
--> first selected change alignment -> plan checkpoint -> dev -> test -> review -> deliver
+ultra-init -> preserve Git/classify brownfield -> init completed
+-> explicit adoption research -> disposition 17 coverage areas
+-> selected characterization/known-red evidence -> gap ledger -> owner approval
+-> first ultra-change -> optional bounded research/plan -> dev -> test/review -> deliver
 ```
 
 Adoption records the system that exists. It does not force the owner to recreate
 market, persona, or roadmap claims that cannot be supported; those remain
-`Unknown` or explicit gaps while every semantic step is still processed.
+`Unknown`, `not_applicable`, accepted `deferred`, or explicit gaps with evidence.
 
 ### Earlier Ultra project
 
@@ -294,8 +356,9 @@ Migration preserves prior files and rows but never carries old approval forward.
 ### Daily maintenance
 
 ```text
-ultra-status -> ultra-change capture/alignment -> plan if task contracts are absent
--> dev -> test -> review -> deliver -> reconciled baseline
+ultra-status -> ultra-change intent capture
+-> host chooses bounded research, plan, current task, think, or status
+-> dev -> risk-selected test -> review -> deliver -> reconciled baseline
 ```
 
 Quick changes shorten the artifact burden only where the machine contract allows;
@@ -307,21 +370,22 @@ evidence rather than bypassing them.
 
 | Entry | Owns | Normal handoff |
 |---|---|---|
-| `ultra-init` | classification, scope, scaffold, baseline/run creation | `ultra-research`; an already-ready project routes to `ultra-change` |
-| `ultra-research` | evidence acquisition, seventeen-step semantic coverage, research decisions | baseline approval then `ultra-change`; bounded research returns to `ultra-plan` |
-| `ultra-think` | one current owner decision or read-only diagnosis | exact invoking workflow and step after checkpoint confirmation |
-| `ultra-change` | outcome capture, alignment, Change Contract, risk/research routing | selected `ultra-research`, then `ultra-plan`; approved existing plan may route to `ultra-dev` |
-| `ultra-plan` | plan decisions, task contracts, dependencies, approval | first ready task through `ultra-dev` |
+| `ultra-init` | classification, scope, Git/scaffold bootstrap, and init verification | stops completed; exposes research/status/doctor and any already-valid change capability |
+| `ultra-research` | coverage disposition, selected evidence acquisition, synthesis, and material research decisions | baseline convergence or return to the owning change |
+| `ultra-think` | one material owner decision or read-only diagnosis | returns to the invoking capability after any needed checkpoint |
+| `ultra-change` | outcome capture, Change Contract, risk/research routing | host selects research, plan, current dev work, think, or status |
+| `ultra-plan` | task contracts, dependencies, acceptance coverage, optional material approval | any dependency-ready task through `ultra-dev` |
 | `ultra-dev` | one task/session vertical slice and focused review | next `ultra-dev` task or aggregate `ultra-test` |
-| `ultra-test` | change-level acceptance and regression gate | `ultra-review` on pass, `ultra-dev` on implementation failure |
-| `ultra-review` | independent specification and engineering verdicts | `ultra-deliver` on approval; otherwise `ultra-dev` or `ultra-test` |
-| `ultra-deliver` | convergence, reconciliation, archive, authorized release evidence | `ultra-status` or the next `ultra-change` |
-| `ultra-status` | read-only authoritative position and one route | whichever exact workflow owns the current step |
-| `ultra-doctor` | read-only diagnosis and authorized mechanical recovery | exact recovered workflow, `ultra-init`, or `ultra-think` |
-
-Every row routes to `ultra-think` when owner authority is missing and to
-`ultra-doctor` when state or installed-runtime authority is unhealthy. Neither route
-creates a parallel workflow or substitutes a Prompt summary for the DB state.
+| `ultra-test` | risk-selected change acceptance and verification profile | `ultra-review` on pass, `ultra-dev`/`ultra-test` on failure |
+| `ultra-review` | independent specification and engineering axes plus risk-selected workers | `ultra-deliver` on approval; otherwise implementation or checking |
+| `ultra-deliver` | convergence, reconciliation, local archive, and delivery evidence | `ultra-status` or the next `ultra-change`; external release is separate |
+| `ultra-status` | read-only authority and transition set | host recommendation among allowed transitions |
+| `ultra-doctor` | read-only diagnosis and authorized mechanical recovery | required recovery only when unique; otherwise safe alternatives |
+
+Every row permits `ultra-think` when material owner authority is missing and permits
+`ultra-doctor` when state or installed-runtime authority is unhealthy. MCP makes one
+of them required only when no safe alternative exists. Neither capability creates a
+parallel workflow or substitutes a Prompt summary for DB state.
 
 ## 9. Recovery and diagnosis
 

package/hooks/pre_stop_check.py

@@ -35,13 +35,14 @@ def main() -> None:
         allow_stop()
         return
     if breadcrumb and breadcrumb.get("change_id"):
+        allowed = ", ".join(breadcrumb.get("allowed_transitions") or []) or "none"
+        required = breadcrumb.get("required_transition") or "none"
         print(
             "[Ultra stop advisory] Active Ultra change remains open: "
             f"change={breadcrumb['change_id']}, "
             f"task={breadcrumb.get('task_id') or 'none'}, "
             f"gate={breadcrumb.get('gate') or 'alignment'}, "
-            f"route={breadcrumb.get('recommended_workflow') or 'ultra-status'}. "
-            f"Next: {breadcrumb.get('next_action') or 'Inspect Ultra status.'} "
+            f"allowed_transitions={allowed}, required_transition={required}. "
             "Stop is allowed; resume or explicitly archive the change later.",
             file=sys.stderr,
         )

package/mcp-server/lib/baseline-workflow.cjs

@@ -40,20 +40,33 @@ function gitHead(rootDir) {
   return result.status === 0 ? result.stdout.trim() : null;
 }
 
+function gitRepositoryRoot(rootDir) {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
 function gitBranch(rootDir) {
-  const result = spawnSync('git', ['branch', '--show-current'], {
+  let result = spawnSync('git', ['symbolic-ref', '--quiet', '--short', 'HEAD'], {
     cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
   });
+  if (result.status !== 0) {
+    result = spawnSync('git', ['branch', '--show-current'], {
+      cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  }
   return result.status === 0 ? (result.stdout.trim() || null) : null;
 }
 
 function gitWorktreeSnapshot(rootDir, scope = ['.']) {
-  const head = gitHead(rootDir);
-  if (!head) {
+  const repositoryRoot = gitRepositoryRoot(rootDir);
+  if (!repositoryRoot) {
     return {
       head: null, branch: null, state: 'unavailable', digest: null, files: [],
     };
   }
+  const head = gitHead(rootDir);
   const selectedScope = Array.isArray(scope) && scope.length > 0 ? scope : ['.'];
   const pathspecs = selectedScope.map((item) => (
     item === '.' ? '.' : `:(literal)${item}`
@@ -63,10 +76,12 @@ function gitWorktreeSnapshot(rootDir, scope = ['.']) {
     'git', ['status', '--porcelain=v1', '-z', '--untracked-files=all', ...args],
     { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
   );
-  const diff = spawnSync(
-    'git', ['diff', '--binary', '--no-ext-diff', 'HEAD', ...args],
-    { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
-  );
+  const diff = head
+    ? spawnSync(
+      'git', ['diff', '--binary', '--no-ext-diff', 'HEAD', ...args],
+      { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
+    )
+    : { status: 0, stdout: Buffer.alloc(0) };
   const untracked = spawnSync(
     'git', ['ls-files', '--others', '--exclude-standard', '-z', ...args],
     { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
@@ -79,7 +94,7 @@ function gitWorktreeSnapshot(rootDir, scope = ['.']) {
   const statusText = status.stdout.toString('utf8');
   const files = statusText.split('\0').filter(Boolean);
   const digest = crypto.createHash('sha256');
-  digest.update(head).update('\0').update(gitBranch(rootDir) || '').update('\0');
+  digest.update(head || 'unborn').update('\0').update(gitBranch(rootDir) || '').update('\0');
   digest.update(status.stdout).update(diff.stdout);
   for (const relative of untracked.stdout.toString('utf8').split('\0').filter(Boolean).sort()) {
     digest.update(relative).update('\0');
@@ -93,7 +108,7 @@ function gitWorktreeSnapshot(rootDir, scope = ['.']) {
   return {
     head,
     branch: gitBranch(rootDir),
-    state: files.length > 0 ? 'dirty' : 'clean',
+    state: head ? (files.length > 0 ? 'dirty' : 'clean') : 'unborn',
     digest: digest.digest('hex'),
     files,
   };
@@ -464,6 +479,55 @@ function startBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = tr
   });
 }
 
+function refreshInProgressBaseline(db, input = {}, {
+  rootDir = process.cwd(), emitEvent = true,
+} = {}) {
+  const current = readBaseline(db, input.id);
+  if (!current) {
+    throw new BaselineWorkflowError('BASELINE_NOT_FOUND', `baseline ${input.id || '(current)'} not found`);
+  }
+  if (!['draft', 'adopting', 'blocked'].includes(current.status)) return current;
+  const projectName = input.project_name === undefined
+    ? current.project_name
+    : nonEmpty(input.project_name, 'project_name');
+  const projectType = input.project_type === undefined ? current.project_type : input.project_type;
+  const stack = input.stack === undefined ? current.stack : input.stack;
+  const classification = input.classification === undefined
+    ? current.classification
+    : normalizeClassification(input.classification);
+  const snapshot = gitWorktreeSnapshot(rootDir, current.scope);
+  const repositoryRevision = snapshot.head
+    || (snapshot.state === 'unborn' ? null : current.repository_revision);
+  const ts = nowIso();
+  return ops.tx(db, () => {
+    db.prepare(
+      `UPDATE baselines SET project_name = ?, project_type = ?, stack = ?,
+       repository_revision = ?, repository_branch = ?, worktree_state = ?,
+       worktree_digest = ?, worktree_files_json = ?, classification_json = ?,
+       updated_at = ? WHERE id = ?`,
+    ).run(
+      projectName, projectType || null, stack || null,
+      repositoryRevision, snapshot.branch, snapshot.state, snapshot.digest,
+      JSON.stringify(snapshot.files), JSON.stringify(classification), ts, current.id,
+    );
+    if (emitEvent) {
+      ops.appendEventInTx(db, {
+        type: 'baseline_metadata_refreshed',
+        payload: {
+          baseline_id: current.id,
+          project_name: projectName,
+          project_type: projectType || null,
+          stack: stack || null,
+          repository_revision: repositoryRevision,
+          repository_branch: snapshot.branch,
+          worktree_state: snapshot.state,
+        },
+      });
+    }
+    return readBaseline(db, current.id);
+  });
+}
+
 function recordBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = true } = {}) {
   const current = readBaseline(db, input.id);
   if (!current) throw new BaselineWorkflowError('BASELINE_NOT_FOUND', `baseline ${input.id} not found`);
@@ -484,6 +548,12 @@ function recordBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = t
     ? current.provider_refs
     : providerRefs.normalizeProviderRefs(input.provider_refs, BaselineWorkflowError);
   const snapshot = gitWorktreeSnapshot(rootDir, scope);
+  if (snapshot.state === 'unborn') {
+    throw new BaselineWorkflowError(
+      'BASELINE_GIT_HEAD_REQUIRED',
+      'Git is initialized but has no commit; create an owner-authorized local checkpoint commit before recording the baseline',
+    );
+  }
   if (snapshot.head && input.repository_revision && input.repository_revision !== snapshot.head) {
     throw new BaselineWorkflowError(
       'BASELINE_REVISION_MISMATCH', 'repository_revision does not match current Git HEAD',
@@ -667,6 +737,7 @@ function convergenceBlockers(db, baseline, input, rootDir) {
   if (!expected) blockers.add('BASELINE_REVISION_REQUIRED');
   else if (baseline.repository_revision !== expected) blockers.add('BASELINE_REVISION_MISMATCH');
   const snapshot = gitWorktreeSnapshot(rootDir, baseline.scope);
+  if (snapshot.state === 'unborn') blockers.add('BASELINE_GIT_HEAD_REQUIRED');
   if (snapshot.head && expected && snapshot.head !== expected) blockers.add('BASELINE_HEAD_STALE');
   if (baseline.repository_branch && snapshot.branch
     && baseline.repository_branch !== snapshot.branch) blockers.add('BASELINE_BRANCH_STALE');
@@ -725,7 +796,6 @@ function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent =
           type: 'baseline_blocked', payload: { baseline_id: current.id, blockers },
         });
       }
-      workflows.blockInitializationInTx(db, current.id, blockers);
     });
     return { ready: false, status: 'blocked', blockers, baseline: readBaseline(db, current.id) };
   }
@@ -745,12 +815,6 @@ function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent =
         type: 'baseline_converged', payload: { baseline_id: current.id, revision: current.repository_revision },
       });
     }
-    workflows.completeInitializationInTx(db, {
-      ...current,
-      approved_by: String(input.approved_by).trim(),
-      research_run_id: research.id,
-      converged_at: ts,
-    });
   });
   return { ready: true, status: 'ready', blockers: [], baseline: readBaseline(db, current.id) };
 }
@@ -786,6 +850,9 @@ function inspectBaseline(db, { rootDir = process.cwd(), id } = {}) {
   const snapshot = gitWorktreeSnapshot(
     rootDir, Array.isArray(baseline.scope) && baseline.scope.length > 0 ? baseline.scope : ['.'],
   );
+  if (snapshot.state === 'unborn') {
+    blockers.push('BASELINE_GIT_HEAD_REQUIRED');
+  }
   if (snapshot.head && baseline.repository_revision && snapshot.head !== baseline.repository_revision) {
     blockers.push('BASELINE_HEAD_STALE');
   } else if (!snapshot.head && baseline.repository_revision?.startsWith('workspace:')) {
@@ -905,6 +972,7 @@ function appendGap(db, input = {}, options = {}) {
 module.exports = {
   BaselineWorkflowError,
   startBaseline,
+  refreshInProgressBaseline,
   recordBaseline,
   convergeBaseline,
   readBaseline,