@nimiplatform/nimi-coding 0.1.0 → 0.2.0

package/cli/lib/internal/contracts-parse.mjs

@@ -27,22 +27,24 @@ export {
   parseHighRiskSchemaContract,
 } from "./contracts-parse-high-risk.mjs";
 
-const SPEC_TREE_PROFILE_ENUM = ["minimal", "standard", "mature"];
+const SPEC_TREE_PROFILE_ENUM = ["minimal", "standard", "mature", "surface_taxonomy_v1"];
 const AUTHORITY_MODE_ENUM = [
   "external_authority_active",
   "external_blueprint_active",
   "canonical_cutover_ready",
   "canonical_active",
+  "surface_class_validated",
 ];
 const BLUEPRINT_MODE_ENUM = [
   "none",
   "repo_spec_blueprint",
   "custom_blueprint",
 ];
-const SPEC_GENERATION_MODE_ENUM = ["mixed"];
+const SPEC_GENERATION_MODE_ENUM = ["mixed", "class_filtered"];
 const SPEC_GENERATION_ACCEPTANCE_MODE_ENUM = [
   "canonical_tree_validity_without_blueprint",
   "semantic_and_structural_parity_when_blueprint_exists",
+  "placement_validity_before_generation",
 ];
 const SPEC_GENERATION_ORDER_ENUM = [
   "index",
@@ -50,6 +52,12 @@ const SPEC_GENERATION_ORDER_ENUM = [
   "kernel_tables",
   "generated_views",
   "thin_guides",
+  "classify_inputs",
+  "validate_placement",
+  "product_authority",
+  "product_authority_tables",
+  "derived_views",
+  "generation_audit",
 ];
 const TOPIC_LIFECYCLE_REPORT_MARKDOWN = /^\.nimi\/topics\/(?:proposal|ongoing|pending|closed)\/\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*\/[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*\.md$/;
 
@@ -61,6 +69,13 @@ function toStringOrNull(value) {
   return typeof value === "string" ? value : null;
 }
 
+function toStringList(value) {
+  if (typeof value === "string") {
+    return [value];
+  }
+  return toStringArray(value);
+}
+
 function normalizePathClass(entry) {
   if (!isPlainObject(entry)) {
     return null;
@@ -100,13 +115,48 @@ function normalizeGeneratedPipeline(entry) {
   return {
     id: toStringOrNull(entry.id),
     ownerSurface: toStringOrNull(entry.owner_surface),
-    inputRoots: toStringArray(entry.input_roots),
+    inputRoots: toStringArray(entry.input_roots).length > 0
+      ? toStringArray(entry.input_roots)
+      : [
+        ...toStringList(entry.input_contract_ref),
+        ...toStringList(entry.input_config_ref),
+      ],
     outputRoots: toStringArray(entry.output_roots),
     generateCommand: toStringOrNull(entry.generate_command),
     driftCheckCommand: toStringOrNull(entry.drift_check_command),
   };
 }
 
+function normalizeV2SpecDomain(entry) {
+  if (!isPlainObject(entry)) {
+    return null;
+  }
+  const root = toStringOrNull(entry.root);
+  return {
+    id: toStringOrNull(entry.id),
+    root,
+    normativeRoot: root ? `${root}/kernel` : null,
+    tablesRoot: root ? `${root}/kernel/tables` : null,
+    generatedRoot: null,
+    guidePaths: [],
+  };
+}
+
+function normalizeV2PathClass(entry) {
+  if (!isPlainObject(entry)) {
+    return null;
+  }
+  return {
+    id: toStringOrNull(entry.id),
+    pathPatterns: toStringArray(entry.path_patterns),
+    excludedPathPatterns: toStringArray(entry.excluded_path_patterns),
+    allowedExtensions: toStringArray(entry.allowed_extensions),
+    generatorRefs: [],
+    mustReferenceNormativeIds: entry.must_reference_product_authority_ids === true,
+    normative: ["product_authority", "product_authority_table"].includes(entry.id),
+  };
+}
+
 function pathStartsWithRoot(targetPath, root) {
   if (typeof targetPath !== "string" || typeof root !== "string") {
     return false;
@@ -140,8 +190,19 @@ function topicLifecycleMarkdownPathsAreSortable(paths) {
   });
 }
 
+function isAllowedV2AuthorityDocsRoot(root) {
+  if (typeof root !== "string" || root.length === 0) {
+    return false;
+  }
+  if (root === "." || root === "./" || root === "/" || root === "**" || root.includes("..")) {
+    return false;
+  }
+  return root === ".nimi/spec" || root.startsWith(".nimi/spec/");
+}
+
 export function parseSpecReconstructionContract(text) {
   const parsed = parseYamlText(text);
+  const version = parsed?.version ?? null;
   const summaryRequiredFields = toStringArray(parsed?.summary_required_fields);
   const summaryStatusEnum = toStringArray(parsed?.summary_status_enum);
   const completionRequirements = toStringArray(parsed?.completion_requirements);
@@ -156,20 +217,35 @@ export function parseSpecReconstructionContract(text) {
     }
     : null;
 
+  const expectedSummaryFields = version === 2
+    ? [...SPEC_RECONSTRUCTION_SUMMARY_REQUIRED_FIELDS.slice(0, 2), "placement_report_ref", ...SPEC_RECONSTRUCTION_SUMMARY_REQUIRED_FIELDS.slice(2)]
+    : SPEC_RECONSTRUCTION_SUMMARY_REQUIRED_FIELDS;
+  const expectedProfileRef = version === 2 ? ".nimi/contracts/surface-taxonomy.schema.yaml" : SPEC_TREE_MODEL_REF;
+  const expectedInputsRef = version === 2 ? ".nimi/config/spec-generation-inputs.yaml" : SPEC_GENERATION_INPUTS_REF;
+  const expectedAuditContractRef = version === 2 ? ".nimi/contracts/spec-generation-audit.schema.yaml" : SPEC_GENERATION_AUDIT_CONTRACT_REF;
+  const expectedAuditRef = version === 2 ? ".nimi/local/state/spec-generation/spec-generation-audit.yaml" : SPEC_GENERATION_AUDIT_REF;
+  const fileClassRequirement = version === 2
+    ? "declared_surface_class_constraints_valid"
+    : "declared_file_class_constraints_valid";
+  const auditRequirement = version === 2
+    ? "spec_generation_audit_present_and_valid_as_local_state"
+    : "spec_generation_audit_present_and_valid";
+
   return {
-    ok: arraysEqual(summaryRequiredFields, SPEC_RECONSTRUCTION_SUMMARY_REQUIRED_FIELDS)
+    ok: [1, 2].includes(version)
+      && arraysEqual(summaryRequiredFields, expectedSummaryFields)
       && arraysEqual(summaryStatusEnum, SPEC_RECONSTRUCTION_SUMMARY_STATUS)
       && completionRequirements.includes("canonical_tree_ready")
       && completionRequirements.includes("declared_profile_required_files_valid")
-      && completionRequirements.includes("declared_file_class_constraints_valid")
-      && completionRequirements.includes("spec_generation_audit_present_and_valid")
+      && completionRequirements.includes(fileClassRequirement)
+      && completionRequirements.includes(auditRequirement)
       && completionRequirements.includes("required_canonical_files_have_matching_audit_entries")
       && completionRequirements.includes("unresolved_gaps_must_remain_explicit")
       && completionRequirements.includes("semantic_and_structural_parity_when_blueprint_exists")
-      && canonicalTreeCompletion?.profileRef === SPEC_TREE_MODEL_REF
-      && canonicalTreeCompletion?.generationInputsRef === SPEC_GENERATION_INPUTS_REF
-      && canonicalTreeCompletion?.auditContractRef === SPEC_GENERATION_AUDIT_CONTRACT_REF
-      && canonicalTreeCompletion?.auditRef === SPEC_GENERATION_AUDIT_REF
+      && canonicalTreeCompletion?.profileRef === expectedProfileRef
+      && canonicalTreeCompletion?.generationInputsRef === expectedInputsRef
+      && canonicalTreeCompletion?.auditContractRef === expectedAuditContractRef
+      && canonicalTreeCompletion?.auditRef === expectedAuditRef
       && canonicalTreeCompletion?.requiredTreeState === "canonical_tree_ready"
       && canonicalTreeCompletion?.requiredFilesValid === true,
     canonicalTreeCompletion,
@@ -181,24 +257,36 @@ export function parseSpecReconstructionContract(text) {
 
 export function parseSpecGenerationAuditContract(text) {
   const parsed = parseYamlText(text);
+  const version = parsed?.version ?? null;
   const requiredTopLevelFields = toStringArray(parsed?.required_top_level_fields);
   const requiredFileEntryFields = toStringArray(parsed?.required_file_entry_fields);
   const sourceBasisEnum = toStringArray(parsed?.source_basis_enum);
   const coverageStatusEnum = toStringArray(parsed?.coverage_status_enum);
   const hardConstraints = toStringArray(parsed?.hard_constraints);
 
+  const expectedTopLevelFields = version === 2
+    ? [...SPEC_GENERATION_AUDIT_REQUIRED_TOP_LEVEL_FIELDS.slice(0, 4), "placement_report_ref", ...SPEC_GENERATION_AUDIT_REQUIRED_TOP_LEVEL_FIELDS.slice(4)]
+    : SPEC_GENERATION_AUDIT_REQUIRED_TOP_LEVEL_FIELDS;
+  const expectedFileEntryFields = version === 2
+    ? ["canonical_path", "surface_class", "source_refs", "source_basis", "coverage_status", "unresolved_items"]
+    : SPEC_GENERATION_AUDIT_FILE_REQUIRED_FIELDS;
+  const expectedTargetRef = version === 2 ? ".nimi/local/state/spec-generation/spec-generation-audit.yaml" : SPEC_GENERATION_AUDIT_REF;
+  const sourceConstraint = version === 2
+    ? "source_refs_must_stay_within_class_filtered_declared_inputs"
+    : "source_refs_must_stay_within_declared_inputs_or_optional_benchmark_root";
+
   return {
-    ok: parsed?.version === 1
+    ok: [1, 2].includes(version)
       && String(parsed?.audit_contract?.id ?? "") === "canonical_spec_generation_audit"
-      && String(parsed?.audit_contract?.target_ref ?? "") === SPEC_GENERATION_AUDIT_REF
-      && arraysEqual(requiredTopLevelFields, SPEC_GENERATION_AUDIT_REQUIRED_TOP_LEVEL_FIELDS)
-      && arraysEqual(requiredFileEntryFields, SPEC_GENERATION_AUDIT_FILE_REQUIRED_FIELDS)
+      && String(parsed?.audit_contract?.target_ref ?? "") === expectedTargetRef
+      && arraysEqual(requiredTopLevelFields, expectedTopLevelFields)
+      && arraysEqual(requiredFileEntryFields, expectedFileEntryFields)
       && arraysEqual(sourceBasisEnum, SPEC_GENERATION_AUDIT_SOURCE_BASIS_ENUM)
       && arraysEqual(coverageStatusEnum, SPEC_GENERATION_AUDIT_COVERAGE_STATUS_ENUM)
       && hardConstraints.includes("every_generated_canonical_file_requires_a_matching_audit_entry")
       && hardConstraints.includes("required_canonical_files_must_not_be_placeholder_not_allowed")
       && hardConstraints.includes("unresolved_or_inferred_content_must_be_explicit")
-      && hardConstraints.includes("source_refs_must_stay_within_declared_inputs_or_optional_benchmark_root")
+      && hardConstraints.includes(sourceConstraint)
       && hardConstraints.includes("no_empty_success_looking_audit_entries"),
     requiredTopLevelFields,
     requiredFileEntryFields,
@@ -215,6 +303,26 @@ export function parseSpecGenerationInputsContract(text) {
   const generationOrderEnum = toStringArray(parsed?.generation_order_enum);
   const hardConstraints = toStringArray(parsed?.hard_constraints);
 
+  if (parsed?.version === 2) {
+    return {
+      ok: String(contract?.id ?? "") === "canonical_spec_generation_inputs"
+        && String(contract?.owner ?? "") === "nimi-coding"
+        && requiredFields.includes("mode")
+        && requiredFields.includes("canonical_target_root")
+        && requiredFields.includes("docs_inputs")
+        && requiredFields.includes("forbidden_source_classes")
+        && arraysEqual(toStringArray(parsed?.mode_enum), ["class_filtered"])
+        && SPEC_GENERATION_ACCEPTANCE_MODE_ENUM.includes(toStringArray(parsed?.acceptance_mode_enum)[0])
+        && generationOrderEnum.includes("classify_inputs")
+        && generationOrderEnum.includes("validate_placement")
+        && hardConstraints.includes("docs_roots_blanket_ingestion_is_forbidden")
+        && hardConstraints.includes("each_input_file_must_have_an_accepted_surface_class_before_render"),
+      requiredFields,
+      generationOrderEnum,
+      hardConstraints,
+    };
+  }
+
   return {
     ok: parsed?.version === 1
       && String(contract?.id ?? "") === "canonical_spec_generation_inputs"
@@ -242,6 +350,12 @@ export function parseSpecGenerationInputsConfig(text) {
   const codeRoots = toStringArray(config?.code_roots);
   const docsRoots = toStringArray(config?.docs_roots);
   const structureRoots = toStringArray(config?.structure_roots);
+  const codeInputs = Array.isArray(config?.code_inputs) ? config.code_inputs : [];
+  const docsInputs = Array.isArray(config?.docs_inputs) ? config.docs_inputs : [];
+  const structureInputs = Array.isArray(config?.structure_inputs) ? config.structure_inputs : [];
+  const topicInputs = Array.isArray(config?.topic_inputs) ? config.topic_inputs : [];
+  const localInputs = Array.isArray(config?.local_inputs) ? config.local_inputs : [];
+  const forbiddenSourceClasses = toStringArray(config?.forbidden_source_classes);
   const humanNotePaths = toStringArray(config?.human_note_paths);
   const benchmarkBlueprintRoot = typeof config?.benchmark_blueprint_root === "string"
     ? config.benchmark_blueprint_root
@@ -251,6 +365,46 @@ export function parseSpecGenerationInputsConfig(text) {
   const generationOrder = toStringArray(config?.generation_order);
   const inferenceRules = toStringArray(config?.inference_rules);
 
+  if (parsed?.version === 2) {
+    const legacyRootsAbsent = !("code_roots" in config)
+      && !("docs_roots" in config)
+      && !("structure_roots" in config);
+    return {
+      ok: String(parsed?.contract_ref ?? "") === ".nimi/contracts/spec-generation-inputs.schema.yaml"
+        && mode === "class_filtered"
+        && canonicalTargetRoot === ".nimi/spec"
+        && legacyRootsAbsent
+        && Array.isArray(codeInputs)
+        && docsInputs.length > 0
+        && docsInputs.every((entry) => isPlainObject(entry)
+          && typeof entry.root === "string"
+          && isAllowedV2AuthorityDocsRoot(entry.root)
+          && Array.isArray(entry.allowed_surface_classes)
+          && Array.isArray(entry.forbidden_surface_classes)
+          && entry.use_as_authority === true)
+        && Array.isArray(structureInputs)
+        && Array.isArray(topicInputs)
+        && Array.isArray(localInputs)
+        && forbiddenSourceClasses.length > 0
+        && generationOrder.includes("classify_inputs")
+        && generationOrder.includes("validate_placement")
+        && inferenceRules.includes("no_blanket_docs_roots")
+        && SPEC_GENERATION_ACCEPTANCE_MODE_ENUM.includes(acceptanceMode)
+        && topicLifecycleMarkdownPathsAreSortable(humanNotePaths),
+      mode,
+      canonicalTargetRoot,
+      codeRoots: codeInputs.map((entry) => String(entry.root ?? "")).filter(Boolean),
+      docsRoots: docsInputs.map((entry) => String(entry.root ?? "")).filter(Boolean),
+      structureRoots: structureInputs.map((entry) => String(entry.root ?? "")).filter(Boolean),
+      humanNotePaths,
+      benchmarkBlueprintRoot,
+      benchmarkMode: benchmarkMode ?? "none",
+      acceptanceMode,
+      generationOrder,
+      inferenceRules,
+    };
+  }
+
   return {
     ok: parsed?.version === 1
       && String(parsed?.contract_ref ?? "") === SPEC_GENERATION_INPUTS_CONTRACT_REF
@@ -289,24 +443,40 @@ export function parseSpecTreeModel(text) {
   const parsed = parseYamlText(text);
   const model = parsed?.spec_tree_model;
   const profile = toStringOrNull(model?.profile);
-  const canonicalRoot = toStringOrNull(model?.canonical_root);
+  const canonicalRoot = toStringOrNull(model?.canonical_root) ?? toStringOrNull(model?.product_authority_root);
   const authorityMode = normalizeAuthorityModeValue(toStringOrNull(model?.authority_mode));
+  const isV2 = parsed?.version === 2;
   const domains = Array.isArray(model?.domains)
-    ? model.domains.map(normalizeSpecDomain).filter(Boolean)
+    ? model.domains.map(isV2 ? normalizeV2SpecDomain : normalizeSpecDomain).filter(Boolean)
     : [];
-  const normativeClasses = Array.isArray(model?.normative_classes)
-    ? model.normative_classes.map(normalizePathClass).filter(Boolean)
+  const normativeClassSource = isV2 ? model?.product_authority_classes : model?.normative_classes;
+  const derivedClassSource = isV2
+    ? (Array.isArray(model?.non_authority_classes) ? model.non_authority_classes.filter((entry) => entry?.id === "derived_view") : [])
+    : model?.derived_classes;
+  const normativeClasses = Array.isArray(normativeClassSource)
+    ? normativeClassSource.map(isV2 ? normalizeV2PathClass : normalizePathClass).filter(Boolean)
     : [];
-  const derivedClasses = Array.isArray(model?.derived_classes)
-    ? model.derived_classes.map(normalizePathClass).filter(Boolean)
+  const derivedClasses = Array.isArray(derivedClassSource)
+    ? derivedClassSource.map(isV2 ? (entry) => ({
+      id: toStringOrNull(entry.id),
+      pathPatterns: toStringArray(entry.allowed_roots),
+      excludedPathPatterns: [],
+      allowedExtensions: [],
+      generatorRefs: [],
+      mustReferenceNormativeIds: false,
+      normative: false,
+    }) : normalizePathClass).filter(Boolean)
     : [];
   const guidanceClasses = Array.isArray(model?.guidance_classes)
-    ? model.guidance_classes.map(normalizePathClass).filter(Boolean)
+    ? model.guidance_classes.map(isV2 ? normalizeV2PathClass : normalizePathClass).filter(Boolean)
     : [];
   const requiredFilesByProfile = SPEC_TREE_PROFILE_ENUM.reduce((acc, currentProfile) => {
     acc[currentProfile] = toStringArray(model?.required_files?.[currentProfile]);
     return acc;
   }, {});
+  if (isV2 && requiredFilesByProfile.surface_taxonomy_v1.length === 0) {
+    requiredFilesByProfile.surface_taxonomy_v1 = requiredFilesByProfile.minimal;
+  }
   const generatedPipelines = Array.isArray(model?.generated_pipelines)
     ? model.generated_pipelines.map(normalizeGeneratedPipeline).filter(Boolean)
     : [];
@@ -333,7 +503,8 @@ export function parseSpecTreeModel(text) {
     && (!domain.generatedRoot || pathStartsWithRoot(domain.generatedRoot, domain.normativeRoot))
     && domain.guidePaths.every((guidePath) => pathStartsWithRoot(guidePath, domain.root))
   ));
-  const requiredFilesValid = SPEC_TREE_PROFILE_ENUM.every((currentProfile) => (
+  const profilesToCheck = isV2 ? [profile] : SPEC_TREE_PROFILE_ENUM.filter((entry) => entry !== "surface_taxonomy_v1");
+  const requiredFilesValid = profilesToCheck.every((currentProfile) => (
     requiredFilesByProfile[currentProfile].length > 0
     && requiredFilesByProfile[currentProfile].every((requiredPath) => pathStartsWithRoot(requiredPath, canonicalRoot))
   ));
@@ -356,7 +527,7 @@ export function parseSpecTreeModel(text) {
   );
 
   return {
-    ok: parsed?.version === 1
+    ok: [1, 2].includes(parsed?.version)
       && profileValid
       && canonicalRootValid
       && authorityModeValid

package/cli/lib/internal/contracts-validators.mjs

@@ -91,10 +91,11 @@ export function validateSpecReconstructionSummary(summary, contract, verifiedAt)
     };
   }
 
-  if (typeof summary.audit_ref !== "string" || summary.audit_ref !== SPEC_GENERATION_AUDIT_REF) {
+  const expectedAuditRef = contract.canonicalTreeCompletion?.auditRef ?? SPEC_GENERATION_AUDIT_REF;
+  if (typeof summary.audit_ref !== "string" || summary.audit_ref !== expectedAuditRef) {
     return {
       ok: false,
-      reason: `spec_reconstruction summary.audit_ref must be \`${SPEC_GENERATION_AUDIT_REF}\``,
+      reason: `spec_reconstruction summary.audit_ref must be \`${expectedAuditRef}\``,
     };
   }
 

package/cli/lib/internal/doctor-bootstrap-surface.mjs

@@ -5,7 +5,6 @@ import {
   COMMAND_GATING_MATRIX_REF,
   LOCAL_GITIGNORE_ENTRIES,
   PACKAGE_NAME,
-  REQUIRED_BOOTSTRAP_FILES,
   REQUIRED_LOCAL_DIRS,
   SPEC_GENERATION_AUDIT_CONTRACT_REF,
   SPEC_GENERATION_AUDIT_REF,
@@ -13,6 +12,7 @@ import {
   SPEC_GENERATION_INPUTS_REF,
   SPEC_TREE_MODEL_REF,
 } from "../../constants.mjs";
+import { getBootstrapSeedEntries } from "../../seeds/bootstrap.mjs";
 import { inspectBootstrapCompatibility } from "../bootstrap.mjs";
 import {
   findCommandGatingRule,
@@ -68,11 +68,22 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
 
   checks.push(buildCheck("nimi_root", true, ".nimi directory exists"));
 
+  const seedEntries = await getBootstrapSeedEntries();
   const missingBootstrapFiles = [];
-  for (const relativePath of REQUIRED_BOOTSTRAP_FILES) {
-    const info = await pathExists(path.join(projectRoot, relativePath));
+  const driftedPackageCanonicalFiles = [];
+  for (const entry of seedEntries) {
+    const absolutePath = path.join(projectRoot, entry.outputRelativePath);
+    const info = await pathExists(absolutePath);
     if (!info || !info.isFile()) {
-      missingBootstrapFiles.push(relativePath);
+      missingBootstrapFiles.push(entry.outputRelativePath);
+      continue;
+    }
+    if (entry.ownership !== "package_canonical") {
+      continue;
+    }
+    const actual = await readTextIfFile(absolutePath);
+    if (actual !== entry.content) {
+      driftedPackageCanonicalFiles.push(entry.outputRelativePath);
     }
   }
   checks.push(
@@ -80,10 +91,18 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
       "bootstrap_seed_files",
       missingBootstrapFiles.length === 0,
       missingBootstrapFiles.length === 0
-        ? `All required bootstrap seed files are present (${REQUIRED_BOOTSTRAP_FILES.length}/${REQUIRED_BOOTSTRAP_FILES.length})`
-        : `Missing required bootstrap seed files: ${missingBootstrapFiles.join(", ")}`,
+        ? `All bootstrap seed files declared by the seed projection policy are present (${seedEntries.length}/${seedEntries.length})`
+        : `Missing bootstrap seed files declared by the seed projection policy: ${missingBootstrapFiles.join(", ")}`,
     ),
   );
+  checks.push({
+    id: "bootstrap_seed_package_canonical_in_sync",
+    ok: true,
+    severity: driftedPackageCanonicalFiles.length === 0 ? "ok" : "warn",
+    detail: driftedPackageCanonicalFiles.length === 0
+      ? "All package_canonical seed files match package source byte-for-byte"
+      : `package_canonical seed files diverge from package source; run \`nimicoding sync --apply\` to refresh, or \`nimicoding sync --check\` for the authoritative gate: ${driftedPackageCanonicalFiles.join(", ")}`,
+  });
 
   const missingLocalDirs = [];
   for (const relativePath of REQUIRED_LOCAL_DIRS) {
@@ -149,15 +168,23 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
           : "bootstrap.yaml declares an unsupported bootstrap contract id or version",
   });
 
+  const specGenerationInputsContract = await loadSpecGenerationInputsContract(projectRoot);
+  const specGenerationAuditContract = await loadSpecGenerationAuditContract(projectRoot);
+  const specGenerationInputs = await loadSpecGenerationInputsConfig(projectRoot);
+  const usesV2SurfaceModel = specGenerationInputs.ok && specGenerationInputs.mode === "class_filtered";
+
   const bootstrapStateText = await readTextIfFile(path.join(projectRoot, ".nimi", "spec", "bootstrap-state.yaml"));
   const bootstrapStateContract = inspectBootstrapStateContract(bootstrapStateText);
   checks.push(
     buildCheck(
       "bootstrap_state_contract",
-      bootstrapStateContract.ok,
-      bootstrapStateContract.ok
+      usesV2SurfaceModel || bootstrapStateContract.ok,
+      usesV2SurfaceModel
+        ? "v2 host-local surface model does not require .nimi/spec/bootstrap-state.yaml"
+        : bootstrapStateContract.ok
         ? `bootstrap-state.yaml matches the ${bootstrapStateContract.treeState} tree-state contract`
         : "bootstrap-state.yaml is missing required lifecycle fields or declares an unsupported lifecycle state",
+      usesV2SurfaceModel ? "info" : undefined,
     ),
   );
 
@@ -166,10 +193,13 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
   checks.push(
     buildCheck(
       "standalone_completion_truth",
-      completionTruth.ok,
-      completionTruth.ok
+      usesV2SurfaceModel || completionTruth.ok,
+      usesV2SurfaceModel
+        ? "v2 host-local surface model does not require .nimi/spec/product-scope.yaml"
+        : completionTruth.ok
         ? `Product scope declares standalone completion profile ${completionTruth.completionProfile}`
         : "product-scope.yaml is missing or drifted from the package-owned standalone completion truth",
+      usesV2SurfaceModel ? "info" : undefined,
     ),
   );
 
@@ -177,14 +207,16 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
   checks.push(
     buildCheck(
       "spec_tree_model_contract",
-      specTreeModel.ok,
-      specTreeModel.ok
+      usesV2SurfaceModel || specTreeModel.ok,
+      usesV2SurfaceModel
+        ? ".nimi/contracts/surface-taxonomy.schema.yaml supplies the v2 spec surface profile"
+        : specTreeModel.ok
         ? `${SPEC_TREE_MODEL_REF} declares canonical root ${specTreeModel.canonicalRoot} with profile ${specTreeModel.profile}`
         : `${SPEC_TREE_MODEL_REF} is missing or malformed`,
+      usesV2SurfaceModel ? "ok" : undefined,
     ),
   );
 
-  const specGenerationInputsContract = await loadSpecGenerationInputsContract(projectRoot);
   checks.push(
     buildCheck(
       "spec_generation_inputs_contract",
@@ -195,7 +227,6 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
     ),
   );
 
-  const specGenerationAuditContract = await loadSpecGenerationAuditContract(projectRoot);
   checks.push(
     buildCheck(
       "spec_generation_audit_contract",
@@ -206,13 +237,12 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
     ),
   );
 
-  const specGenerationInputs = await loadSpecGenerationInputsConfig(projectRoot);
   checks.push(
     buildCheck(
       "spec_generation_inputs_config",
       specGenerationInputs.ok,
       specGenerationInputs.ok
-        ? `${SPEC_GENERATION_INPUTS_REF} declares mixed canonical spec generation inputs`
+        ? `${SPEC_GENERATION_INPUTS_REF} declares ${specGenerationInputs.mode} canonical spec generation inputs`
         : `${SPEC_GENERATION_INPUTS_REF} is missing or malformed`,
     ),
   );
@@ -221,21 +251,29 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
   checks.push(
     buildCheck(
       "command_gating_matrix_contract",
-      commandGatingMatrix.ok,
-      commandGatingMatrix.ok
+      usesV2SurfaceModel || commandGatingMatrix.ok,
+      usesV2SurfaceModel
+        ? "v2 workflow gates are provided by project-local .nimi/contracts and .nimi/methodology"
+        : commandGatingMatrix.ok
         ? `${COMMAND_GATING_MATRIX_REF} declares ${commandGatingMatrix.entries.length} command gating rules`
         : `${COMMAND_GATING_MATRIX_REF} is missing or malformed`,
+      usesV2SurfaceModel ? "ok" : undefined,
     ),
   );
 
   const blueprintReference = await loadBlueprintReference(projectRoot);
-  const blueprintReferenceExpected = bootstrapStateContract.blueprintMode !== "none";
+  const blueprintReferenceExpected = usesV2SurfaceModel
+    ? specGenerationInputs.benchmarkMode !== "none" || typeof specGenerationInputs.benchmarkBlueprintRoot === "string"
+    : bootstrapStateContract.blueprintMode !== "none";
+  const expectedBlueprintCanonicalRoot = usesV2SurfaceModel
+    ? specGenerationInputs.canonicalTargetRoot
+    : specTreeModel.canonicalRoot;
   const blueprintReferenceAligned = !blueprintReferenceExpected
     ? !blueprintReference.present
     : blueprintReference.present
       && blueprintReference.ok
-      && blueprintReference.mode === bootstrapStateContract.blueprintMode
-      && blueprintReference.canonicalTargetRoot === specTreeModel.canonicalRoot;
+      && (usesV2SurfaceModel || blueprintReference.mode === bootstrapStateContract.blueprintMode)
+      && blueprintReference.canonicalTargetRoot === expectedBlueprintCanonicalRoot;
   checks.push(
     buildCheck(
       "blueprint_reference_contract",
@@ -257,7 +295,7 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
     available: benchmarkAvailable,
     ready: benchmarkAvailable && Boolean(
       specGenerationInputs.ok
-      && specTreeModel.ok
+      && (usesV2SurfaceModel || specTreeModel.ok)
       && (
         specGenerationInputs.benchmarkMode === "none"
           ? !blueprintReference.present
@@ -295,32 +333,38 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
       : `Canonical tree required files are still missing: ${canonicalTree.missing.join(", ")}`,
   });
 
-  const specGenerationAuditReport = await validateSpecAudit(
-    path.join(projectRoot, SPEC_GENERATION_AUDIT_REF),
-    { projectRoot },
-  );
-  const specGenerationAudit = specGenerationAuditReport.refusal?.code === "SPEC_AUDIT_MISSING"
-    ? emptySpecGenerationAudit()
-    : {
+  const specGenerationAuditRef = usesV2SurfaceModel
+    ? ".nimi/local/state/spec-generation/spec-generation-audit.yaml"
+    : SPEC_GENERATION_AUDIT_REF;
+  const specGenerationAuditInfo = await pathExists(path.join(projectRoot, specGenerationAuditRef));
+  let specGenerationAudit = emptySpecGenerationAudit();
+  specGenerationAudit.auditPath = specGenerationAuditRef;
+  if (specGenerationAuditInfo?.isFile()) {
+    const specGenerationAuditReport = await validateSpecAudit(
+      path.join(projectRoot, specGenerationAuditRef),
+      { projectRoot },
+    );
+    specGenerationAudit = {
       present: true,
       ok: specGenerationAuditReport.ok,
-      auditPath: SPEC_GENERATION_AUDIT_REF,
+      auditPath: specGenerationAuditRef,
       validator: "validate-spec-audit",
       summary: specGenerationAuditReport.summary ?? null,
       reason: specGenerationAuditReport.ok
         ? "Spec generation audit is present and structurally valid"
         : specGenerationAuditReport.errors.join("; "),
     };
+  }
   const specGenerationAuditCheckSeverity = !specGenerationAudit.present
-    ? canonicalTree.requiredFilesValid ? "error" : "info"
+    ? canonicalTree.requiredFilesValid ? "warn" : "info"
     : specGenerationAudit.ok ? "ok" : canonicalTree.requiredFilesValid ? "error" : "warn";
   checks.push({
     id: "spec_generation_audit",
-    ok: !specGenerationAudit.present ? !canonicalTree.requiredFilesValid : specGenerationAudit.ok,
+    ok: !specGenerationAudit.present ? true : specGenerationAudit.ok,
     severity: specGenerationAuditCheckSeverity,
     detail: !specGenerationAudit.present
       ? canonicalTree.requiredFilesValid
-        ? "Canonical tree is ready but spec generation audit is still missing or invalid"
+        ? "Canonical tree is ready and spec generation audit is missing; run the audit workflow when file-level generation evidence is required"
         : specGenerationAudit.reason
       : specGenerationAudit.ok
         ? specGenerationAudit.reason
@@ -331,10 +375,13 @@ export async function inspectDoctorBootstrapSurface(projectRoot) {
   checks.push(
     buildCheck(
       "high_risk_closeout_gate",
-      Boolean(highRiskCloseoutGate?.completedRequires?.tree_state === "canonical_tree_ready"),
-      highRiskCloseoutGate
+      usesV2SurfaceModel || Boolean(highRiskCloseoutGate?.completedRequires?.tree_state === "canonical_tree_ready"),
+      usesV2SurfaceModel
+        ? "v2 high-risk closeout gates are contract-driven by project-local .nimi/contracts"
+        : highRiskCloseoutGate
         ? "Command gating matrix includes high_risk_execution closeout readiness"
         : "command gating matrix is missing closeout gating for high_risk_execution",
+      usesV2SurfaceModel ? "ok" : undefined,
     ),
   );
 

package/cli/lib/internal/doctor-delegated-surface.mjs

@@ -147,7 +147,7 @@ export async function inspectDoctorDelegatedSurface(projectRoot) {
   const missingHandoffPaths = [];
   for (const relativePath of handoffRequiredContext) {
     const info = await pathExists(path.join(projectRoot, relativePath));
-    if (!info) {
+    if (!info && relativePath !== ".nimi/spec") {
       missingHandoffPaths.push(relativePath);
     }
   }