project-tiny-context-harness 0.11.0 → 0.12.1

package/dist/lib/context-mutation/mutation-recovery.js

@@ -2,7 +2,7 @@ import { applyMutationChangeBackward, applyMutationChangeForward, assertMutation
 import { cleanupContextMutationTemporaries, finishContextMutation, } from "./mutation-commit.js";
 import { mutationDirectoryStatus, prepareMutationDirectories, rollbackMutationDirectories, } from "./mutation-directories.js";
 import { assertSameContextMutationJournalSnapshot, readContextMutationJournal, updateContextMutationJournal, } from "./mutation-journal.js";
-import { contextMutationAffectedPaths, withContextMutationAuthorityInterlock, } from "./mutation-long-task-guard.js";
+import { withContextMutationInterlock } from "./mutation-interlock.js";
 import { validateLiveContextMutation, validateRolledBackContextMutation, } from "./mutation-live-validation.js";
 import { canonicalJson } from "../strict-codec.js";
 import { mutationPhysicalPath } from "./mutation-file-state.js";
@@ -41,7 +41,7 @@ export async function contextMutationStatus(repository) {
 }
 export async function completeContextMutation(repository) {
     const initial = await requiredJournal(repository);
-    return withContextMutationAuthorityInterlock(repository, contextMutationAffectedPaths(initial), async () => completeContextMutationLocked(repository, initial), "recovery");
+    return withContextMutationInterlock(repository, async () => completeContextMutationLocked(repository, initial));
 }
 async function completeContextMutationLocked(repository, initial) {
     let journal = await requiredMatchingJournal(repository, initial);
@@ -76,7 +76,7 @@ async function completeContextMutationLocked(repository, initial) {
 }
 export async function rollbackContextMutation(repository) {
     const initial = await requiredJournal(repository);
-    return withContextMutationAuthorityInterlock(repository, contextMutationAffectedPaths(initial), async () => rollbackContextMutationLocked(repository, initial), "recovery");
+    return withContextMutationInterlock(repository, async () => rollbackContextMutationLocked(repository, initial));
 }
 async function rollbackContextMutationLocked(repository, initial) {
     let journal = await requiredMatchingJournal(repository, initial);

package/dist/lib/context-register/context-register.js

@@ -1,4 +1,5 @@
 import { appendContextManifestBlock, } from "../context-mutation/manifest-lossless-patch.js";
+import { assertSupportedSchema } from "../schema-guard.js";
 import { captureMutationFileState, mutationFileStateFromBytes, mutationTemporaryPath, } from "../context-mutation/mutation-cas.js";
 import { executeContextMutationPlan } from "../context-mutation/mutation-commit.js";
 import { assertMutationCatalogValid, assertNoUnfinishedContextMutation, decodeMutationUtf8, loadMutationCatalog, mutationCatalogFailure, mutationIoFailure, mutationMessage, mutationStateBytes, sameMutationArray, } from "../context-mutation/mutation-command-support.js";
@@ -10,6 +11,8 @@ import { normalizeContextRegisterInput } from "./context-register-input.js";
 import { assertRegistrationTarget, assertStagedRegistration, readContextContent, renderAppendDiff, } from "./context-register-support.js";
 const MANIFEST_PATH = "project_context/context.toml";
 export async function registerContext(input) {
+    if (input.apply)
+        await assertSupportedSchema(input.project_root, "context register");
     const planned = await planContextRegistration(input);
     if (!input.apply)
         return planned.result;

package/dist/lib/context-templates.d.ts

@@ -1,5 +1 @@
 export declare function globalContextTemplate(): string;
-export declare function architectureContextTemplate(): string;
-export declare function areaContextTemplate(areaName: string): string;
-export declare function verificationContextTemplate(areaName: string): string;
-export declare function deploymentContextTemplate(areaName: string): string;

package/dist/lib/context-templates.js

@@ -1,212 +1,3 @@
 export function globalContextTemplate() {
-    return [
-        "# Project / Delivery Context",
-        "",
-        "## Project Goal",
-        "",
-        "- Describe the user-visible goal this project is trying to achieve.",
-        "",
-        "## Non-goals / Boundaries",
-        "",
-        "- List what this project intentionally does not do.",
-        "",
-        "## Background",
-        "",
-        "- Capture the minimum background a fresh agent needs before changing code.",
-        "",
-        "## Design Rationale",
-        "",
-        "- Record only durable choices that are hard to infer from code or tests. Classify changes before implementation; if a change alters product ownership/plans, module responsibilities, information architecture, API/Schema, state/scheduler semantics, cross-area boundaries, verification role paths or deployment role paths, update Context before code with enough durable context to guide implementation.",
-        "",
-        "## Architecture Context",
-        "",
-        "- Link to `project_context/architecture.md`; keep architecture notes minimal and focused on boundaries, components and constraints that are not obvious from code.",
-        "",
-        "## Context Graph",
-        "",
-        "- Link to `project_context/context.toml` and keep its default area, role, trigger, read policy and boundary metadata aligned with this Context.",
-        "- When adding or reorganizing files under `project_context/areas/**`, run a soft role placement scan before registering every Markdown file as an area: product ownership stays in `area` / `domain` / `subdomain`; contracts, foundations, verification, deployment, implementation indexes, decision rationale and archives should use role Context when that better fits the reading purpose.",
-        "",
-        "## Product / Delivery Brief",
-        "",
-        "- Capture durable product goals, users, core flows, acceptance signals and non-goals.",
-        "",
-        "## UX / Screen Brief",
-        "",
-        "- Capture durable screen, flow, interaction, responsive and accessibility facts. Use `DESIGN.md` for visual identity and design tokens when needed.",
-        "",
-        "## Verification Entry Points",
-        "",
-        "- Point to the default verification context for repeatable test, smoke, CI or validation paths.",
-        "- Project-level cross-domain verification may live here only as a short index; execution details belong in `verification` role Context.",
-        "",
-        "## Current State",
-        "",
-        "- Summarize what is currently implemented or intentionally blocked.",
-        "",
-        "## Next Safe Action",
-        "",
-        "- State a stable safe re-entry rule for a fresh agent, including when Context must be updated before code. Do not store task-local progress or a one-off next edit here.",
-        "",
-        "## Context Index",
-        "",
-        "- [main](areas/main.md)",
-        "- [main verification](areas/main/verification.md)",
-        "",
-    ].join("\n");
-}
-export function architectureContextTemplate() {
-    return [
-        "# Architecture Context",
-        "",
-        "This is the restrained architecture context. Keep only facts that help a fresh agent recover system shape, boundaries and durable constraints quickly.",
-        "",
-        "## System Boundary",
-        "",
-        "- Describe what is inside this project and what external systems, providers or runtime assumptions sit outside it.",
-        "",
-        "## Component Map",
-        "",
-        "- List the smallest useful set of components, areas or context units and how they relate.",
-        "",
-        "## Data / Control Flow",
-        "",
-        "- Summarize only the durable request, event, state or data flow that is hard to infer from code alone.",
-        "",
-        "## Design Rationale",
-        "",
-        "- Record architecture-level choices that still constrain future work; architecture boundary changes should be captured here before implementation alignment.",
-        "",
-        "## Constraints And Tradeoffs",
-        "",
-        "- Capture performance, safety, integration, deployment or maintainability constraints that matter for future changes.",
-        "",
-        "## Verification Implications",
-        "",
-        "- List project-specific verification entry points affected by architectural changes; do not claim tests already passed.",
-        "",
-        "## Open Risks",
-        "",
-        "- List unresolved architectural risks or unknowns.",
-        "",
-    ].join("\n");
-}
-export function areaContextTemplate(areaName) {
-    return [
-        `# Area Context: ${areaName}`,
-        "",
-        "## Responsibility",
-        "",
-        "- Describe this product/domain area or context unit's responsibility.",
-        "",
-        "## User / System Contract",
-        "",
-        "- Describe the external behavior, API, CLI, UI, screen state, interaction or data contract. Contract changes should be captured here before implementation alignment.",
-        "",
-        "## Core Data / API / State",
-        "",
-        "- Summarize the important data structures, APIs, state transitions, or rules.",
-        "",
-        "## Module Design Capsule",
-        "",
-        "- Principles: stable execution constraints that should affect future module work.",
-        "- Design Logic: the minimum logic for choosing, rejecting, degrading or composing module behavior.",
-        "- Design Rationale: only durable reasons that change later implementation or verification decisions.",
-        "- Current standards, thresholds and commands belong in the relevant contract or verification Context, not as permanent principles.",
-        "",
-        "## Key Constraints",
-        "",
-        "- List constraints that are not obvious from code alone, including product rules, responsive/a11y needs or visual boundaries.",
-        "",
-        "## Code Entry Points",
-        "",
-        "- `src/` or the concrete file/function entry points.",
-        "",
-        "## Related Role Context",
-        "",
-        "- Verification paths live in this area's `verification` role Context, such as `project_context/areas/main/verification.md`.",
-        "- Deployment/runtime/bootstrap paths live in this area's optional `deployment` role Context when those facts exist.",
-        "",
-        "## Open Risks",
-        "",
-        "- List unresolved risks or blockers.",
-        "",
-    ].join("\n");
-}
-export function verificationContextTemplate(areaName) {
-    return [
-        `# Verification Context: ${areaName}`,
-        "",
-        "This role Context records critical repeat-execution paths for the owning area. Keep it minimal: enough for a future agent to rerun verification without rediscovering setup, not a test report.",
-        "",
-        "## Owner",
-        "",
-        `- Owning area: \`${areaName}\`.`,
-        "",
-        "## Verification Paths",
-        "",
-        "- `npm test` or the shortest project-specific test, smoke, CI, probe or validation command.",
-        "- Verification paths are reusable execution instances, not independent definitions of the verification target. For capability, metric or acceptance claims, first use the owning module's design Context to decide what claim should be proven, then choose the command or probe.",
-        "",
-        "## Required Preparation",
-        "",
-        "- List only durable setup such as services, env files, fixtures, local runtimes or external dependencies needed before rerun.",
-        "",
-        "## Expected Signals",
-        "",
-        "- Name the stage, health check, status, artifact shape or observable signal that means the path reached the intended point.",
-        "",
-        "## Acceptable Warnings",
-        "",
-        "- List warnings that are expected and should not trigger repeated investigation.",
-        "",
-        "## Excluded Dead Ends",
-        "",
-        "- List previously ruled-out commands, providers, endpoints or setup paths only when remembering them prevents repeated wasted work.",
-        "",
-        "## Forbidden Content",
-        "",
-        "- Do not record one-off logs, full command output, temporary JSON, CI artifacts, test reports, secrets, tokens, cookies, device ids, raw payloads or pass/fail claims.",
-        "",
-    ].join("\n");
-}
-export function deploymentContextTemplate(areaName) {
-    return [
-        `# Deployment Context: ${areaName}`,
-        "",
-        "This optional role Context records critical repeat-execution paths for deploy, runtime bootstrap, cloud initialization and operational recovery. Keep it minimal and durable.",
-        "",
-        "## Owner",
-        "",
-        `- Owning area: \`${areaName}\`.`,
-        "",
-        "## Runtime Topology",
-        "",
-        "- List durable service distribution only when it matters for rerunning deploy or bootstrap, such as Web/API/worker/Redis/DB/Docker/cloud instance boundaries.",
-        "",
-        "## Deployment Paths",
-        "",
-        "- List the shortest deploy, CI/CD, bootstrap, migration, health-check or rollback/degradation command/path.",
-        "",
-        "## Required Preparation",
-        "",
-        "- List only durable setup such as cloud resources, env files, compose profiles, secret mounting names or database initialization steps. Do not store secret values.",
-        "",
-        "## Expected Signals",
-        "",
-        "- Name health checks, status transitions, URLs, queues, containers or logs-at-a-glance that show the path reached the intended stage.",
-        "",
-        "## Acceptable Warnings",
-        "",
-        "- List known benign warnings or slow-start states.",
-        "",
-        "## Excluded Dead Ends",
-        "",
-        "- List previously ruled-out deploy/bootstrap paths only when remembering them prevents repeated wasted work.",
-        "",
-        "## Forbidden Content",
-        "",
-        "- Do not record one-off logs, full command output, CI artifacts, release ledgers, secrets, tokens, cookies, device ids, raw payloads or claims that deployment already succeeded.",
-        "",
-    ].join("\n");
+    return "# Project Context\n\nTODO: Record the project goal, important boundaries, confirmed decisions and useful operation/source entrypoints as they become known. Do not invent facts to fill a template.\n";
 }

package/dist/lib/doctor.d.ts

@@ -1,7 +1,7 @@
-import type { ContextDoctorOptions } from "./context-doctor/context-doctor-types.js";
+import { type ContextDoctorOptions } from "./context-doctor/context-doctor-types.js";
 export interface DoctorReport {
     info: string[];
     warnings: string[];
     errors: string[];
 }
-export declare function runDoctor(projectRoot: string, options?: ContextDoctorOptions): Promise<DoctorReport>;
+export declare function runDoctor(repository: string, options?: ContextDoctorOptions): Promise<DoctorReport>;

package/dist/lib/doctor.js

@@ -1,145 +1,56 @@
-import { createRequire } from "node:module";
 import path from "node:path";
-import os from "node:os";
-import { readdir } from "node:fs/promises";
-import { DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES, DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES, inspectDefaultContextFootprint, } from "./context-default-footprint.js";
-import { readConfig } from "./config.js";
-import { inspectDesignAuthority } from "./design-md.js";
-import { inspectDesignAuthorityClosure } from "./design-authority-closure.js";
-import { harnessConfigPath, harnessRoot } from "./harness-root.js";
+import { readFile } from "node:fs/promises";
+import { rawSchemaVersion, unsupportedSchemaMessage } from "./schema-guard.js";
+import { inspectDefaultContextFootprint } from "./context-default-footprint.js";
+import { runValidator } from "./validators.js";
 import { pathExists } from "./fs.js";
-import { unsupportedSchemaMessage } from "./schema-guard.js";
-import { inspectContextCatalogHealth } from "./context-doctor/context-doctor.js";
-const require = createRequire(import.meta.url);
-const packageMetadata = require("../../package.json");
-export async function runDoctor(projectRoot, options = {}) {
+import { CONTEXT_DOCTOR_DEFAULTS, } from "./context-doctor/context-doctor-types.js";
+import { MANAGED_BLOCK_START, MANAGED_BLOCK_END } from "./managed-file.js";
+export async function runDoctor(repository, options = {}) {
     const report = { info: [], warnings: [], errors: [] };
-    const root = await harnessRoot(projectRoot);
-    const relativeConfigPath = await harnessConfigPath(projectRoot);
-    const configPath = path.join(projectRoot, relativeConfigPath);
-    if (!(await pathExists(configPath))) {
-        report.errors.push(`missing ${relativeConfigPath}`);
-        return report;
-    }
-    const config = await readConfig(projectRoot);
-    const packageVersion = packageMetadata.version ?? "0.0.0";
-    report.info.push(`harness root: ${root}`);
-    report.info.push(`core package: ${config.core.package}@${packageVersion}`);
-    report.info.push(`schema version: ${config.core.schema_version}`);
-    const unsupportedSchema = unsupportedSchemaMessage(config.core.schema_version, "doctor");
-    if (unsupportedSchema) {
-        report.errors.push(unsupportedSchema);
-        return report;
-    }
-    for (const required of [
-        "project_context/context.toml",
-        "project_context/global.md",
-        "project_context/architecture.md",
-        "project_context/areas",
-    ]) {
-        if (!(await pathExists(path.join(projectRoot, required)))) {
-            report.errors.push(`missing ${required}`);
-        }
-    }
-    for (const managed of config.managed_files) {
-        const exists = await pathExists(path.join(projectRoot, managed.path));
-        if (!exists && managed.strategy !== "create-if-missing") {
-            report.warnings.push(`managed path missing: ${managed.path}`);
-        }
-    }
     try {
-        const footprint = await inspectDefaultContextFootprint(projectRoot);
-        report.info.push(`default Context read path: ${footprint.files.length} file(s), ${footprint.total_bytes} bytes`);
-        if (footprint.total_bytes > DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES) {
-            report.warnings.push(`default Context read path is ${footprint.total_bytes} bytes, above the ${DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES}-byte soft budget; review duplication or specialized placement only when complete, readable recovery semantics remain intact—required near-universal facts take precedence`);
-        }
-        for (const file of footprint.files) {
-            if (file.bytes <= DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES)
-                continue;
-            report.warnings.push(`default Context file ${file.path} is ${file.bytes} bytes, above the ${DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES}-byte per-file soft budget; this is advisory only and required readable facts take precedence`);
-        }
-        for (const group of footprint.duplicate_groups) {
-            report.warnings.push(`default Context contains byte-identical files: ${group.join(", ")}; keep one owning fact source and replace duplicates with a short pointer`);
-        }
+        const version = await rawSchemaVersion(repository);
+        if (!version)
+            report.errors.push("Harness configuration is missing; use init.");
+        else {
+            report.info.push("Harness schema: " + version);
+            const unsupported = unsupportedSchemaMessage(version, "doctor");
+            if (unsupported)
+                report.errors.push(unsupported);
+            else if (version !== "5")
+                report.warnings.push("Explicit upgrade required before schema-5 writes; old recovery tools must be version-pinned.");
+        }
+        const validation = await runValidator(repository, "validate-context");
+        report.info.push(...validation.info);
+        report.errors.push(...validation.errors);
+        report.warnings.push(...(validation.warnings ?? []));
+        const footprint = await inspectDefaultContextFootprint(repository);
+        report.info.push("Default body files: " +
+            footprint.files.length +
+            "; bytes: " +
+            footprint.total_bytes);
+        for (const file of footprint.files)
+            if (file.bytes >
+                (options.context_file_soft_budget_bytes ??
+                    CONTEXT_DOCTOR_DEFAULTS.context_file_soft_budget_bytes))
+                report.warnings.push("Review long default Context when useful: " + file.path);
+        for (const group of footprint.duplicate_groups)
+            report.warnings.push("Identical default files: " + group.join(", "));
     }
     catch (error) {
-        report.warnings.push(`default Context footprint unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        report.errors.push(String(error));
     }
     try {
-        const contextHealth = await inspectContextCatalogHealth(projectRoot, options);
-        report.info.push(...contextHealth.info);
-        report.warnings.push(...contextHealth.warnings);
-        report.errors.push(...contextHealth.errors);
-    }
-    catch (error) {
-        report.warnings.push(`all-Context diagnostics unavailable: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    const designAuthority = await inspectDesignAuthority(projectRoot);
-    if (designAuthority.status === "unconfigured") {
-        report.info.push("design authority: unconfigured; DESIGN.md is a starter scaffold and does not authorize material production UI until project-specific tokens and exact-target/constraint/inspiration references are selected");
+        const agents = await readFile(path.join(repository, "AGENTS.md"), "utf8");
+        if (!agents.includes(MANAGED_BLOCK_START) ||
+            !agents.includes(MANAGED_BLOCK_END))
+            report.warnings.push("AGENTS.md has no complete Tiny Context managed block.");
     }
-    else {
-        report.info.push(`design authority: ${designAuthority.status}${designAuthority.status === "configured" ? "; project-level visual-system configuration only" : ""}`);
+    catch {
+        report.warnings.push("AGENTS.md is unreadable or missing.");
     }
-    if (designAuthority.status === "configured") {
-        report.info.push(`design authority signals: index=${designAuthority.has_authority_index ? "present" : "missing"}, token_source=${designAuthority.token_source_selected ? "selected" : "missing-or-unselected"}, classified_references=${designAuthority.classified_reference_count}`);
-        if (!designAuthority.has_authority_index) {
-            report.warnings.push("configured DESIGN.md has no Design Authority Index; add the authored token source/generation direction and classified exact-target/constraint/inspiration references when material UI depends on them");
-        }
-        else {
-            if (!designAuthority.token_source_selected) {
-                report.warnings.push("Design Authority Index has no selected authored token source; generated tokens or current CSS must not become competing visual authority");
-            }
-            if (designAuthority.classified_reference_count === 0) {
-                report.warnings.push("Design Authority Index has no classified durable design references; inspiration, constraints and exact targets remain undeclared for material surfaces");
-            }
-        }
-    }
-    const authorityClosure = await inspectDesignAuthorityClosure(projectRoot);
-    if (authorityClosure.status === "valid" && authorityClosure.identity) {
-        report.info.push(`design authority closure: ${authorityClosure.mode}, ${authorityClosure.members.length} member(s), ${authorityClosure.identity.closure_digest}`);
-    }
-    else if (authorityClosure.status === "invalid") {
-        for (const diagnostic of authorityClosure.diagnostics) {
-            const detail = `design authority closure ${diagnostic.code}${diagnostic.path ? ` (${diagnostic.path})` : ""}: ${diagnostic.detail}`;
-            if (diagnostic.severity === "error")
-                report.errors.push(detail);
-            else
-                report.warnings.push(detail);
-        }
-    }
-    if (authorityClosure.status === "valid")
-        for (const diagnostic of authorityClosure.diagnostics)
-            if (diagnostic.severity === "warning")
-                report.warnings.push(`design authority closure ${diagnostic.code}${diagnostic.path ? ` (${diagnostic.path})` : ""}: ${diagnostic.detail}`);
-    report.info.push("surface implementation readiness: not inferred; inspect owning Product Surface/Screen/Control Context, selected target or constraints, authored token source and project-owned verification for each material surface");
-    for (const location of await findUserSuperpowersSkills()) {
-        report.warnings.push(`user-level using-superpowers Skill detected at ${location}. Tiny Context workflows do not depend on it and doctor will not modify global configuration. To disable it explicitly for Codex, remove/disable that plugin or add a matching [[skills.config]] entry with enabled = false in ${path.join(os.homedir(), ".codex", "config.toml")}.`);
-    }
-    report.info.push("doctor complete");
+    if (await pathExists(path.join(repository, "AGENTS.override.md")))
+        report.warnings.push("AGENTS.override.md may shadow root AGENTS.md. Review the actual host entry; files existing does not prove the instructions were loaded.");
+    report.info.push("Host-specific global/nested overrides and loaded instructions are not proven by this structural inspection. No global configuration is changed.");
     return report;
 }
-async function findUserSuperpowersSkills() {
-    const home = os.homedir();
-    const direct = path.join(home, ".codex", "skills", "using-superpowers", "SKILL.md");
-    const result = [];
-    if (await pathExists(direct))
-        result.push(direct);
-    const cache = path.join(home, ".codex", "plugins", "cache");
-    try {
-        for (const owner of await readdir(cache)) {
-            const candidateRoot = path.join(cache, owner);
-            for (const plugin of await readdir(candidateRoot)) {
-                if (plugin !== "superpowers")
-                    continue;
-                for (const version of await readdir(path.join(candidateRoot, plugin))) {
-                    const candidate = path.join(candidateRoot, plugin, version, "skills", "using-superpowers", "SKILL.md");
-                    if (await pathExists(candidate))
-                        result.push(candidate);
-                }
-            }
-        }
-    }
-    catch { }
-    return [...new Set(result)].sort();
-}

package/dist/lib/init.js

@@ -1,38 +1,41 @@
 import path from "node:path";
 import { CONTEXT_MANIFEST_PATH, defaultContextManifestTemplate, } from "./context-manifest.js";
-import { architectureContextTemplate, areaContextTemplate, globalContextTemplate, verificationContextTemplate, } from "./context-templates.js";
+import { globalContextTemplate } from "./context-templates.js";
 import { writeConfigIfMissing } from "./config.js";
-import { createDesignMdIfMissing, DESIGN_MD_PATH } from "./design-md.js";
 import { harnessConfigPath } from "./harness-root.js";
-import { ensureDir, pathExists, writeTextIfChanged } from "./fs.js";
+import { pathExists } from "./fs.js";
 import { assertSupportedSchema } from "./schema-guard.js";
-import { runSync } from "./sync-engine.js";
+import { syncStartupInstructions } from "./sync-engine.js";
+import { withMaintenanceLock } from "./maintenance-lock.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { writeMaintenanceText } from "./maintenance-write.js";
+import { assertNoUnfinishedContextMutation } from "./context-mutation/mutation-command-support.js";
 export async function runInit(projectRoot, options) {
-    const report = [];
     await assertSupportedSchema(projectRoot, "init");
-    const existingEntries = await projectHasExistingFiles(projectRoot);
-    if (existingEntries && !options.adopt && !options.force) {
-        report.push("Project is not empty; continuing with non-destructive init. Use --adopt to mark this as an existing project adoption.");
-    }
-    const configPath = await harnessConfigPath(projectRoot);
-    if (await writeConfigIfMissing(projectRoot)) {
-        report.push(`created ${configPath}`);
-    }
-    else {
-        report.push(`kept existing ${configPath}`);
-    }
-    await createProjectContext(projectRoot, report);
-    await createDesignMd(projectRoot, report);
-    const syncReport = await runSync(projectRoot);
-    report.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
-    report.push(...(syncReport.notices ?? []));
-    report.push(options.adopt ? "adopt mode complete" : "init complete");
-    return report;
-}
-async function createDesignMd(projectRoot, report) {
-    if (await createDesignMdIfMissing(projectRoot)) {
-        report.push(`created ${DESIGN_MD_PATH}`);
-    }
+    return withMaintenanceLock(projectRoot, "sync", async () => {
+        const report = [];
+        await assertSupportedSchema(projectRoot, "init");
+        await assertNoUnfinishedContextMutation(projectRoot);
+        const existingEntries = await projectHasExistingFiles(projectRoot);
+        if (existingEntries && !options.adopt && !options.force) {
+            report.push("Project is not empty; continuing with non-destructive init. Use --adopt to mark this as an existing project adoption.");
+        }
+        const configPath = await harnessConfigPath(projectRoot);
+        if (await writeConfigIfMissing(projectRoot)) {
+            report.push(`created ${configPath}`);
+        }
+        else {
+            report.push(`kept existing ${configPath}`);
+        }
+        await createProjectContext(projectRoot, report);
+        const syncReport = await syncStartupInstructions(projectRoot);
+        report.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
+        report.push(...(syncReport.notices ?? []));
+        if (syncReport.blocked.length)
+            throw new Error(`init incomplete: ${syncReport.blocked.join("; ")}`);
+        report.push(options.adopt ? "adopt mode complete" : "init complete");
+        return report;
+    });
 }
 async function projectHasExistingFiles(projectRoot) {
     const markers = ["README.md", "src", "pyproject.toml", "go.mod"];
@@ -44,25 +47,17 @@ async function projectHasExistingFiles(projectRoot) {
     return false;
 }
 async function createProjectContext(projectRoot, report) {
-    const areasRoot = path.join(projectRoot, "project_context", "areas");
-    await ensureDir(areasRoot);
     const files = [
         [CONTEXT_MANIFEST_PATH, defaultContextManifestTemplate()],
         ["project_context/global.md", globalContextTemplate()],
-        ["project_context/architecture.md", architectureContextTemplate()],
-        ["project_context/areas/main.md", areaContextTemplate("main")],
-        [
-            "project_context/areas/main/verification.md",
-            verificationContextTemplate("main"),
-        ],
     ];
     for (const [relative, content] of files) {
-        const target = path.join(projectRoot, relative);
-        if (await pathExists(target)) {
+        const before = await captureMutationFileState(projectRoot, relative);
+        if (before.exists) {
             report.push(`kept existing ${relative}`);
             continue;
         }
-        if (await writeTextIfChanged(target, content)) {
+        if (await writeMaintenanceText(projectRoot, relative, content, before)) {
             report.push(`created ${relative}`);
         }
     }

package/dist/lib/maintenance-lock.d.ts

@@ -0,0 +1,3 @@
+type MaintenanceOperation = "sync" | "upgrade" | "context_mutation" | "export";
+export declare function withMaintenanceLock<T>(repository: string, operation: MaintenanceOperation, action: () => Promise<T>): Promise<T>;
+export {};