project-tiny-context-harness 0.2.39

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

@@ -0,0 +1,3 @@
+export declare const CONTEXT_MANIFEST_PATH = "project_context/context.toml";
+export declare function defaultContextManifestTemplate(): string;
+export declare function contextManifestFromExistingAreas(projectRoot: string): Promise<string>;

package/dist/lib/context-manifest.js

@@ -0,0 +1,103 @@
+import path from "node:path";
+import { listFiles } from "./fs.js";
+export const CONTEXT_MANIFEST_PATH = "project_context/context.toml";
+export function defaultContextManifestTemplate() {
+    return [
+        "# Schema v4 Minimal Context graph manifest.",
+        "# Keep the default product/domain area for ordinary projects. Role context nodes",
+        "# are read-purpose slices owned by an area or, only when cross-domain, by the project root.",
+        "# When migrating deep files under project_context/areas/**, refine obvious",
+        "# contract/foundation/subdomain/verification/deployment/implementation-index/",
+        "# decision-rationale/archive files into [[context]] entries instead of keeping",
+        "# every Markdown file as an [[areas]] product owner.",
+        "",
+        "[[areas]]",
+        "id = \"main\"",
+        "root = \".\"",
+        "context = \"project_context/areas/main.md\"",
+        "kind = \"app\"",
+        "default = true",
+        "",
+        "[[context]]",
+        "path = \"project_context/areas/main/verification.md\"",
+        "role = \"verification\"",
+        "read_policy = \"default\"",
+        "triggers = [\"test\", \"verify\", \"verification\", \"smoke\", \"ci\"]",
+        "",
+        "# Example optional node:",
+        "# [[context]]",
+        "# path = \"project_context/areas/main/deployment.md\"",
+        "# role = \"deployment\"",
+        "# read_policy = \"on-demand\"",
+        "# triggers = [\"deploy\", \"deployment\", \"runtime\", \"cloud\", \"docker\"]",
+        ""
+    ].join("\n");
+}
+export async function contextManifestFromExistingAreas(projectRoot) {
+    const areasRoot = path.join(projectRoot, "project_context", "areas");
+    const areas = (await listFiles(areasRoot))
+        .filter((file) => file.endsWith(".md"))
+        .sort();
+    if (areas.length === 0) {
+        return defaultContextManifestTemplate();
+    }
+    const lines = [
+        "# Schema v4 Minimal Context graph manifest.",
+        "# Auto-created by upgrade from existing project_context/areas/**/*.md files.",
+        "# Review deep or non-area context and move it to explicit [[context]] role entries",
+        "# such as subdomain, contract, foundation, verification, deployment, archive,",
+        "# implementation-index or decision-rationale when needed.",
+        ""
+    ];
+    const areaEntries = [];
+    const contextEntries = [];
+    for (const areaPath of areas) {
+        const relativeToAreas = path.relative(areasRoot, areaPath).split(path.sep).join("/");
+        const contextPath = `project_context/areas/${relativeToAreas}`;
+        const id = contextUnitId(relativeToAreas);
+        const role = inferredRoleContext(relativeToAreas);
+        if (role) {
+            contextEntries.push({
+                path: contextPath,
+                role,
+                triggers: role === "verification"
+                    ? ["test", "verify", "verification", "smoke", "ci"]
+                    : ["deploy", "deployment", "runtime", "cloud", "docker"]
+            });
+        }
+        else {
+            areaEntries.push({ contextPath, id });
+        }
+    }
+    const defaultId = areaEntries.some((entry) => entry.id === "main") ? "main" : areaEntries[0]?.id;
+    for (const { contextPath, id } of areaEntries) {
+        lines.push("[[areas]]", `id = "${id}"`, "root = \".\"", `context = "${contextPath}"`, `kind = "${id === "main" ? "app" : "context-unit"}"`, id === defaultId ? "default = true" : "default = false", "");
+    }
+    for (const context of contextEntries) {
+        lines.push("[[context]]", `path = "${context.path}"`, `role = "${context.role}"`, context.role === "verification" ? "read_policy = \"default\"" : "read_policy = \"on-demand\"", `triggers = [${context.triggers.map((trigger) => `"${trigger}"`).join(", ")}]`, "");
+    }
+    return lines.join("\n");
+}
+function inferredRoleContext(relativeToAreas) {
+    const normalized = relativeToAreas.toLowerCase();
+    if (normalized.endsWith("/verification.md") || normalized === "verification.md") {
+        return "verification";
+    }
+    if (normalized.endsWith("/deployment.md") || normalized === "deployment.md") {
+        return "deployment";
+    }
+    return undefined;
+}
+function contextUnitId(relativeToAreas) {
+    const withoutExtension = relativeToAreas.replace(/\.md$/i, "");
+    const parts = withoutExtension.split("/");
+    const last = parts.at(-1)?.toLowerCase();
+    const semanticParts = last === "readme" || last === "index" ? parts.slice(0, -1) : parts;
+    const raw = (semanticParts.length > 0 ? semanticParts : ["main"]).join("-");
+    const slug = raw
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "main";
+}

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,204 @@
+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 the safest next step for a fresh agent, including whether the next change should update Context before code.",
+        "",
+        "## 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.",
+        "",
+        "## 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.",
+        "",
+        "## 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");
+}

package/dist/lib/design-md.d.ts

@@ -0,0 +1,2 @@
+export declare const DESIGN_MD_PATH = "DESIGN.md";
+export declare function createDesignMdIfMissing(projectRoot: string): Promise<boolean>;

package/dist/lib/design-md.js

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { pathExists, writeTextIfChanged } from "./fs.js";
+export const DESIGN_MD_PATH = "DESIGN.md";
+export async function createDesignMdIfMissing(projectRoot) {
+    const target = path.join(projectRoot, DESIGN_MD_PATH);
+    if (await pathExists(target)) {
+        return false;
+    }
+    return writeTextIfChanged(target, designMdTemplate());
+}
+function designMdTemplate() {
+    return [
+        "---",
+        'version: "alpha"',
+        'name: "Starter Design System"',
+        'description: "Neutral baseline design guidance for projects that have not defined their own visual system."',
+        "colors:",
+        '  canvas: "#F8FAFC"',
+        '  surface: "#FFFFFF"',
+        '  surface-muted: "#EEF2F7"',
+        '  text: "#172033"',
+        '  text-muted: "#5D6B82"',
+        '  primary: "#2563EB"',
+        '  primary-hover: "#1D4ED8"',
+        '  on-primary: "#FFFFFF"',
+        "typography:",
+        "  display:",
+        '    fontFamily: "Public Sans"',
+        '    fontSize: "2.5rem"',
+        "    fontWeight: 700",
+        "    lineHeight: 1.1",
+        "  title:",
+        '    fontFamily: "Public Sans"',
+        '    fontSize: "1.5rem"',
+        "    fontWeight: 700",
+        "    lineHeight: 1.25",
+        "  body:",
+        '    fontFamily: "Public Sans"',
+        '    fontSize: "1rem"',
+        "    fontWeight: 400",
+        "    lineHeight: 1.6",
+        "  label:",
+        '    fontFamily: "Public Sans"',
+        '    fontSize: "0.875rem"',
+        "    fontWeight: 600",
+        "    lineHeight: 1.3",
+        "rounded:",
+        "  sm: 4px",
+        "  md: 8px",
+        "  lg: 12px",
+        "spacing:",
+        "  xs: 4px",
+        "  sm: 8px",
+        "  md: 16px",
+        "  lg: 24px",
+        "  xl: 32px",
+        "components:",
+        "  app-shell:",
+        '    backgroundColor: "{colors.canvas}"',
+        '    textColor: "{colors.text}"',
+        "  surface-card:",
+        '    backgroundColor: "{colors.surface}"',
+        '    textColor: "{colors.text}"',
+        '    rounded: "{rounded.md}"',
+        "    padding: 16px",
+        "  quiet-control:",
+        '    backgroundColor: "{colors.surface-muted}"',
+        '    textColor: "{colors.text-muted}"',
+        '    rounded: "{rounded.sm}"',
+        "    padding: 8px",
+        "  primary-action:",
+        '    backgroundColor: "{colors.primary}"',
+        '    textColor: "{colors.on-primary}"',
+        '    typography: "{typography.label}"',
+        '    rounded: "{rounded.md}"',
+        "    padding: 12px",
+        "  primary-action-hover:",
+        '    backgroundColor: "{colors.primary-hover}"',
+        '    textColor: "{colors.on-primary}"',
+        '    typography: "{typography.label}"',
+        '    rounded: "{rounded.md}"',
+        "    padding: 12px",
+        "---",
+        "",
+        "# Design System",
+        "",
+        "## Overview",
+        "",
+        "- This is a starter visual system for projects that have not defined their own design rules yet.",
+        "- User-authored tokens, brand rules and later product decisions take precedence over this starter baseline.",
+        "- Keep durable color, typography, spacing, radius, component and interaction choices here so future UI work does not drift.",
+        "",
+        "## Colors",
+        "",
+        "- Use `canvas` for the page background, `surface` for panels and `surface-muted` for quiet controls or secondary regions.",
+        "- Keep primary actions on `primary` with `on-primary` text; use `primary-hover` for hover and active emphasis.",
+        "- Avoid introducing decorative gradients, random accent colors or single-hue palettes unless the product brand explicitly calls for them.",
+        "",
+        "## Typography",
+        "",
+        "- Use `display` only for true page-level emphasis, `title` for section and panel headings, `body` for readable content and `label` for controls.",
+        "- Preserve hierarchy through size, weight and spacing before adding extra colors or decoration.",
+        "",
+        "## Layout",
+        "",
+        "- Start with clear page structure: canvas, surfaces, primary action, secondary controls and readable content regions.",
+        "- Use the spacing scale consistently; dense operational screens can reduce vertical whitespace, while marketing or editorial surfaces can breathe more.",
+        "- On small screens, stack content in priority order and keep primary actions reachable without overlapping other UI.",
+        "",
+        "## Components",
+        "",
+        "- Buttons, inputs, cards, navigation and dialogs need default, hover, active, focus, disabled, loading and error states when they are user-facing.",
+        "- Use `surface-card` for contained groups, `quiet-control` for low-emphasis controls and `primary-action` for the main command.",
+        "- Prefer clear affordances, visible focus states and stable dimensions so labels, icons and dynamic text do not resize the layout.",
+        "",
+        "## Do's and Don'ts",
+        "",
+        "- Do use this file as the first design fact source before generating mockups, Figma screens or frontend UI.",
+        "- Do replace or extend this starter when the project has a real brand, product category or design system.",
+        "- Do keep accessibility, responsive behavior and interaction states explicit.",
+        "- Don't treat this starter as a user brand decision once project-specific rules exist.",
+        "- Don't add generic AI-looking hero gradients, oversized cards or decorative blobs unless the product direction asks for them.",
+        "",
+        "## Design Change Workflow",
+        "",
+        "- Read this file before creating design drafts, redesigning UI, changing visual systems or polishing frontend styling.",
+        "- When there is a scan target such as UI source, page files, build output or a local/remote URL, run `npx impeccable detect <target>` before finalizing design changes.",
+        "- Treat Impeccable findings as design-review signals: fix issues that affect clarity, consistency, accessibility or trust, and note when there is no suitable scan target.",
+        "- After design decisions stabilize, update this file with durable tokens, component rules and do/don't guidance so later UI work stays aligned.",
+        ""
+    ].join("\n");
+}

package/dist/lib/doctor.d.ts

@@ -0,0 +1,6 @@
+export interface DoctorReport {
+    info: string[];
+    warnings: string[];
+    errors: string[];
+}
+export declare function runDoctor(projectRoot: string): Promise<DoctorReport>;

package/dist/lib/doctor.js

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { readConfig } from "./config.js";
+import { harnessConfigPath, harnessRoot } from "./harness-root.js";
+import { pathExists } from "./fs.js";
+import { unsupportedSchemaMessage } from "./schema-guard.js";
+const require = createRequire(import.meta.url);
+const packageMetadata = require("../../package.json");
+export async function runDoctor(projectRoot) {
+    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}`);
+        }
+    }
+    report.info.push("doctor complete");
+    return report;
+}

package/dist/lib/fs.d.ts

@@ -0,0 +1,8 @@
+export declare function pathExists(target: string): Promise<boolean>;
+export declare function readText(target: string): Promise<string>;
+export declare function ensureDir(target: string): Promise<void>;
+export declare function writeTextIfChanged(target: string, content: string): Promise<boolean>;
+export declare function listFiles(root: string): Promise<string[]>;
+export declare function copyTree(sourceRoot: string, destinationRoot: string, options?: {
+    skipGitkeep?: boolean;
+}): Promise<string[]>;

package/dist/lib/fs.js

@@ -0,0 +1,56 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readText(target) {
+    return fs.readFile(target, "utf8");
+}
+export async function ensureDir(target) {
+    await fs.mkdir(target, { recursive: true });
+}
+export async function writeTextIfChanged(target, content) {
+    if ((await pathExists(target)) && (await readText(target)) === content) {
+        return false;
+    }
+    await ensureDir(path.dirname(target));
+    await fs.writeFile(target, content, "utf8");
+    return true;
+}
+export async function listFiles(root) {
+    if (!(await pathExists(root))) {
+        return [];
+    }
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(fullPath)));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+export async function copyTree(sourceRoot, destinationRoot, options = {}) {
+    const changed = [];
+    for (const source of await listFiles(sourceRoot)) {
+        if (options.skipGitkeep && path.basename(source) === ".gitkeep") {
+            continue;
+        }
+        const relative = path.relative(sourceRoot, source);
+        const destination = path.join(destinationRoot, relative);
+        if (await writeTextIfChanged(destination, await readText(source))) {
+            changed.push(destination);
+        }
+    }
+    return changed;
+}

package/dist/lib/harness-root.d.ts

@@ -0,0 +1,9 @@
+export interface HarnessRootConfig {
+    harnessFolderName: string;
+    source: string;
+}
+export declare function readHarnessRootConfig(projectRoot: string): Promise<HarnessRootConfig>;
+export declare function harnessRoot(projectRoot: string): Promise<string>;
+export declare function harnessConfigPath(projectRoot: string): Promise<string>;
+export declare function harnessPath(root: string, ...segments: string[]): string;
+export declare function normalizeHarnessFolderName(value: string): string;

package/dist/lib/harness-root.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { DEFAULT_HARNESS_ROOT, HARNESS_JSON_CONFIG_PATH } from "./paths.js";
+import { pathExists, readText } from "./fs.js";
+export async function readHarnessRootConfig(projectRoot) {
+    const packageJson = await readJsonConfig(path.join(projectRoot, "package.json"));
+    const packageConfig = packageJson && typeof packageJson === "object" ? packageJson.sdlcHarness : undefined;
+    const packageValue = folderNameFromObject(packageConfig);
+    if (packageValue) {
+        return { harnessFolderName: normalizeHarnessFolderName(packageValue), source: "package.json#sdlcHarness" };
+    }
+    const explicitConfig = await readJsonConfig(path.join(projectRoot, HARNESS_JSON_CONFIG_PATH));
+    const explicitValue = folderNameFromObject(explicitConfig);
+    if (explicitValue) {
+        return { harnessFolderName: normalizeHarnessFolderName(explicitValue), source: HARNESS_JSON_CONFIG_PATH };
+    }
+    return { harnessFolderName: DEFAULT_HARNESS_ROOT, source: "default" };
+}
+export async function harnessRoot(projectRoot) {
+    return (await readHarnessRootConfig(projectRoot)).harnessFolderName;
+}
+export async function harnessConfigPath(projectRoot) {
+    return harnessPath(await harnessRoot(projectRoot), "config.yaml");
+}
+export function harnessPath(root, ...segments) {
+    return [root, ...segments].join("/").replace(/\/+/g, "/");
+}
+function folderNameFromObject(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const record = value;
+    const folderName = record.harnessFolderName ?? record.harnessFloderName;
+    return typeof folderName === "string" && folderName.trim() ? folderName : undefined;
+}
+async function readJsonConfig(filePath) {
+    if (!(await pathExists(filePath))) {
+        return undefined;
+    }
+    return JSON.parse(await readText(filePath));
+}
+export function normalizeHarnessFolderName(value) {
+    const normalized = value.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    if (!normalized || normalized === "." || normalized === "..") {
+        throw new Error("harnessFolderName must be a non-empty relative directory");
+    }
+    if (path.isAbsolute(normalized) || normalized.includes("..")) {
+        throw new Error("harnessFolderName must not be absolute or contain '..'");
+    }
+    return normalized;
+}

package/dist/lib/init.d.ts

@@ -0,0 +1,5 @@
+export interface InitOptions {
+    adopt: boolean;
+    force: boolean;
+}
+export declare function runInit(projectRoot: string, options: InitOptions): Promise<string[]>;