@company-semantics/contracts 59.0.0 → 60.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "59.0.0",
+  "version": "60.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'dd2a725d7ebd' as const;
-export const SPEC_HASH_FULL = 'dd2a725d7ebd694db25efbe0e638077984af41551c1989fb374d9a7b8bc4eb3d' as const;
+export const SPEC_HASH = '4ee1bc3befbf' as const;
+export const SPEC_HASH_FULL = '4ee1bc3befbf8bb865b4bdad38b892c59f198fec45acdcdde93a067a678516b3' as const;

package/src/api/generated.ts

@@ -5065,7 +5065,7 @@ export interface components {
             summary: {
                 executionId: string;
                 /** @enum {string} */
-                kind: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "companyMd.commentAction" | "semantic.transform" | "companyMd.importContextDoc";
                 target: {
                     /** @constant */
                     type: "slack";
@@ -5313,6 +5313,7 @@ export interface components {
             canUploadContext?: boolean;
             canManageAcl?: boolean;
             canComment: boolean;
+            canDecideSuggestion: boolean;
             canChangeVisibility?: boolean;
             inheritsFromId: string | null;
             inheritsFrom: string | null;
@@ -6992,6 +6993,7 @@ export interface components {
             createdAt: string;
             updatedAt: string;
             comments: components["schemas"]["Comment"][];
+            capabilities: components["schemas"]["ThreadCapabilities"];
         };
         /** @description Opaque, versioned comment anchor: document-level, a text anchor with a required quote and optional relative positions, or a zero-width text-insertion point for insert suggestions. */
         CommentAnchor: {
@@ -7046,6 +7048,14 @@ export interface components {
             endOffset: number | null;
             displayName: string;
         };
+        /** @description What the requesting actor may do to one thread, decided server-side. */
+        ThreadCapabilities: {
+            canReply: boolean;
+            canResolve: boolean;
+            canReopen: boolean;
+            canDecideSuggestion: boolean;
+            canWithdraw: boolean;
+        };
         /** @description A comment thread without its comments. */
         CommentThreadSummary: {
             id: string;
@@ -9116,7 +9126,7 @@ export interface operations {
             query?: {
                 cursor?: string;
                 limit?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "companyMd.commentAction" | "semantic.transform" | "companyMd.importContextDoc";
                 targetType?: string;
                 periodStart?: string;
                 periodEnd?: string;
@@ -9251,7 +9261,7 @@ export interface operations {
             query?: {
                 limit?: number;
                 offset?: number;
-                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "semantic.transform" | "companyMd.importContextDoc";
+                kind?: "integration.connect" | "integration.disconnect" | "integration.purge" | "profile.update" | "slack.send" | "data.ingest" | "data.scope" | "system.cleanup" | "member.changeManager" | "companyMd.ingest" | "companyMd.commentPass" | "companyMd.commentAction" | "semantic.transform" | "companyMd.importContextDoc";
                 kindPrefix?: string;
             };
             header?: never;

package/src/comments/__tests__/schemas.test.ts

@@ -73,6 +73,17 @@ function makeThread(over: Record<string, unknown> = {}) {
     createdAt: "2026-08-01T12:00:00.000Z",
     updatedAt: "2026-08-01T12:00:00.000Z",
     comments: [makeComment()],
+    // REQUIRED on a thread carried WITH its comments. The summary shape has no
+    // capabilities and no comments — a `CommentThreadSummary` parse of this
+    // fixture simply ignores both, which is why the summary cases below still
+    // pass unchanged.
+    capabilities: {
+      canReply: true,
+      canResolve: true,
+      canReopen: false,
+      canDecideSuggestion: false,
+      canWithdraw: false,
+    },
     ...over,
   };
 }

package/src/comments/schemas.ts

@@ -216,8 +216,58 @@ export type CommentThreadSummary = z.infer<typeof CommentThreadSummarySchema>;
  * order a redacted row used to hold open no longer has anything to hold. The
  * wire SHAPE is unchanged either way; what changed is which rows arrive.
  */
+/**
+ * What the requesting actor may do to ONE thread.
+ *
+ * SERVER-COMPUTED, and that is the point. The app used to reconstruct this
+ * model client-side from doc-level signals plus the viewer's id, which is how
+ * the two surfaces came to disagree — the agent's read reported `canResolve:
+ * false` to actors who had a working Resolve button in the rail. One predicate,
+ * on the server, answering for every surface.
+ *
+ * Each flag ANDs the actor's subject-level band with the thread's own kind and
+ * status, so a flag is `true` only where the verb would actually be admitted.
+ * Two things it deliberately cannot express, both documented rather than
+ * papered over:
+ *   - a LIVE ACCEPTANCE LEASE, which makes both decide verbs 409 while
+ *     `suggestion.status` is still `open`; the claim columns are never
+ *     projected, so `canDecideSuggestion: true` is "band and status permit",
+ *     not "nobody else is mid-accept".
+ *   - anything about OTHER threads; these are per-thread answers.
+ */
+export const ThreadCapabilitiesSchema = z.object({
+  /** Write a reply. Not conditioned on status — a reply reopens a resolved thread. */
+  canReply: z.boolean(),
+  /** Resolve it: an OPEN comment thread only; a suggestion is decided, not resolved. */
+  canResolve: z.boolean(),
+  /** Reopen it: the exact complement of `canResolve`. */
+  canReopen: z.boolean(),
+  /** Accept or reject an OPEN suggestion — the edit band (ADR-BE-536). */
+  canDecideSuggestion: z.boolean(),
+  /**
+   * Withdraw one's OWN open suggestion. IDENTITY, not band: the author needs no
+   * edit capability, so this is true for authors that `canDecideSuggestion`
+   * refuses. Separate for exactly that reason — folded together, the stricter
+   * answer governed and a commenter-band author was told they could not close
+   * their own suggestion.
+   */
+  canWithdraw: z.boolean(),
+});
+export type ThreadCapabilities = z.infer<typeof ThreadCapabilitiesSchema>;
+
 export const CommentThreadSchema = CommentThreadSummarySchema.extend({
   comments: z.array(CommentSchema),
+  /**
+   * REQUIRED. Every route that returns a thread WITH its comments computes it —
+   * the list read and the create; the mutation routes return a
+   * `CommentThreadSummary`, which carries no comments and no capabilities.
+   *
+   * Not optional, deliberately. An optional block means a client keeps a local
+   * derivation for when it is absent, and that second opinion is the precise
+   * thing this field exists to delete: the app and the agent-facing read had
+   * drifted into disagreeing about the same thread.
+   */
+  capabilities: ThreadCapabilitiesSchema,
 });
 export type CommentThread = z.infer<typeof CommentThreadSchema>;
 

package/src/content/schemas.ts

@@ -202,6 +202,29 @@ export const CompanyMdDocResponseSchema = z.object({
    * takes the major bump.
    */
   canComment: z.boolean(),
+  /**
+   * SUGGESTION-DECIDE capability signal: whether the requesting actor holds
+   * `CompanyMd.CanEdit` on this doc as `assertCanDecideSuggestion` evaluates it
+   * — accepting or rejecting someone's suggestion arbitrates what the document
+   * will say, so it rides the edit band (PRD-00934 / ADR-BE-536).
+   *
+   * IT EXISTS BECAUSE `canEdit` IS NOT ONE ANSWER. The app used to derive the
+   * Accept/Reject affordance from `canEdit`, which is the BATCH path
+   * (`canUserEditDocBatch`): it subtracts docs whose projection is stale and
+   * adds owner / account-owner identity safeties. The gate the Accept button
+   * actually hits is `evaluate('CompanyMd.CanEdit')`, which has neither. The two
+   * disagree in both directions — a dead Accept button on a doc whose projection
+   * has not compiled, and a hidden affordance on one whose access shrank but has
+   * not recompiled. Same nominal policy, two implementations; this field is the
+   * one the gate uses, computed the way the gate computes it.
+   *
+   * REQUIRED, like `canComment` above and unlike the three sharing signals: an
+   * absent value would mean "unknown", and a client that invents a default for
+   * an authority question has replaced the server's answer with a guess. The
+   * single-doc read is the only producer of this shape and always computes it.
+   * Signal only; admittance and enforcement are unchanged.
+   */
+  canDecideSuggestion: z.boolean(),
   /**
    * GOVERNANCE capability signal (ADR-BE-435): whether the requesting actor holds
    * `CompanyMd.CanChangeVisibility` (owner OR the `org.manage_content_sharing`

package/src/execution/__tests__/registry.test.ts

@@ -243,6 +243,27 @@ describe("EXECUTION_KINDS golden snapshot", () => {
           templateId: "companyMd.commentPass",
         },
       },
+      "companyMd.commentAction": {
+        kind: "companyMd.commentAction",
+        domain: "data",
+        display: {
+          label: "Apply Comment Action",
+          pastTenseLabel: "Comment action applied",
+          icon: "pencil",
+        },
+        governance: {
+          visibility: "user",
+          requiresAdmin: false,
+        },
+        ui: {
+          showInAdmin: false,
+          showInTimeline: true,
+          confirmBeforeRun: true,
+        },
+        explanation: {
+          templateId: "companyMd.commentAction",
+        },
+      },
       "semantic.transform": {
         kind: "semantic.transform",
         domain: "organization",
@@ -300,12 +321,14 @@ describe("ExecutionKind exhaustiveness", () => {
   });
 
   it("every kind the backend dispatches is a union member, not a call-site cast", () => {
-    // These three previously ran while cast to ExecutionKind at their call
-    // sites, which left the registry incomplete over what actually executes.
+    // These previously ran — or, for the comment ACTION, previewed a confirmable
+    // intent that then routed nowhere — while cast to ExecutionKind at their
+    // call sites, which left the registry incomplete over what actually executes.
     for (const kind of [
       "companyMd.commentPass",
       "semantic.transform",
       "companyMd.importContextDoc",
+      "companyMd.commentAction",
     ]) {
       expect(isValidExecutionKind(kind)).toBe(true);
       expect(CONFIRMATION_LABELS[kind as ExecutionKind]).toBeTruthy();

package/src/execution/kinds.ts

@@ -55,4 +55,12 @@ export type ExecutionKind =
   | "semantic.transform"
   /** Already RUNS today, previously cast at the call site. Creates a context
    *  doc from submitted text and links it under a destination doc. */
-  | "companyMd.importContextDoc";
+  | "companyMd.importContextDoc"
+  /** ONE collaboration write on a company.md thread — resolve, reopen, reply,
+   *  or decide a suggestion. Distinct from `companyMd.commentPass`: the pass is
+   *  a reviewed BUNDLE gated on the whole rail's staleness token, which is the
+   *  wrong gate for a single act — an unrelated new comment elsewhere on the
+   *  document would refuse it. Promoted out of a call-site cast for the same
+   *  reason `semantic.transform` was: a kind that runs but is absent from the
+   *  registry is invisible to every reader of it. */
+  | "companyMd.commentAction";

package/src/execution/registry.ts

@@ -271,6 +271,29 @@ export const EXECUTION_KINDS = {
       templateId: "companyMd.commentPass",
     },
   },
+  "companyMd.commentAction": {
+    kind: "companyMd.commentAction",
+    domain: "data",
+    display: {
+      label: "Apply Comment Action",
+      pastTenseLabel: "Comment action applied",
+      icon: "pencil",
+    },
+    governance: {
+      visibility: "user",
+      requiresAdmin: false,
+    },
+    ui: {
+      showInAdmin: false,
+      showInTimeline: true,
+      // A single collaboration write still changes what the conversation says,
+      // and resolving or deciding is not silently reversible for other readers.
+      confirmBeforeRun: true,
+    },
+    explanation: {
+      templateId: "companyMd.commentAction",
+    },
+  },
   "semantic.transform": {
     kind: "semantic.transform",
     domain: "organization",

package/src/guards/evolution-config.ts

@@ -98,8 +98,16 @@ export interface FileClusterBaseline {
   stripSuffixes?: string[];
   /** Role words to strip (e.g., 'Service', 'Handler') */
   stripRoleWords?: string[];
-  /** Directories to ignore */
+  /**
+   * Directories to ignore, **in addition to** the guard's always-ignored set
+   * (`node_modules`, `dist`, `.git`, `coverage`). This list extends the
+   * defaults; it cannot remove one (ADR-CI-215).
+   */
   ignoredDirectories?: string[];
+  /** Extensions the directory walk collects (default: `['.ts', '.tsx']`) */
+  extensions?: string[];
+  /** When true, violations are errors and annotations require a `reason:` suffix */
+  strict?: boolean;
 }
 
 /**
@@ -116,6 +124,24 @@ export interface SubdirectoryAffinityBaseline {
   excludePatterns?: RegExp[];
   /** Importer patterns to ignore */
   ignoredImporterPatterns?: RegExp[];
-  /** Directories to ignore */
+  /**
+   * Directories to ignore, **in addition to** the guard's always-ignored set
+   * (`node_modules`, `dist`, `.git`, `coverage`). This list extends the
+   * defaults; it cannot remove one (ADR-CI-215).
+   */
   ignoredDirectories?: string[];
+  /**
+   * Extensions the directory walk collects (default: `['.ts', '.tsx']`).
+   * Import RESOLUTION is governed by the guard's own module-graph extension
+   * list, not by this one.
+   */
+  extensions?: string[];
+  /**
+   * Import alias prefix to repo-relative root, e.g. `{ '@/': 'src/' }`.
+   * Omit it and only relative specifiers resolve, which is what the guard did
+   * before ADR-CI-214. The trailing slash on both halves is load-bearing.
+   */
+  aliases?: Record<string, string>;
+  /** When true, violations are errors and annotations require a `reason:` suffix */
+  strict?: boolean;
 }

package/src/message-parts/__tests__/confirmation.test.ts

@@ -123,6 +123,7 @@ describe("CONFIRMATION_LABELS", () => {
       "member.changeManager": "Change Reporting Manager",
       "companyMd.ingest": "Ingest Company Knowledge",
       "companyMd.commentPass": "Apply Comment Pass",
+      "companyMd.commentAction": "Apply Comment Action",
       "semantic.transform": "Apply Reporting Transformation",
       "companyMd.importContextDoc": "Import Context Document",
     });

package/src/message-parts/confirmation.ts

@@ -48,6 +48,7 @@ export const CONFIRMATION_LABELS: Record<ExecutionKind, string> = {
   "member.changeManager": "Change Reporting Manager",
   "companyMd.ingest": "Ingest Company Knowledge",
   "companyMd.commentPass": "Apply Comment Pass",
+  "companyMd.commentAction": "Apply Comment Action",
   "semantic.transform": "Apply Reporting Transformation",
   "companyMd.importContextDoc": "Import Context Document",
 };