feat(plugins)!: guard final designs and resolve gaps in place

Check merged unit evidence and dependencies before final design or regeneration.
Keep explicit drafts marked, preserve reviewed answers in their original documents,
and protect reviewed corrections against concurrent changes. Scope build records to
their application and constrain generated design outputs.

BREAKING CHANGE: incomplete designs require explicit draft mode; final generation
requires current merged evidence. Multi-application build records must name their
application. Install the updated Modernize member plugin before recording them.

Author: khuonghung

apps/api/README.md

@@ -39,6 +39,10 @@ Responsibilities beyond the feature modules below:
   items, the traceability matrix, the AS-IS synthesis documents) with the parsers of
   `@kintsugi/agents/reader` (default ref: the stage's latest successful run, else the default
   branch); `GET …/applications/:appId/results/headlines` gives the overview's headline numbers.
+- Delivery → gap answers: `POST …/applications/:appId/understand/gaps/answer` (`documents.resolve`) proposes
+  a correction to the named gap's row in its original specification. It checks the document the user read and the
+  writer checks its old hash again; the correction is always reviewed in a PR. A merged answer with evidence can
+  clear a blocking gap; draft designs remain non-final. See [ADR-0082](../../docs/decisions/0082-design-readiness-drafts-and-in-place-gap-answers.md).
 - Cross-project reads (session only): `GET /api/document-writes`
   (`?status=queued,failed&projectId`); `GET /api/monitoring/overview` (counts, what needs
   attention, recent activity, the worker's pg-boss queue counts — `null` when unreadable) and

apps/api/migrations/041_gap_answers.sql

@@ -0,0 +1,6 @@
+-- A portal answer proposes a correction to the existing specification; a Git review/merge accepts it.
+insert into core.permission (code, group_name, description) values
+  ('documents.resolve', 'Delivery', 'Propose answers and reopen gaps in original specifications')
+on conflict (code) do nothing;
+insert into core.role_permission (role_id, permission_code) values ('admin', 'documents.resolve')
+on conflict do nothing;

apps/api/src/common/audit/audit-trail.ts

@@ -17,6 +17,7 @@ export const AUDIT_ACTIONS = {
   sandboxUpdate: "sandbox.update",
   telemetryExportUpdate: "telemetry-export.update",
   manifestPublish: "manifest.publish",
+  documentCorrection: "document.correction",
   webSearchConfigure: "web-search.configure",
   projectMemoryConfigure: "project-memory.configure",
   projectMemoryReset: "project-memory.reset",

apps/api/src/modules/admin/document-writes/application/document-writes.service.ts

@@ -9,7 +9,7 @@ import { AUDIT_ACTIONS, AuditTrail, auditRecord } from "#common/audit/audit-trai
 import type { Actor } from "#common/auth/decorators.js";
 import { newId } from "#common/domain/ids.js";
 import { ProjectsService } from "#modules/admin/projects/index.js";
-import type { DocumentWriteFilter, DocumentWriteRecord, NewDocumentWrite } from "../domain/document-write.js";
+import type { DocumentWriteFile, DocumentWriteFilter, DocumentWriteRecord, NewDocumentWrite } from "../domain/document-write.js";
 import { DocumentRepoSkeleton, DocumentWriteQueue, DocumentWriteStore } from "../domain/document-write.ports.js";
 
 @Injectable()
@@ -54,6 +54,16 @@ export class DocumentWritesService {
     return write;
   }
 
+  /** A bounded caller supplies corrected documents; the writer proposes them for review and checks their old hashes. */
+  async proposeCorrection(projectId: string, message: string, files: DocumentWriteFile[], actor: Actor): Promise<DocumentWriteRecord> {
+    const project = await this.projects.getProject(projectId);
+    if (project.documentRepository === null) throw new ConflictException(`Project ${projectId} has no document repository`);
+    if (files.length === 0 || files.some((file) => !file.path.endsWith(".md") || !/^[0-9a-f]{64}$/.test(file.expectedHash ?? ""))) throw new ConflictException("A correction needs Markdown documents and their previous hashes");
+    const write = await this.#enqueue({ id: newId(), projectId, documentRepositoryId: project.documentRepository.repositoryId, kind: "state-change", message, files, reviewAll: true, actor: actor.username ?? actor.id });
+    await this.audit.recordChange(auditRecord(actor, AUDIT_ACTIONS.documentCorrection, { projectId, subject: write.id, detail: { paths: files.map((file) => file.path) } }));
+    return write;
+  }
+
   async list(projectId: string, query: PageQuery): Promise<Page<DocumentWriteRecord>> {
     await this.projects.getProject(projectId); // 404 for an unknown project
     const { items, total } = await this.store.listForProject(projectId, query.limit, query.offset);

apps/api/src/modules/admin/document-writes/domain/document-write.ts

@@ -43,6 +43,8 @@ export interface DocumentWriteFile {
   content: string;
   /** Written only when the default branch does not have the file yet. */
   createOnly?: boolean;
+  /** SHA-256 of the document the person edited, checked by the writer before committing. */
+  expectedHash?: string;
 }
 
 /** A write to enqueue: the files plus the provenance that becomes commit trailers. */

apps/api/src/modules/admin/document-writes/infrastructure/pg-boss-document-write.queue.ts

@@ -24,7 +24,7 @@ export class PgBossDocumentWriteQueue extends DocumentWriteQueue implements OnAp
       projectId: write.projectId,
       kind: write.kind,
       message: write.message,
-      files: write.files.map((file) => ({ path: file.path, content: file.content, ...(file.createOnly === true ? { createOnly: true } : {}) })),
+      files: write.files.map((file) => ({ path: file.path, content: file.content, ...(file.createOnly === true ? { createOnly: true } : {}), ...(file.expectedHash === undefined ? {} : { expectedHash: file.expectedHash }) })),
       ...(write.reviewAll === true ? { reviewAll: true } : {}),
       ...(write.actor === undefined ? {} : { actor: write.actor }),
     });

apps/api/src/modules/delivery/build/application/build.service.ts

@@ -101,12 +101,14 @@ export class BuildService {
   }
 
   /** The newest `build.*` record of a member for each unit (the summary of a record is the unit key), the merge request one first. */
-  async memberBuilds(projectId: string, withUser: boolean): Promise<Map<string, MemberBuild>> {
+  async memberBuilds(projectId: string, withUser: boolean, scope: { applicationId: string; allowLegacy: boolean }): Promise<Map<string, MemberBuild>> {
     const page = await this.activity.list({ projectId, pluginName: MEMBER_PLUGIN, limit: RECENT_ACTIVITY, offset: 0 });
     const latest = new Map<string, MemberBuild>();
     const tests = new Map<string, MemberBuild>();
     for (const record of page.items) {
       if (!record.kind.startsWith("build.")) continue;
+      const application = record.detail["application"];
+      if (application === undefined ? !scope.allowLegacy : application !== scope.applicationId) continue;
       const build = memberBuildOf(record, withUser);
       if (record.kind === "build.mr" && build.mr !== undefined && build.commit !== undefined && !latest.has(record.summary)) latest.set(record.summary, build);
       else if (record.kind === "build.test" && !tests.has(record.summary)) tests.set(record.summary, build);
@@ -123,14 +125,17 @@ export class BuildService {
   async overview(projectId: string, applicationId: string, options: { memberUsers: boolean }): Promise<BuildOverviewView> {
     const [design, context] = await Promise.all([this.design.overview(projectId, applicationId, undefined), this.documents.context(projectId)]);
     const commit = design.ref.commit;
-    const [targets, active, member] = await Promise.all([this.targets(projectId, applicationId), this.activeReviews(projectId, applicationId, context), this.memberBuilds(projectId, options.memberUsers)]);
+    const [targets, active, member] = await Promise.all([this.targets(projectId, applicationId), this.activeReviews(projectId, applicationId, context), this.memberBuilds(projectId, options.memberUsers, { applicationId, allowLegacy: context.project.applications.length === 1 })]);
 
     const rows: UnitBuildRow[] = [];
     for (const group of chunk(design.units, READ_AT_ONCE)) {
       rows.push(
         ...(await Promise.all(
           group.map(async (unit): Promise<UnitBuildRow> => {
-            const designed = Object.values(unit.sets).some((set) => set.files.total - set.files.missing > 0);
+            const summaries = Object.values(unit.sets);
+            // A draft or a failed conformance check is not the design a member is authorized to build.
+            const designed = summaries.some((set) => set.files.conformant > 0 && set.files.missing === 0 && set.files.problems === 0 && (set.blockers?.length ?? 0) === 0)
+              && summaries.every((set) => set.files.problems === 0);
             const recorded = member.get(unit.key);
             const busy = active.get(unit.key);
             const published = frontMatter(await this.documents.readText(context, commit, unitCodeReviewPath(applicationId, unit.key)));

apps/api/src/modules/delivery/design/application/design-runs.service.ts

@@ -24,9 +24,11 @@ export interface DesignSelection {
   resumeOf?: string;
   /** Write the set again for units that already have it, over their design (ADR-0081). */
   regenerate?: boolean;
+  /** Explicitly produce a non-final design when the evidence is incomplete. */
+  draft?: boolean;
 }
 
-type Conflict = { unit: string; state: "running" | "in-pr"; runId: string } | { unit: string; state: "written" } | { unit: string; state: "unwritten" } | { unit: string; state: "needs"; needs: string[] };
+type Conflict = { unit: string; state: "not-ready"; reasons: string[] } | { unit: string; state: "running" | "in-pr"; runId: string } | { unit: string; state: "written" } | { unit: string; state: "unwritten" } | { unit: string; state: "needs"; needs: string[] };
 
 const reasonOf = (conflict: Conflict): string => {
   switch (conflict.state) {
@@ -38,6 +40,8 @@ const reasonOf = (conflict: Conflict): string => {
       return "has this set already";
     case "unwritten":
       return "has no design of this set to regenerate";
+    case "not-ready":
+      return conflict.reasons.join("; ");
     case "needs":
       return `needs ${conflict.needs.join(", ")} first`;
   }
@@ -61,7 +65,8 @@ export class DesignRunsService {
     const wanted = [...new Set(selection.units ?? [])].sort();
     if (set === "" || wanted.length === 0) throw new BadRequestException("Name the design set and at least one unit");
 
-    const [sets, overview] = await Promise.all([this.design.sets(projectId, undefined, applicationId), this.design.overview(projectId, applicationId, undefined)]);
+    const overview = await this.design.overview(projectId, applicationId, undefined);
+    const sets = await this.design.sets(projectId, overview.ref.commit, applicationId);
     if (!sets.sets.some((entry) => entry.id === set)) throw new BadRequestException({ message: `The project defines no design set "${set}" (${designSetDir(set)}/)`, details: { set } });
     const faults = sets.problems.filter((problem) => problem.path.startsWith(`${designSetDir(set)}/`));
     if (faults.length > 0) {
@@ -86,16 +91,19 @@ export class DesignRunsService {
     }
 
     const regenerate = selection.regenerate === true;
+    const draft = selection.draft === true;
     const busy = new Map((await this.activity(projectId, applicationId)).items.filter((item) => item.set === set).map((item) => [item.unit, item]));
     const needs = overview.sets.find((entry) => entry.id === set)?.needs ?? [];
     const conflicts = wanted.flatMap((key): Conflict[] => {
       const active = busy.get(key);
       if (active !== undefined) return [{ unit: key, state: active.state, runId: active.runId }];
       const summary = forApplication ? overview.application.sets[set] : byKey.get(key)!.sets[set];
       if (summary === undefined) return [];
+      if (summary.draftAllowed === false) return [{ unit: key, state: "not-ready", reasons: ["The unit is not active in the merged catalog; assess and merge its scope first."] }];
+      if (!draft && (summary.blockers?.length ?? 0) > 0) return [{ unit: key, state: "not-ready", reasons: summary.blockers! }];
       // A regeneration needs a design to replace; a first design needs the sets it builds on and no design yet.
       if (regenerate) return summary.files.conformant + summary.files.problems > 0 ? [] : [{ unit: key, state: "unwritten" }];
-      if (summary.ready) return [];
+      if (summary.ready || (draft && summary.files.conformant + summary.files.problems === 0)) return [];
       return [summary.state === "missing" ? { unit: key, state: "needs", needs } : { unit: key, state: "written" }];
     });
     if (conflicts.length > 0) {
@@ -108,7 +116,7 @@ export class DesignRunsService {
       });
     }
     // Pinned: the default branch tip the overview was read at.
-    return this.runs.startRun(projectId, applicationId, DESIGN, actor, { inputs: { scope: { items: wanted, files: [], set, ...(regenerate ? { regenerate: true } : {}) }, documentsCommit: overview.ref.commit } });
+    return this.runs.startRun(projectId, applicationId, DESIGN, actor, { inputs: { scope: { items: wanted, files: [], set, ...(regenerate ? { regenerate: true } : {}), ...(draft ? { draft: true } : {}) }, documentsCommit: overview.ref.commit } });
   }
 
   /** The units a run is generating or a pull request carries, per design set: what a new selection cannot take. */

apps/api/src/modules/delivery/design/application/design.service.ts

@@ -18,6 +18,8 @@ import {
   type DesignSetSource,
   type ResolvedDesignFile,
   checkDesignDocument,
+  designInputBlockers,
+  type ItemCatalogItem,
   designBaseFiles,
   designCoverage,
   designFilesFor,
@@ -54,10 +56,14 @@ import {
   parseRequirementsMarkdown,
   unitDesignFilePath,
   unitRulesPath,
+  unitAsIsPath,
+  unitUnderstandingPath,
+  unitRulesReviewPath,
   unitStatePath,
 } from "@kintsugi/domain";
 import { parseKintsugiYaml } from "@kintsugi/manifest";
 import { chunk } from "#common/util/async.js";
+import { CatalogService } from "#modules/delivery/catalog/index.js";
 import { type DocumentContext, DocumentsService } from "#modules/delivery/documents/index.js";
 import type {
   CommonComponentView,
@@ -209,7 +215,7 @@ export class DesignService {
   private readonly projectSets = new Map<string, Promise<ProjectSets>>();
   private readonly scans = new Map<string, Promise<AppScan>>();
 
-  constructor(private readonly documents: DocumentsService) {}
+  constructor(private readonly documents: DocumentsService, private readonly catalog: CatalogService) {}
 
   /** The design sets of the project at a ref, with the faults of their definitions; with an application, how its units stand with each. */
   async sets(projectId: string, ref: string | undefined, applicationId: string | undefined): Promise<DesignSetsView> {
@@ -485,12 +491,24 @@ export class DesignService {
           if (keys.length < MAX_UNITS) keys.push({ module, unit });
         }
       }
+      const catalog = await this.catalog.load(context.project.id, applicationId, commit).catch((error: unknown) => {
+        if (error instanceof NotFoundException) return undefined;
+        throw error;
+      });
+      const active = new Map((catalog?.catalog.items ?? []).filter((item) => item.status === "active").map((item) => [item.id, item]));
+      const knownKeys = new Set(keys.map((key) => `${key.module}/${key.unit}`));
+      for (const item of active.values()) {
+        if (!knownKeys.has(item.id) && keys.length < MAX_UNITS) {
+          const [module, unit] = item.id.split("/") as [string, string];
+          keys.push({ module, unit });
+        }
+      }
       const shared: Omit<DesignContext, "items"> = { ruleIds: [], requirementIds, componentIds: components.map((component) => component.id) };
       // The application's own design first: a unit's design may point to the items of the sets of the application it needs.
       const application = await this.scanApplication(context, commit, applicationId, project, shared);
       const units: UnitScan[] = [];
       for (const group of chunk(keys, READS)) {
-        const scanned = await Promise.all(group.map((key) => this.scanUnit(context, commit, applicationId, key.module, key.unit, project, shared, application)));
+        const scanned = await Promise.all(group.map((key) => this.scanUnit(context, commit, applicationId, key.module, key.unit, project, shared, application, active.get(`${key.module}/${key.unit}`))));
         units.push(...scanned.filter((unit): unit is UnitScan => unit !== undefined));
       }
       return { project, application, units, components };
@@ -541,25 +559,31 @@ export class DesignService {
     }
     for (const detail of details) {
       const summary = summaries[detail.set] as UnitSetSummary;
-      const needsMet = detail.needs.every((need) => summaries[need] === undefined || finished((summaries[need] as UnitSetSummary).state));
-      summary.ready = needsMet && summary.state === "missing" && summary.files.conformant + summary.files.problems === 0;
+      summary.blockers = detail.needs.filter((need) => summaries[need] === undefined || !finished(summaries[need]!.state)).map((need) => `Needs the merged, conformant ${need} design first.`);
+      summary.ready = summary.blockers.length === 0 && summary.state === "missing" && summary.files.conformant + summary.files.problems === 0;
     }
     return { summaries, details, unresolved, componentRefs, anyStale, items };
   }
 
   /** One unit: its state file, its rules, its design documents, and what the checks say. Undefined without a unit file. */
-  private async scanUnit(context: DocumentContext, commit: string, app: string, module: string, unit: string, project: ProjectSets, shared: Omit<DesignContext, "items">, application: ApplicationScan): Promise<UnitScan | undefined> {
+  private async scanUnit(context: DocumentContext, commit: string, app: string, module: string, unit: string, project: ProjectSets, shared: Omit<DesignContext, "items">, application: ApplicationScan, catalogItem?: ItemCatalogItem): Promise<UnitScan | undefined> {
     const stateText = await this.documents.readText(context, commit, unitStatePath(app, module, unit), MAX_DESIGN_BYTES);
-    const summary = stateText === undefined ? null : parseWorkItem(stateText);
-    if (stateText === undefined || summary === null || summary.kind === undefined) return undefined;
-    const data = documentOf(stateText).data;
+    const summary = stateText === undefined ? (catalogItem === undefined ? null : { kind: catalogItem.kind, title: catalogItem.name, assignee: undefined }) : parseWorkItem(stateText);
+    if (summary === null || summary.kind === undefined) return undefined;
+    const data = documentOf(stateText ?? "").data;
     const waived = new Map<string, string>();
     for (const entry of Array.isArray(data["waived"]) ? data["waived"] : []) {
       const waiver = typeof entry === "string" ? parseDesignWaiver(entry) : undefined;
       if (waiver !== undefined) waived.set(`${waiver.set}/${waiver.file}`, waiver.reason);
     }
     const rulesText = await this.documents.readText(context, commit, unitRulesPath(app, module, unit), MAX_RULES_BYTES);
     const rules = rulesText === undefined ? [] : ruleCardsOf(rulesText);
+    const [specification, understanding, review] = await Promise.all([
+      this.documents.readText(context, commit, unitAsIsPath(app, module, unit), MAX_DESIGN_BYTES),
+      this.documents.readText(context, commit, unitUnderstandingPath(app, module, unit), MAX_DESIGN_BYTES),
+      this.documents.readText(context, commit, unitRulesReviewPath(app, module, unit), MAX_RULES_BYTES),
+    ]);
+    const evidenceBlockers = designInputBlockers({ specification, understanding, rules: rulesText, review, catalogDigest: catalogItem?.digest });
     const kind = summary.kind;
     const applicable = project.sets.filter((loaded) => designFilesFor(loaded, kind).length > 0);
 
@@ -621,11 +645,15 @@ export class DesignService {
     }
     for (const detail of details) {
       const summary = sets[detail.set] as UnitSetSummary;
-      const needsMet = detail.needs.every((need) => {
+      summary.draftAllowed = catalogItem !== undefined;
+      summary.blockers = [...evidenceBlockers, ...detail.needs.filter((need) => {
         const target = sets[need] ?? application.summaries[need];
-        return target === undefined || finished(target.state);
-      });
-      summary.ready = needsMet && summary.state === "missing" && summary.files.conformant + summary.files.problems === 0;
+        // A unit dependency deliberately inapplicable to this kind has nothing to generate.
+        const definition = project.sets.find((loaded) => loaded.set.id === need);
+        const inapplicable = definition !== undefined && definition.set.scope !== "application" && designFilesFor(definition, kind).length === 0;
+        return !inapplicable && (target === undefined || !finished(target.state));
+      }).map((need) => `Needs the merged, conformant ${need} design first.`)];
+      summary.ready = summary.blockers.length === 0 && summary.state === "missing" && summary.files.conformant + summary.files.problems === 0;
     }
     const coverage: UnitCoverageRow[] = rules
       .map((rule) => ({ rule: rule.id, title: rule.title, coveredBy: coveredBy.get(rule.id) ?? [] }))