@nimiplatform/nimi-coding 0.1.0

package/cli/lib/yaml-helpers.mjs

@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+
+import YAML from "yaml";
+
+import { pathExists } from "./fs-helpers.mjs";
+import { isPlainObject, toStringArray } from "./value-helpers.mjs";
+
+function findFirstMatchingKey(node, targetKey) {
+  if (Array.isArray(node)) {
+    for (const entry of node) {
+      const found = findFirstMatchingKey(entry, targetKey);
+      if (found !== undefined) {
+        return found;
+      }
+    }
+    return undefined;
+  }
+
+  if (!isPlainObject(node)) {
+    return undefined;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(node, targetKey)) {
+    return node[targetKey];
+  }
+
+  for (const value of Object.values(node)) {
+    const found = findFirstMatchingKey(value, targetKey);
+    if (found !== undefined) {
+      return found;
+    }
+  }
+
+  return undefined;
+}
+
+export function parseYamlText(text) {
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return YAML.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export async function loadYamlFile(filePath) {
+  const info = await pathExists(filePath);
+  if (!info || !info.isFile()) {
+    return null;
+  }
+
+  try {
+    return YAML.parse(await readFile(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function readYamlScalar(text, key) {
+  const parsed = parseYamlText(text);
+  const value = findFirstMatchingKey(parsed, key);
+
+  if (value === undefined || value === null || isPlainObject(value) || Array.isArray(value)) {
+    return null;
+  }
+
+  return String(value);
+}
+
+export function readYamlList(text, key) {
+  const parsed = parseYamlText(text);
+  const value = findFirstMatchingKey(parsed, key);
+  return toStringArray(value);
+}
+
+export function mergeOrderedPaths(...groups) {
+  const merged = [];
+
+  for (const group of groups) {
+    for (const entry of group) {
+      if (entry && !merged.includes(entry)) {
+        merged.push(entry);
+      }
+    }
+  }
+
+  return merged;
+}
+
+export function parseSkillSection(text, sectionKey) {
+  const parsed = parseYamlText(text);
+  const section = parsed?.[sectionKey];
+
+  if (!Array.isArray(section)) {
+    return [];
+  }
+
+  return section.map((entry) => ({
+    ...entry,
+    id: typeof entry?.id === "string" ? entry.id : null,
+    inputs: Array.isArray(entry?.inputs) ? entry.inputs.map((item) => String(item)) : [],
+    required: entry?.required === undefined ? undefined : String(entry.required),
+    source: entry?.source === undefined ? undefined : String(entry.source),
+    purpose: entry?.purpose === undefined ? undefined : String(entry.purpose),
+    result_contract_ref: entry?.result_contract_ref === undefined ? undefined : String(entry.result_contract_ref),
+  })).filter((entry) => entry.id);
+}
+
+export function parsePathRequirements(text, sectionKey) {
+  const parsed = parseYamlText(text);
+  const section = parsed?.[sectionKey];
+
+  if (!Array.isArray(section)) {
+    return [];
+  }
+
+  return section
+    .filter((entry) => isPlainObject(entry) && typeof entry.path === "string")
+    .map((entry) => ({
+      path: entry.path,
+      required_top_level_keys: Array.isArray(entry.required_top_level_keys)
+        ? entry.required_top_level_keys.map((item) => String(item))
+        : [],
+    }));
+}
+
+export function readTopLevelKeys(text) {
+  const parsed = parseYamlText(text);
+  return isPlainObject(parsed) ? Object.keys(parsed) : [];
+}

package/cli/nimicoding.mjs

@@ -0,0 +1 @@
+export { runCli } from "./index.mjs";

package/cli/seeds/bootstrap.mjs

@@ -0,0 +1,47 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+const HOST_BOOTSTRAP_EXCLUDED_PATHS = new Set([
+  "methodology/spec-target-truth-profile.yaml",
+]);
+const SOURCE_PROJECTIONS = [
+  { sourceDir: "config", outputDir: ".nimi/config" },
+  { sourceDir: "contracts", outputDir: ".nimi/contracts" },
+  { sourceDir: "methodology", outputDir: ".nimi/methodology" },
+  { sourceDir: "spec", outputDir: ".nimi/spec" },
+];
+
+function toPortableRelativePath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+async function collectProjectedFiles(rootPath, currentPath, outputDir, seedMap) {
+  const entries = await readdir(currentPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const absolutePath = path.join(currentPath, entry.name);
+    if (entry.isDirectory()) {
+      await collectProjectedFiles(rootPath, absolutePath, outputDir, seedMap);
+      continue;
+    }
+
+    const relativePath = toPortableRelativePath(path.relative(rootPath, absolutePath));
+    if (HOST_BOOTSTRAP_EXCLUDED_PATHS.has(`${path.basename(rootPath)}/${relativePath}`)) {
+      continue;
+    }
+    seedMap.set(`${outputDir}/${relativePath}`, await readFile(absolutePath, "utf8"));
+  }
+}
+
+export async function createBootstrapSeedFileMap() {
+  const seedMap = new Map();
+
+  for (const projection of SOURCE_PROJECTIONS) {
+    const sourceRoot = path.join(PACKAGE_ROOT, projection.sourceDir);
+    await collectProjectedFiles(sourceRoot, sourceRoot, projection.outputDir, seedMap);
+  }
+
+  return seedMap;
+}

package/config/audit-execution-artifacts.yaml

@@ -0,0 +1,20 @@
+version: 1
+audit_execution_artifacts:
+  skill_id: audit_sweep
+  host_adapter_ref: .nimi/config/host-adapter.yaml
+  result_contract_ref: .nimi/contracts/audit-sweep-result.yaml
+  locality: local_only
+  artifact_roots:
+    plan_ref: .nimi/local/audit/plans
+    chunk_refs: .nimi/local/audit/chunks
+    ledger_ref: .nimi/local/audit/ledgers
+    report_ref: .nimi/local/audit/reports
+    remediation_map_ref: .nimi/local/audit/remediation-maps
+    audit_closeout_ref: .nimi/local/audit/closeouts
+    packet_ref: .nimi/local/audit/packets
+    evidence_refs: .nimi/local/audit/evidence
+    run_ledger_ref: .nimi/local/audit/runs
+  hard_constraints:
+    - audit_execution_artifacts_remain_operational_only
+    - imported_refs_must_stay_under_declared_local_roots
+    - candidate_artifacts_must_not_override_semantic_truth

package/config/bootstrap.yaml

@@ -0,0 +1,6 @@
+version: 1
+initialized_by: "@nimiplatform/nimi-coding"
+cli_version: "0.1.0"
+bootstrap_contract: "nimicoding.bootstrap"
+bootstrap_contract_version: 1
+profile: default

package/config/external-execution-artifacts.yaml

@@ -0,0 +1,16 @@
+version: 1
+external_execution_artifacts:
+  skill_id: high_risk_execution
+  host_adapter_ref: .nimi/config/host-adapter.yaml
+  result_contract_ref: .nimi/contracts/high-risk-execution-result.yaml
+  locality: local_only
+  artifact_roots:
+    packet_ref: .nimi/local/packets
+    orchestration_state_ref: .nimi/local/orchestration
+    prompt_ref: .nimi/local/prompts
+    worker_output_ref: .nimi/local/outputs
+    evidence_refs: .nimi/local/evidence
+  hard_constraints:
+    - external_execution_artifacts_remain_operational_only
+    - imported_refs_must_stay_under_declared_local_roots
+    - candidate_artifacts_must_not_override_semantic_truth

package/config/host-adapter.yaml

@@ -0,0 +1,30 @@
+version: 1
+host_adapter:
+  runtime_owner: external_ai_host
+  selected_adapter_id: none
+  admitted_adapter_ids:
+    - codex
+    - oh_my_codex
+    - claude
+  handoff_mode: prompt_output_evidence_handoff
+  evidence_mode: candidate_only
+  semantic_review_owner: nimicoding_manager
+  admitted_execution_surfaces:
+    - authority_convergence_audit
+  host_profile_ref: .nimi/config/host-profile.yaml
+  manifest_ref: .nimi/config/skill-manifest.yaml
+  artifact_contract_ref: .nimi/config/external-execution-artifacts.yaml
+  handoff_ref: .nimi/methodology/skill-handoff.yaml
+  operational_state_roots:
+    - .nimi/local
+    - .nimi/cache
+  semantic_owner_roots:
+    - .nimi/methodology
+    - .nimi/spec
+    - .nimi/contracts
+    - .nimi/config
+  hard_constraints:
+    - adapter_must_not_override_semantic_truth
+    - adapter_must_not_define_acceptance_or_disposition
+    - adapter_runtime_state_must_remain_operational_only
+    - authority_convergence_subagent_execution_is_adapter_projection_only

package/config/host-profile.yaml

@@ -0,0 +1,29 @@
+version: 1
+host_profile:
+  id: external_ai_host
+  host_class: ai_native_coding_host
+  runtime_contract_ref: .nimi/methodology/skill-runtime.yaml
+  compatibility_contract_ref: .nimi/contracts/external-host-compatibility.yaml
+  installer_ref: .nimi/config/skill-installer.yaml
+  installer_result_contract_ref: .nimi/methodology/skill-installer-result.yaml
+  ownership_mode: external
+  execution_mode: delegated
+  install_state: not_installed
+  self_hosted: false
+  required_context:
+    - .nimi/methodology
+    - .nimi/spec
+    - .nimi/contracts
+    - .nimi/config/skill-manifest.yaml
+    - .nimi/config/host-profile.yaml
+    - .nimi/config/host-adapter.yaml
+    - .nimi/config/external-execution-artifacts.yaml
+    - .nimi/methodology/skill-handoff.yaml
+  required_capabilities:
+    - read_project_local_nimi_truth
+    - route_declared_external_skills
+    - fail_closed_on_missing_authority
+  hard_constraints:
+    - vendor_neutral_profile_only
+    - do_not_assume_local_runtime_install
+    - do_not_claim_packet_orchestration_ownership

package/config/installer-evidence.yaml

@@ -0,0 +1,31 @@
+version: 1
+evidence_home:
+  id: local_skill_installer_operational_evidence
+  locality: local_only
+  root: .nimi/local/installer-evidence
+  runs_dir: .nimi/local/installer-evidence/runs
+  latest_summary_path: .nimi/local/installer-evidence/latest-summary.json
+  payload_cache_dir: .nimi/local/installer-evidence/payloads
+  temp_dir: .nimi/local/installer-evidence/temp
+  retention:
+    summaries: retain_verified_history
+    raw_logs: local_prunable
+    payloads: ephemeral_best_effort
+    temp_paths: delete_after_run
+  semantic_projection:
+    mode: verified_summary_only
+    contract_ref: .nimi/methodology/skill-installer-summary-projection.yaml
+    target_result_contract: .nimi/methodology/skill-installer-result.yaml
+    lifecycle_scope:
+      owner: external_ai_host
+      stage_model: collapsed_single_contract
+      semantic_stages:
+        - capture
+        - production
+        - status_declaration
+        - semantic_projection
+        - final_result_declaration
+  hard_constraints:
+    - do_not_promote_concrete_evidence_artifacts
+    - do_not_require_tracked_evidence_files
+    - missing_local_evidence_must_not_imply_success

package/config/skill-installer.yaml

@@ -0,0 +1,23 @@
+version: 1
+installer:
+  id: external_delegated_skill_installer
+  installer_owner: external_ai_host
+  installer_mode: delegated
+  install_state: not_installed
+  executable_installation: false
+  self_hosted: false
+  manifest_ref: .nimi/config/skill-manifest.yaml
+  runtime_contract_ref: .nimi/methodology/skill-runtime.yaml
+  host_profile_ref: .nimi/config/host-profile.yaml
+  result_contract_ref: .nimi/methodology/skill-installer-result.yaml
+  evidence_home_ref: .nimi/config/installer-evidence.yaml
+  install_flow:
+    - read_declared_skill_manifest
+    - resolve_against_declared_runtime_contract
+    - resolve_against_declared_host_profile
+    - require_explicit_external_install_action
+  hard_constraints:
+    - do_not_assume_local_installer_runtime
+    - do_not_assume_vendor_specific_package_manager
+    - do_not_claim_self_hosted_installation
+    - unresolved_install_requirement_must_fail_closed

package/config/skill-manifest.yaml

@@ -0,0 +1,46 @@
+version: 1
+manifest:
+  runtime_owner: external_ai_host
+  runtime_contract_ref: .nimi/methodology/skill-runtime.yaml
+  host_profile_ref: .nimi/config/host-profile.yaml
+  installer_ref: .nimi/config/skill-installer.yaml
+  installer_result_contract_ref: .nimi/methodology/skill-installer-result.yaml
+  execution_mode: delegated
+  install_state: not_installed
+skills:
+  - id: spec_reconstruction
+    source: external
+    required: true
+    result_contract_ref: .nimi/contracts/spec-reconstruction-result.yaml
+    inputs:
+      - .nimi/config/spec-generation-inputs.yaml
+      - .nimi/methodology/spec-reconstruction.yaml
+      - .nimi/spec/_meta/spec-tree-model.yaml
+      - .nimi/spec/bootstrap-state.yaml
+  - id: doc_spec_audit
+    source: external
+    required: true
+    result_contract_ref: .nimi/contracts/doc-spec-audit-result.yaml
+    inputs:
+      - README.md
+      - .nimi/spec
+  - id: audit_sweep
+    source: external
+    required: false
+    result_contract_ref: .nimi/contracts/audit-sweep-result.yaml
+    inputs:
+      - .nimi/methodology
+      - .nimi/spec
+      - .nimi/contracts
+      - .nimi/local
+      - .nimi/config/audit-execution-artifacts.yaml
+  - id: high_risk_execution
+    source: external
+    required: false
+    result_contract_ref: .nimi/contracts/high-risk-execution-result.yaml
+    inputs:
+      - .nimi/methodology
+      - .nimi/spec
+      - .nimi/contracts
+      - .nimi/local
+      - .nimi/config/external-execution-artifacts.yaml

package/config/skills.yaml

@@ -0,0 +1,30 @@
+version: 1
+bootstrap:
+  runtime_installed: false
+  installation_mode: deferred
+canonical_reconstruction_guidance: .nimi/methodology/spec-reconstruction.yaml
+canonical_contracts_root: .nimi/contracts
+canonical_manifest: .nimi/config/skill-manifest.yaml
+canonical_host_profile: .nimi/config/host-profile.yaml
+canonical_host_adapter: .nimi/config/host-adapter.yaml
+canonical_external_execution_artifacts: .nimi/config/external-execution-artifacts.yaml
+canonical_runtime_contract: .nimi/methodology/skill-runtime.yaml
+canonical_installer: .nimi/config/skill-installer.yaml
+canonical_installer_result_contract: .nimi/methodology/skill-installer-result.yaml
+canonical_installer_operational_evidence: .nimi/config/installer-evidence.yaml
+canonical_installer_summary_projection_contract: .nimi/methodology/skill-installer-summary-projection.yaml
+handoff_contract: .nimi/methodology/skill-handoff.yaml
+runtime_owner: external_ai_host
+expected_skill_surfaces:
+  - id: spec_reconstruction
+    required: true
+    purpose: reconstruct_project_canonical_tree_into_.nimi/spec
+  - id: doc_spec_audit
+    required: true
+    purpose: compare_human_docs_against_.nimi/spec
+  - id: audit_sweep
+    required: false
+    purpose: perform_full_coverage_audit_sweep_and_emit_frozen_findings_ledger
+  - id: high_risk_execution
+    required: false
+    purpose: packetized_execution_after_project_truth_matures

package/config/spec-generation-inputs.yaml

@@ -0,0 +1,25 @@
+version: 1
+contract_ref: .nimi/contracts/spec-generation-inputs.schema.yaml
+spec_generation_inputs:
+  mode: mixed
+  canonical_target_root: .nimi/spec
+  code_roots: []
+  docs_roots:
+    - README.md
+  structure_roots:
+    - .
+  human_note_paths: []
+  benchmark_blueprint_root: null
+  benchmark_mode: none
+  acceptance_mode: canonical_tree_validity_without_blueprint
+  generation_order:
+    - index
+    - kernel_markdown
+    - kernel_tables
+    - generated_views
+    - thin_guides
+  inference_rules:
+    - infer_domains_from_available_source_materials_when_no_blueprint_exists
+    - separate_normative_kernel_from_generated_and_guidance_surfaces
+    - establish_kernel_markdown_before_thin_guides
+    - establish_kernel_tables_before_generated_views

package/contracts/acceptance.schema.yaml

@@ -0,0 +1,16 @@
+id: nimi-coding.acceptance.v1
+kind: acceptance
+required_order:
+  - authority alignment
+  - phase closure
+  - evidence sufficiency
+  - disposition
+  - next step or reopen
+disposition_enum:
+  - complete
+  - partial
+  - deferred
+required_blocks:
+  - Findings
+  - Current Phase Disposition
+  - Next Step or Reopen Condition

package/contracts/admission-checklist.schema.yaml

@@ -0,0 +1,15 @@
+id: nimicoding.admission-checklist.v1
+kind: admission-checklist
+required:
+  - checklist_id
+  - topic_id
+  - scope
+  - gate_items
+  - stop_phrases
+scope_enum:
+  - topic_entry
+  - wave_preflight
+  - implementation_admission
+rules:
+  - every gate item must be answerable as pass or fail
+  - stop phrases must remain explicit manager stop signals rather than hints

package/contracts/audit-chunk.schema.yaml

@@ -0,0 +1,110 @@
+version: 1
+schema:
+  id: nimi-coding.audit-chunk.v1
+  kind: audit-chunk
+required_top_level_fields:
+  - version
+  - kind
+  - sweep_id
+  - chunk_id
+  - state
+  - owner_domain
+  - criteria
+  - files
+  - file_hashes
+  - lifecycle
+  - created_at
+  - updated_at
+optional_top_level_fields:
+  - planning_basis
+  - spec_surface
+  - authority_refs
+  - authority_kind
+  - app_id
+  - package_authority_id
+  - admission_ref
+  - authority_root
+  - evidence_root_admission_refs
+  - admitted_evidence_roots
+  - host_authority_projection_refs
+  - evidence_roots
+  - evidence_inventory
+  - evidence_inventory_status
+  - evidence_inventory_empty_reason
+  - coverage_contract
+  - evidence_file_hashes
+  - calibration_expected_defects
+  - coverage_quality
+  - audit_validity
+state_enum:
+  - planned
+  - dispatched
+  - ingested
+  - reviewed
+  - frozen
+  - failed
+  - skipped
+lifecycle_required_fields:
+  - planned_at
+  - dispatched_at
+  - ingested_at
+  - reviewed_at
+  - frozen_at
+  - failed_at
+  - skipped_at
+hard_constraints:
+  - chunk_files_must_match_plan_inventory
+  - spec_authority_chunks_must_declare_authority_refs_and_evidence_roots
+  - spec_authority_chunks_must_declare_evidence_inventory
+  - spec_authority_chunks_with_empty_evidence_inventory_must_declare_explicit_empty_reason
+  - spec_authority_chunks_must_declare_coverage_contract
+  - spec_authority_chunk_files_remain_authority_refs_only
+  - admitted_package_authority_projection_refs_must_be_explicitly_mapped
+  - spec_authority_ingest_requires_one_authority_outcome_per_authority_ref
+  - spec_authority_ingest_requires_evidence_files_exactly_matching_evidence_inventory
+  - spec_authority_authority_outcome_evidence_refs_must_belong_to_authority_refs_or_evidence_inventory
+  - no_finding_audited_outcomes_must_declare_negative_reasoning
+  - no_finding_audited_outcomes_with_non_empty_evidence_inventory_must_declare_implementation_evidence_refs_or_not_applicable_reason
+  - p0p1_recall_chunks_without_critical_or_high_findings_must_declare_negative_reasoning_and_implementation_refs
+  - p0p1_recall_chunks_with_implementation_inventory_must_record_rule_specific_checks
+  - p0p1_no_finding_evidence_with_implementation_inventory_must_cite_semantic_auditor_provenance
+  - synthetic_no_finding_generators_must_not_emit_semantic_audit_evidence
+  - calibration_expected_defects_must_be_satisfied_by_finding_evidence_when_present
+  - ingest_requires_dispatch
+  - frozen_requires_manager_review
+  - failed_or_skipped_requires_explicit_reason
+audit_evidence_coverage_fields:
+  - evidence_files
+  - authority_outcomes
+  - no_finding_summary
+  - p0p1_negative_reasoning
+  - p0p1_evidence_refs
+  - p0p1_rule_checks
+  - p0p1_implementation_not_applicable_reason
+auditor_provenance_fields:
+  required_when_p0p1_no_finding_with_implementation_inventory:
+    - kind
+    - packet_ref
+    - session_ref_or_transcript_ref_or_review_ref
+authority_outcome_fields:
+  required:
+    - authority_ref
+    - status
+    - evidence_refs
+  optional:
+    - reason
+    - negative_reasoning
+    - implementation_evidence_refs
+    - implementation_not_applicable_reason
+authority_outcome_status_enum:
+  - audited
+  - blocked
+  - not_applicable
+calibration_expected_defect_fields:
+  required:
+    - id
+  optional:
+    - root_cause_key
+    - location_file
+    - severity
+    - category

package/contracts/audit-closeout.schema.yaml

@@ -0,0 +1,51 @@
+version: 1
+schema:
+  id: nimi-coding.audit-closeout.v1
+  kind: audit-closeout
+required_top_level_fields:
+  - sweep_id
+  - ledger_ref
+  - remediation_map_ref
+  - audit_closeout_ref
+  - coverage_status
+  - coverage_scope
+  - coverage_quality
+  - audit_validity
+  - finding_posture
+  - closeout_posture
+  - verified_at
+coverage_status_enum:
+  - full
+  - partial
+  - blocked
+closeout_posture_enum:
+  - audit_complete_findings_open
+  - audit_complete_all_findings_postured
+  - partial_coverage_all_findings_postured
+  - partial_coverage_findings_open
+  - audit_invalid_no_finding_evidence
+  - blocked
+coverage_quality_required_fields:
+  - scope_label
+  - posture
+  - warnings
+  - blockers
+audit_validity_required_fields:
+  - posture
+  - warnings
+  - blockers
+  - no_finding_posture
+  - p0p1_recall_required_count
+  - p0p1_recall_invalid_count
+  - p0p1_rule_check_count
+  - auditor_provenance_present
+  - calibration_expected_defect_count
+  - calibration_missed_defect_count
+hard_constraints:
+  - closeout_requires_latest_ledger_snapshot
+  - audit_complete_requires_no_active_chunks
+  - all_open_findings_require_remediation_map_coverage
+  - all_closed_findings_require_resolution_evidence
+  - coverage_status_partial_requires_partial_coverage_closeout_posture
+  - audit_validity_invalid_requires_audit_invalid_no_finding_evidence_posture
+  - coverage_quality_and_audit_validity_must_be_nested_objects_not_flattened_root_fields