jg-agent-hq 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0
+
+- Preserve coordinator-owned, revision-bound plan comparison evidence through plan operations. Expose its bounded count in status without copying review bodies into responses.
+- Require the comparison collection in the coordination contract. The private coordinator owns semantic review, relevance selection and execution gates.
+
 ## 0.1.0
 
 - Add the shared lock API, owner-aware recovery and built-package verification.

package/README.md

@@ -59,6 +59,8 @@ Use `jg-agent-hq request --state-root <directory>` with a closed HQ command on s
 
 Finalization assigns milestone UUIDs and returns the complete canonical sequence. Plan approval, sequence approval and scoped execution authorization are separate explicit operator actions. None sends native input or answers tool permissions. `coordination.json` holds current records beside the plan. SQLite retains write replay identities and a replaceable, paged milestone projection. Keep both when recovering interrupted writes. A pending write blocks further mutation until its original action is reconciled.
 
+Coordinators can retain revision-bound compatibility reviews in that same file. Core operations preserve the records without assessing them or granting authority. The integrating coordinator owns review freshness and conflict gates.
+
 Begin a revision before native planning. HQ stops bound implementation threads and their owned background work, captures partial-work evidence, and keeps execution paused while the CLI revises the plan and regenerates milestones. The finalizer carries exact matches automatically and asks for one confirmation covering every unmatched completed or partial milestone. Equivalent rewording preserves the original completion evidence. Changed requirements remain pending. Present and approve the canonical sequence, then explicitly authorize the new execution scope and mode. Neither approval nor restart resumes implementation. See the [revision recovery contract](api/README.md#revision-and-progress-recovery).
 
 ## Cross-provider feedback

package/api/README.md

@@ -192,6 +192,8 @@ Plan and milestone artifacts are bounded to 1 MiB each; coordination evidence is
 
 Mutations hold the shared metadata lock at `<coordinationRoot>/.runtime/hq.lock` (`coordinationRoot` defaults to `stateRoot`), retain a durable action identity and intended write before changing files, sync temporary files and atomically replace each artifact. Use `serve --coordination-root <directory>` when the canonical coordination lock is separate from runtime storage. Repeating an action UUID with the identical payload never reapproves revoked work. A changed payload conflicts. An interrupted write remains blocked and can be retried with its original action only when files match the recorded baseline or exact intended output. Conflicting edits are preserved. Completed write bodies are removed from SQLite while replay identity remains. The current finalization receipt retains the operator event, execution revision, canonical file hash and timestamp independently of write recovery bodies. Status reads expose `pendingActionId` for unresolved writes; they never approve or resume work.
 
+`coordination.json` includes required `comparisons`, an array bounded to 1,024 records validated by `PlanComparisonSchema`. Each record binds `sourceRevision`, `targetDirectory`, `targetRevision`, a `compatible` or `contradiction` verdict, `reason`, `reviewedAt` and reviewer provenance (`provider`, `cliVersion`, nullable observed `model`, and native message `reference`). A trusted coordinator writes these records while holding the same metadata lock. Core operations preserve them; status exposes only `comparisonCount`. They never change execution digests or grant authority. The coordinator owns relevance, freshness, semantic judgments, bounded review reads and any execution gate, including contradictions. The standalone core does not assess compatibility.
+
 The installed `plan-status` and `plan-milestones` commands accept `--state-root` and `--directory`; the latter also accepts `--limit` and `--cursor`. Use `request` for the closed JSON mutation commands. The result is a tagged `status`, `milestones`, `reconciliation`, `reconciliation-required`, `finalized` or `execution-check` object within the outer `plan` response. A retried finalization returns current status when its finalized artifact no longer exists or has changed.
 
 ### Revision and progress recovery

package/dist/contracts/actions/types.d.ts

@@ -2,16 +2,16 @@ import { z } from 'zod';
 export declare const ActionCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"thread-create">;
     provider: z.ZodEnum<{
-        codex: "codex";
         claude: "claude";
+        codex: "codex";
     }>;
     workspaceRoot: z.ZodString;
     name: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"thread-adopt">;
     provider: z.ZodEnum<{
-        codex: "codex";
         claude: "claude";
+        codex: "codex";
     }>;
     workspaceRoot: z.ZodString;
     nativeId: z.ZodString;
@@ -158,16 +158,16 @@ export declare const ActionEnvelopeSchema: z.ZodObject<{
     command: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"thread-create">;
         provider: z.ZodEnum<{
-            codex: "codex";
             claude: "claude";
+            codex: "codex";
         }>;
         workspaceRoot: z.ZodString;
         name: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"thread-adopt">;
         provider: z.ZodEnum<{
-            codex: "codex";
             claude: "claude";
+            codex: "codex";
         }>;
         workspaceRoot: z.ZodString;
         nativeId: z.ZodString;
@@ -455,8 +455,8 @@ export type IActionSummary = z.infer<typeof ActionSummarySchema>;
 export declare const ManagedThreadSchema: z.ZodObject<{
     id: z.ZodUUID;
     provider: z.ZodEnum<{
-        codex: "codex";
         claude: "claude";
+        codex: "codex";
     }>;
     nativeId: z.ZodNullable<z.ZodString>;
     name: z.ZodString;

package/dist/contracts/handoffs/types.d.ts

@@ -2,8 +2,8 @@ import { z } from 'zod';
 export declare const HandoffSourceSchema: z.ZodObject<{
     threadId: z.ZodUUID;
     provider: z.ZodEnum<{
-        codex: "codex";
         claude: "claude";
+        codex: "codex";
     }>;
     nativeId: z.ZodString;
     workspaceRoot: z.ZodString;
@@ -116,8 +116,8 @@ export declare const HandoffSummarySchema: z.ZodObject<{
     source: z.ZodObject<{
         threadId: z.ZodUUID;
         provider: z.ZodEnum<{
-            codex: "codex";
             claude: "claude";
+            codex: "codex";
         }>;
         nativeId: z.ZodString;
         workspaceRoot: z.ZodString;
@@ -150,8 +150,8 @@ export declare const HandoffSummarySchema: z.ZodObject<{
     targetThreadId: z.ZodNullable<z.ZodUUID>;
     targetNativeId: z.ZodNullable<z.ZodString>;
     targetProvider: z.ZodEnum<{
-        codex: "codex";
         claude: "claude";
+        codex: "codex";
     }>;
     creation: z.ZodObject<{
         actionId: z.ZodNullable<z.ZodUUID>;
@@ -219,8 +219,8 @@ export declare const HandoffSchema: z.ZodObject<{
     source: z.ZodObject<{
         threadId: z.ZodUUID;
         provider: z.ZodEnum<{
-            codex: "codex";
             claude: "claude";
+            codex: "codex";
         }>;
         nativeId: z.ZodString;
         workspaceRoot: z.ZodString;
@@ -253,8 +253,8 @@ export declare const HandoffSchema: z.ZodObject<{
     targetThreadId: z.ZodNullable<z.ZodUUID>;
     targetNativeId: z.ZodNullable<z.ZodString>;
     targetProvider: z.ZodEnum<{
-        codex: "codex";
         claude: "claude";
+        codex: "codex";
     }>;
     creation: z.ZodObject<{
         actionId: z.ZodNullable<z.ZodUUID>;
@@ -353,8 +353,8 @@ export declare const HandoffResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
             threadId: z.ZodUUID;
             provider: z.ZodEnum<{
-                codex: "codex";
                 claude: "claude";
+                codex: "codex";
             }>;
             nativeId: z.ZodString;
             workspaceRoot: z.ZodString;
@@ -387,8 +387,8 @@ export declare const HandoffResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         targetThreadId: z.ZodNullable<z.ZodUUID>;
         targetNativeId: z.ZodNullable<z.ZodString>;
         targetProvider: z.ZodEnum<{
-            codex: "codex";
             claude: "claude";
+            codex: "codex";
         }>;
         creation: z.ZodObject<{
             actionId: z.ZodNullable<z.ZodUUID>;
@@ -486,8 +486,8 @@ export declare const HandoffResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodObject<{
             threadId: z.ZodUUID;
             provider: z.ZodEnum<{
-                codex: "codex";
                 claude: "claude";
+                codex: "codex";
             }>;
             nativeId: z.ZodString;
             workspaceRoot: z.ZodString;
@@ -520,8 +520,8 @@ export declare const HandoffResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         targetThreadId: z.ZodNullable<z.ZodUUID>;
         targetNativeId: z.ZodNullable<z.ZodString>;
         targetProvider: z.ZodEnum<{
-            codex: "codex";
             claude: "claude";
+            codex: "codex";
         }>;
         creation: z.ZodObject<{
             actionId: z.ZodNullable<z.ZodUUID>;

package/dist/contracts/index.d.ts

@@ -5,8 +5,8 @@ export { ActionCommandSchema, ActionEnvelopeSchema, ActionReceiptSchema, ActionS
 export type { IActionCommand, IActionEnvelope, IActionReceipt, IActionSummary, IManagedThread, INativeApproval, ILifecycleEvent, } from './actions/index.js';
 export { SkillIdSchema, NativeSkillInputSchema, SkillSchema, SkillPageSchema, SkillPreviewSchema, MessageInputSchema, } from './skills/index.js';
 export type { INativeSkillInput, ISkill, ISkillPage, ISkillPreview, IMessageInput, } from './skills/index.js';
-export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './plans/index.js';
-export type { IPlanRevision, IPlanMetadata, IPlanTarget, IPlanOperatorAction, IPlanCommand, IPlanCommandInput, IPlanCoordination, IPlanMilestone, IPlanStatus, IPlanResult, } from './plans/index.js';
+export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanComparisonSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './plans/index.js';
+export type { IPlanRevision, IPlanMetadata, IPlanTarget, IPlanOperatorAction, IPlanCommand, IPlanCommandInput, IPlanCoordination, IPlanComparison, IPlanMilestone, IPlanStatus, IPlanResult, } from './plans/index.js';
 export { PlanCheckSchema, PlanCheckoutSchema, PlanWorktreeProofSchema, PlanCompletionSchema, PlanSnapshotMilestoneSchema, PlanCorrespondenceSchema, PlanDraftMilestoneSchema, PlanProposalSchema, PlanRevisionWorkflowSchema, PlanCorrespondenceRecordSchema, PlanCoordinationSummarySchema, } from './plans/index.js';
 export type { IPlanCheckout, IPlanWorktreeProof, IPlanCompletion, IPlanSnapshotMilestone, IPlanCorrespondence, IPlanDraftMilestone, IPlanProposal, IPlanRevisionWorkflow, IPlanCorrespondenceRecord, } from './plans/index.js';
 export { PlanCheckpointSchema } from './plans/index.js';

package/dist/contracts/index.js

@@ -7,7 +7,7 @@ export { ActionCommandSchema, ActionEnvelopeSchema, ActionReceiptSchema, ActionS
 // native skills and explicit message input
 export { SkillIdSchema, NativeSkillInputSchema, SkillSchema, SkillPageSchema, SkillPreviewSchema, MessageInputSchema, } from './skills/index.js';
 // plan revisions and explicit authority
-export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './plans/index.js';
+export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanComparisonSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './plans/index.js';
 // revision checkpoints and retained verification
 export { PlanCheckSchema, PlanCheckoutSchema, PlanWorktreeProofSchema, PlanCompletionSchema, PlanSnapshotMilestoneSchema, PlanCorrespondenceSchema, PlanDraftMilestoneSchema, PlanProposalSchema, PlanRevisionWorkflowSchema, PlanCorrespondenceRecordSchema, PlanCoordinationSummarySchema, } from './plans/index.js';
 // saved revision baseline

package/dist/contracts/plans/index.d.ts

@@ -1,5 +1,5 @@
-export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './types.js';
-export type { IPlanRevision, IPlanMetadata, IPlanTarget, IPlanOperatorAction, IPlanCommand, IPlanCommandInput, IPlanCoordination, IPlanMilestone, IPlanStatus, IPlanResult, } from './types.js';
+export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanComparisonSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './types.js';
+export type { IPlanRevision, IPlanMetadata, IPlanTarget, IPlanOperatorAction, IPlanCommand, IPlanCommandInput, IPlanCoordination, IPlanComparison, IPlanMilestone, IPlanStatus, IPlanResult, } from './types.js';
 export { PlanCheckSchema, PlanCheckoutSchema, PlanWorktreeProofSchema, PlanCompletionSchema, PlanSnapshotMilestoneSchema, PlanCorrespondenceSchema, PlanDraftMilestoneSchema, PlanProposalSchema, PlanRevisionWorkflowSchema, PlanCorrespondenceRecordSchema, PlanCoordinationSummarySchema, } from './types.js';
 export type { IPlanCheckout, IPlanWorktreeProof, IPlanCompletion, IPlanSnapshotMilestone, IPlanCorrespondence, IPlanDraftMilestone, IPlanProposal, IPlanRevisionWorkflow, IPlanCorrespondenceRecord, } from './types.js';
 export { PlanCheckpointSchema } from './types.js';

package/dist/contracts/plans/index.js

@@ -1,5 +1,5 @@
 // revision, provenance and plan contracts
-export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './types.js';
+export { PlanDigestSchema, PlanRevisionSchema, PlanMetadataSchema, PlanTargetSchema, PlanOperatorActionSchema, PlanCommandSchema, PlanApprovalSchema, PlanExecutionSchema, PlanFinalizationSchema, PlanComparisonSchema, PlanCoordinationSchema, PlanMilestoneSchema, PlanStatusSchema, PlanResultSchema, } from './types.js';
 // revision checkpoints and retained verification
 export { PlanCheckSchema, PlanCheckoutSchema, PlanWorktreeProofSchema, PlanCompletionSchema, PlanSnapshotMilestoneSchema, PlanCorrespondenceSchema, PlanDraftMilestoneSchema, PlanProposalSchema, PlanRevisionWorkflowSchema, PlanCorrespondenceRecordSchema, PlanCoordinationSummarySchema, } from './types.js';
 // saved revision baseline

package/dist/contracts/plans/types.d.ts

@@ -760,8 +760,61 @@ export declare const PlanFinalizationSchema: z.ZodObject<{
     fileHash: z.ZodString;
     createdAt: z.ZodNumber;
 }, z.core.$strict>;
+export declare const PlanComparisonSchema: z.ZodObject<{
+    sourceRevision: z.ZodObject<{
+        planDigest: z.ZodString;
+        breakdownDigest: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    targetDirectory: z.ZodString;
+    targetRevision: z.ZodObject<{
+        planDigest: z.ZodString;
+        breakdownDigest: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    verdict: z.ZodEnum<{
+        compatible: "compatible";
+        contradiction: "contradiction";
+    }>;
+    reason: z.ZodString;
+    reviewer: z.ZodObject<{
+        provider: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+        }>;
+        cliVersion: z.ZodString;
+        model: z.ZodNullable<z.ZodString>;
+        reference: z.ZodString;
+    }, z.core.$strict>;
+    reviewedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type IPlanComparison = z.infer<typeof PlanComparisonSchema>;
 export declare const PlanCoordinationSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
+    comparisons: z.ZodArray<z.ZodObject<{
+        sourceRevision: z.ZodObject<{
+            planDigest: z.ZodString;
+            breakdownDigest: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        targetDirectory: z.ZodString;
+        targetRevision: z.ZodObject<{
+            planDigest: z.ZodString;
+            breakdownDigest: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        verdict: z.ZodEnum<{
+            compatible: "compatible";
+            contradiction: "contradiction";
+        }>;
+        reason: z.ZodString;
+        reviewer: z.ZodObject<{
+            provider: z.ZodEnum<{
+                claude: "claude";
+                codex: "codex";
+            }>;
+            cliVersion: z.ZodString;
+            model: z.ZodNullable<z.ZodString>;
+            reference: z.ZodString;
+        }, z.core.$strict>;
+        reviewedAt: z.ZodNumber;
+    }, z.core.$strict>>;
     finalized: z.ZodNullable<z.ZodObject<{
         action: z.ZodObject<{
             id: z.ZodUUID;
@@ -1299,6 +1352,7 @@ export declare const PlanCoordinationSummarySchema: z.ZodObject<{
             closeActionId: z.ZodUUID;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    comparisonCount: z.ZodNumber;
     completionCount: z.ZodNumber;
     revision: z.ZodNullable<z.ZodObject<{
         createdAt: z.ZodNumber;
@@ -1515,6 +1569,7 @@ export declare const PlanStatusSchema: z.ZodObject<{
                 closeActionId: z.ZodUUID;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
+        comparisonCount: z.ZodNumber;
         completionCount: z.ZodNumber;
         revision: z.ZodNullable<z.ZodObject<{
             createdAt: z.ZodNumber;
@@ -1899,6 +1954,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     closeActionId: z.ZodUUID;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
+            comparisonCount: z.ZodNumber;
             completionCount: z.ZodNumber;
             revision: z.ZodNullable<z.ZodObject<{
                 createdAt: z.ZodNumber;
@@ -2118,6 +2174,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     closeActionId: z.ZodUUID;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
+            comparisonCount: z.ZodNumber;
             completionCount: z.ZodNumber;
             revision: z.ZodNullable<z.ZodObject<{
                 createdAt: z.ZodNumber;
@@ -2461,6 +2518,7 @@ export declare const PlanResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     closeActionId: z.ZodUUID;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
+            comparisonCount: z.ZodNumber;
             completionCount: z.ZodNumber;
             revision: z.ZodNullable<z.ZodObject<{
                 createdAt: z.ZodNumber;

package/dist/contracts/plans/types.js

@@ -270,8 +270,24 @@ export const PlanFinalizationSchema = z.strictObject({
     fileHash: PlanDigestSchema,
     createdAt: z.number().int(),
 });
+// coordinators own semantic review; the core preserves its exact revision-bound evidence
+export const PlanComparisonSchema = z.strictObject({
+    sourceRevision: PlanRevisionSchema,
+    targetDirectory: z.string().min(1).max(4096),
+    targetRevision: PlanRevisionSchema,
+    verdict: z.enum(['compatible', 'contradiction']),
+    reason: z.string().min(1).max(4096),
+    reviewer: z.strictObject({
+        provider: z.enum(['claude', 'codex']),
+        cliVersion: z.string().min(1).max(128),
+        model: z.string().min(1).max(256).nullable(),
+        reference: z.string().min(1).max(4096),
+    }),
+    reviewedAt: z.number().int().nonnegative(),
+});
 export const PlanCoordinationSchema = z.strictObject({
     schemaVersion: z.literal(1),
+    comparisons: z.array(PlanComparisonSchema).max(1024),
     finalized: PlanFinalizationSchema.nullable(),
     planApproval: PlanApprovalSchema.nullable(),
     sequenceApproval: PlanApprovalSchema.nullable(),
@@ -294,11 +310,13 @@ export const PlanCoordinationSchema = z.strictObject({
 });
 // collection bodies remain in the file owner and paged SQLite projections
 export const PlanCoordinationSummarySchema = PlanCoordinationSchema.omit({
+    comparisons: true,
     completions: true,
     correspondences: true,
     revision: true,
     baseline: true,
 }).extend({
+    comparisonCount: z.number().int().nonnegative(),
     completionCount: z.number().int().nonnegative(),
     revision: PlanRevisionWorkflowSchema.omit({
         checkpoint: true,