youmd 0.10.2 → 0.12.0

package/dist/lib/goalRegistryFile.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Read-only repository evidence for a single Project Brain goal.
+ *
+ * This is intentionally not an apply mechanism.  Callers may create canonical
+ * documents and exact replacement proposals, but a repository owner must apply
+ * those proposals through the guarded proposal plane.  The only paths this
+ * module will inspect are:
+ *   project-context/goals/<goal-id>/goal.json
+ *   project-context/goals/<goal-id>/events/NNNNNN.json
+ *   project-context/goals/<goal-id>/reviews/<review-id>.json
+ */
+export declare const GOAL_REGISTRY_GOAL_SCHEMA: "https://you.md/schemas/project-goal/v1";
+export declare const GOAL_REGISTRY_GOAL_VERSION: "you-md/project-goal/v1";
+export declare const GOAL_REGISTRY_EVENT_SCHEMA: "https://you.md/schemas/project-goal-event/v1";
+export declare const GOAL_REGISTRY_EVENT_VERSION: "you-md/project-goal-event/v1";
+export declare const GOAL_REGISTRY_REVIEW_SCHEMA: "https://you.md/schemas/project-goal-review/v1";
+export declare const GOAL_REGISTRY_REVIEW_VERSION: "you-md/project-goal-review/v1";
+export declare const GOAL_REGISTRY_PROPOSAL_VERSION: "you-md/goal-registry-proposal/v1";
+declare const STATUS: readonly ["active", "blocked", "completion_claimed", "reviewing", "completed", "reopened"];
+declare const EVENT_TYPES: readonly ["created", "blocked", "resumed", "completion_claimed", "review_started", "review_passed", "review_failed", "owner_reopened"];
+export type GoalRegistryStatus = typeof STATUS[number];
+export type GoalRegistryEventType = typeof EVENT_TYPES[number];
+export type GoalRegistryCriterion = {
+    criterionRef: string;
+    text: string;
+    taskRefs: string[];
+};
+export type GoalRegistryEvidence = {
+    evidenceRef: string;
+    sha256: string;
+    revision: string;
+    provenance: {
+        sourceRef: string;
+        sourceRevision: string;
+    };
+};
+export type GoalRegistryCriterionResult = {
+    criterionRef: string;
+    passed: boolean;
+    taskRefs: string[];
+    evidenceRefs: GoalRegistryEvidence[];
+};
+export interface GoalRegistryGoal {
+    $schema: typeof GOAL_REGISTRY_GOAL_SCHEMA;
+    schemaVersion: typeof GOAL_REGISTRY_GOAL_VERSION;
+    kind: "project-goal";
+    id: string;
+    goalRef: string;
+    projectRef: string;
+    goalRevision: string;
+    status: GoalRegistryStatus;
+    outcome: string;
+    successCriteria: GoalRegistryCriterion[];
+    rootTaskRefs: string[];
+    producerAgentRefs: string[];
+    currentReviewRef?: string;
+    templateRef?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GoalRegistryEvent {
+    $schema: typeof GOAL_REGISTRY_EVENT_SCHEMA;
+    schemaVersion: typeof GOAL_REGISTRY_EVENT_VERSION;
+    kind: "project-goal-event";
+    eventRef: string;
+    goalRef: string;
+    sequence: number;
+    eventType: GoalRegistryEventType;
+    fromStatus: GoalRegistryStatus | null;
+    toStatus: GoalRegistryStatus;
+    actorAgentRef: string;
+    occurredAt: string;
+    baseRevision: string;
+    goalRevision: string;
+    previousEventHash: string | null;
+    eventHash: string;
+    evidenceRefs: GoalRegistryEvidence[];
+    reviewRef?: string;
+    criteriaResults?: GoalRegistryCriterionResult[];
+    remediationTaskRefs?: string[];
+}
+export interface GoalRegistryReview {
+    $schema: typeof GOAL_REGISTRY_REVIEW_SCHEMA;
+    schemaVersion: typeof GOAL_REGISTRY_REVIEW_VERSION;
+    kind: "project-goal-review";
+    reviewRef: string;
+    goalId: string;
+    goalRef: string;
+    goalRevision: string;
+    baseEventHash: string;
+    reviewerAgentRef: string;
+    producerAgentRefs: string[];
+    verdict: "approved" | "rejected";
+    successCriteriaResults: GoalRegistryCriterionResult[];
+    remediationTaskRefs: string[];
+    reviewedAt: string;
+}
+export interface GoalRegistryPaths {
+    root: string;
+    goal: string;
+    events: string;
+    reviews: string;
+    event(sequence: number): string;
+    review(reviewId: string): string;
+}
+export interface GoalRegistrySnapshot {
+    goal: GoalRegistryGoal;
+    events: GoalRegistryEvent[];
+    reviews: GoalRegistryReview[];
+    status: GoalRegistryStatus;
+    lastEventHash: string | null;
+    lastEventRef?: string;
+}
+export interface GoalRegistryExactProposal {
+    schemaVersion: typeof GOAL_REGISTRY_PROPOSAL_VERSION;
+    kind: "goal-registry-proposal";
+    proposalRef: string;
+    status: "proposed";
+    authority: "review_only";
+    applySupported: false;
+    target: {
+        path: string;
+        exists: boolean;
+        owner: "repository";
+        writePolicy: "propose";
+        baseContentHash: string;
+    };
+    replacement: {
+        format: "whole_file";
+        content: string;
+        contentHash: string;
+    };
+    approval: {
+        required: true;
+        policy: "fresh_exact_replacement";
+        reusable: false;
+    };
+}
+export type GoalRegistryFileErrorCode = "GOAL_REGISTRY_INVALID_JSON" | "GOAL_REGISTRY_INVALID_DOCUMENT" | "GOAL_REGISTRY_INVALID_PATH" | "GOAL_REGISTRY_SYMLINK_REFUSED" | "GOAL_REGISTRY_READ_FAILED" | "GOAL_REGISTRY_SECRET_DETECTED" | "GOAL_REGISTRY_CANARY_DETECTED" | "GOAL_REGISTRY_REVISION_MISMATCH" | "GOAL_REGISTRY_EVENT_HASH_MISMATCH" | "GOAL_REGISTRY_SEQUENCE_MISMATCH" | "GOAL_REGISTRY_EVENT_CHAIN_MISMATCH" | "GOAL_REGISTRY_STALE_BASE" | "GOAL_REGISTRY_INVALID_TRANSITION" | "GOAL_REGISTRY_REVIEW_REQUIRED" | "GOAL_REGISTRY_REVIEW_INVALID" | "GOAL_REGISTRY_REVIEWER_NOT_INDEPENDENT" | "GOAL_REGISTRY_OWNER_AUTH_REQUIRED";
+export declare class GoalRegistryFileError extends Error {
+    readonly code: GoalRegistryFileErrorCode;
+    constructor(code: GoalRegistryFileErrorCode, message: string);
+}
+export declare function goalRegistryPaths(goalId: string, contextRoot?: string): GoalRegistryPaths;
+export declare function createGoalRegistryGoalDocument(input: Omit<GoalRegistryGoal, "$schema" | "schemaVersion" | "kind" | "goalRef" | "goalRevision" | "status" | "updatedAt" | "currentReviewRef">): GoalRegistryGoal;
+export declare function parseGoalRegistryGoal(value: unknown, canaries?: string[]): GoalRegistryGoal;
+export declare function createGoalRegistryEventDocument(input: Omit<GoalRegistryEvent, "$schema" | "schemaVersion" | "kind" | "eventRef" | "eventHash" | "fromStatus" | "toStatus">): GoalRegistryEvent;
+export declare function parseGoalRegistryEvent(value: unknown, goal: GoalRegistryGoal, canaries?: string[]): GoalRegistryEvent;
+export declare function parseGoalRegistryReview(value: unknown, goal: GoalRegistryGoal, canaries?: string[]): GoalRegistryReview;
+/** Create a canonical review document in memory. It never writes to a repository. */
+export declare function createGoalRegistryReviewDocument(goal: GoalRegistryGoal, input: Omit<GoalRegistryReview, "$schema" | "schemaVersion" | "kind" | "reviewRef" | "goalId" | "goalRef" | "goalRevision"> & {
+    reviewId: string;
+}): GoalRegistryReview;
+export declare function replayGoalRegistryEvents(goal: GoalRegistryGoal, events: GoalRegistryEvent[], reviews: GoalRegistryReview[], ownerAuthorized?: boolean): GoalRegistrySnapshot;
+/** Read and replay one on-disk goal. This function never modifies the repository. */
+export declare function readGoalRegistry(repoRoot: string, goalId: string, options?: {
+    contextRoot?: string;
+    canaries?: string[];
+    ownerAuthorized?: boolean;
+}): GoalRegistrySnapshot;
+/** Produce a review-only exact replacement proposal for a canonical goal artifact. */
+export declare function proposeGoalRegistryArtifact(options: {
+    repoRoot: string;
+    relativePath: string;
+    content: string;
+    canaries?: string[];
+}): GoalRegistryExactProposal | null;
+export {};
+//# sourceMappingURL=goalRegistryFile.d.ts.map

package/dist/lib/goalRegistryFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goalRegistryFile.d.ts","sourceRoot":"","sources":["../../src/lib/goalRegistryFile.ts"],"names":[],"mappings":"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"}