@archpilotlabs/archpilot 0.0.3 → 0.0.5

package/README.md

@@ -1,11 +1,31 @@
-# ArchPilot
+<p align="center">
+  <img src="https://archpilot.org/logo.svg" width="100" />
+</p>
 
-**Executable architecture governance for your codebase.**
+<h1 align="center">ArchPilot</h1>
+
+<p align="center">
+  Executable architecture governance for your codebase
+</p>
+
+<p align="center">
+  Validate • Enforce • Measure your architecture - continuously
+</p>
 
 ArchPilot is a CLI that validates your repository against architecture rules and helps you keep your system **visible, enforceable, and measurable** as it evolves.
 
 ---
 
+## 🧭 Why this exists
+
+Most teams rely on documentation or tribal knowledge to maintain architecture.
+
+Over time, boundaries blur, dependencies leak, and architectural decisions drift without anyone noticing.
+
+ArchPilot turns architecture into something you can **actually validate, enforce, and track continuously**.
+
+---
+
 ## 🚀 What it does
 
 ArchPilot turns architecture into something you can actually run and verify:
@@ -132,7 +152,7 @@ archpilot governance upload
 
 ---
 
-## 🧩 Features
+## 🧩 Core Capabilities
 
 * Architecture-as-code (`.archpilot/`)
 * Dependency validation and module contracts
@@ -156,7 +176,7 @@ ArchPilot is built on four principles:
 
 ## 📄 License
 
-All rights reserved. This software is proprietary and closed-source.
+Proprietary. See LICENSE file for details.
 
 ---
 

package/dist/archpilot-cli.js

@@ -218290,8 +218290,8 @@ function assessChangeRisk(input2) {
     },
     {
       id: "CRF-015",
-      label: "Diff context unavailable",
-      description: "Diff-aware scope was unavailable; risk uses fallback signals only.",
+      label: "Full validation mode (no scoped diff provided)",
+      description: "No scoped diff was provided; risk uses full validation context.",
       weight: 2,
       category: "scope"
     }
@@ -218354,7 +218354,7 @@ function assessChangeRisk(input2) {
     trigger("CRF-016", `warningCount=${input2.warningCount}, affectedDependents=${affectedDependentsCount}`);
   }
   if (!diffContextAvailable) {
-    trigger("CRF-015", "no changed/diff context available");
+    trigger("CRF-015", "no scoped diff was provided; full validation context used");
   }
   const signals = {
     ...changedModulesCount !== void 0 ? { changedModulesCount } : {},
@@ -222254,7 +222254,7 @@ function renderArchitectureReviewConsole(summary, options) {
   lines.push("ArchPilot Architecture Review");
   lines.push("");
   lines.push(`Result: ${getValidationResultLabel(summary)}`);
-  lines.push(`Risk level (Governance Risk): ${summary.risk.level.toUpperCase()}`);
+  lines.push(`Architecture Review Level: ${summary.risk.level.toUpperCase()}`);
   lines.push(`Enforcement (Policy Outcome): ${summary.enforcement.action.toUpperCase()}`);
   if (summary.enforcement.policyLevel) {
     lines.push(`Policy level: ${summary.enforcement.policyLevel.toUpperCase()}`);
@@ -222348,7 +222348,7 @@ function renderArchitectureReviewConsole(summary, options) {
     lines.push(`  - ${summary.adrRequirement.suggestedFilenameHint}`);
   }
   if (summary.safetyControls) {
-    lines.push("Missing Safety Controls:");
+    lines.push("Recommended Deployment Safety Controls:");
     lines.push(`- Triggered: ${summary.safetyControls.triggered ? "YES" : "NO"}`);
     lines.push(`- Applicable: ${summary.safetyControls.applicable ? "YES" : "NO"}`);
     lines.push(`- Summary: ${summary.safetyControls.summary}`);
@@ -222588,7 +222588,7 @@ ${options.impactAnalysisSection}
 - Quality findings: ${summary.qualityFindings}
 - Setup gaps: ${summary.setupGaps}
 - Guidance findings: ${summary.guidanceFindings}
-- Risk level (governance risk): ${summary.risk.level.toUpperCase()}
+- Architecture Review Level: ${summary.risk.level.toUpperCase()}
 - Enforcement (policy outcome): ${summary.enforcement.action.toUpperCase()}
 - Change risk (diff-aware PR impact): ${summary.changeRisk.riskLevel.toUpperCase()}
 - Impact radius level: ${summary.impactAnalysis.impactLevel}
@@ -222628,15 +222628,15 @@ ${options?.driftReport ? `- Drift detected: ${options.driftReport.summaryCounts.
 - Dependencies removed: ${options.driftReport.summaryCounts.dependenciesRemoved}` : "- No baseline drift report is available. Run `archpilot baseline check` to generate drift-report.md details."}
 
 ## Governance Summary
-- Governance Risk: ${summary.risk.level.toUpperCase()}
+- Architecture Review Level: ${summary.risk.level.toUpperCase()}
 - Change Risk: ${summary.changeRisk.riskLevel.toUpperCase()}
 - Enforcement Outcome: ${summary.enforcement.enforcementDecision ?? summary.enforcement.action.toUpperCase()}
 - Policy Level: ${summary.enforcement.policyLevel?.toUpperCase() ?? "N/A"}
 - Approved exceptions: ${summary.counts.exceptions ?? 0}
 - Suppressed findings: ${summary.counts.suppressed}
 
-## Risk Assessment (Governance Risk)
-- Risk level: ${summary.risk.level.toUpperCase()}
+## Architecture Review Level
+- Level: ${summary.risk.level.toUpperCase()}
 - Reasons:
 ${summary.risk.reasons.map((reason) => `  - ${reason}`).join("\n")}
 
@@ -222664,7 +222664,7 @@ ${adrDisplay.state === "required" && summary.adrRequirement.suggestedCommand ? `
 - Suggested filename hint:
 ${adrDisplay.state === "required" && summary.adrRequirement.suggestedFilenameHint ? `  - ${summary.adrRequirement.suggestedFilenameHint}` : "  - (none)"}
 
-## Missing Safety Controls
+## Recommended Deployment Safety Controls
 ${summary.safetyControls ? `- Triggered: ${summary.safetyControls.triggered ? "YES" : "NO"}
 - Applicable: ${summary.safetyControls.applicable ? "YES" : "NO"}
 - Summary: ${summary.safetyControls.summary}
@@ -222812,13 +222812,13 @@ function renderArchitectureReviewCompactMarkdown(summary, options) {
 - Passed: ${summary.counts.passed}
 - Suppressed: ${summary.counts.suppressed}
 - Exceptions: ${summary.counts.exceptions ?? 0}
-- Risk level (Governance Risk): ${summary.risk.level.toUpperCase()}
+- Architecture Review Level: ${summary.risk.level.toUpperCase()}
 - Enforcement (Policy Outcome): ${summary.enforcement.action.toUpperCase()}
 - Policy Level: ${summary.enforcement.policyLevel?.toUpperCase() ?? "N/A"}
 - ADR Required: ${adrDisplay.requiredLabel}
 - ADR Satisfied: ${adrDisplay.satisfiedLabel}
 - ADR Suggested command: ${adrDisplay.state === "required" ? summary.adrRequirement.suggestedCommand ?? "(none)" : "(none)"}
-- Missing Safety Controls: ${(summary.safetyControls?.findings.length ?? 0) > 0 ? `${summary.safetyControls?.findings.length} finding(s)` : summary.safetyControls?.triggered ? "none" : "not-applicable"}
+- Recommended Deployment Safety Controls: ${(summary.safetyControls?.findings.length ?? 0) > 0 ? `${summary.safetyControls?.findings.length} finding(s)` : summary.safetyControls?.triggered ? "none" : "not-applicable"}
 - Change Risk (Diff-Aware PR Impact): ${summary.changeRisk.riskLevel.toUpperCase()}
 - Change Risk Summary: ${summary.changeRisk.summary}
 - Impact Analysis: ${summary.impactAnalysis.impactLevel} (radius ${summary.impactAnalysis.impactRadiusScore})
@@ -222843,6 +222843,9 @@ function formatRuleLine(ruleId) {
   const metadata = getValidationRuleMetadataById(ruleId);
   return `${ruleId} ${metadata.title}`;
 }
+function formatFindingLine(finding) {
+  return `${formatRuleLine(finding.id)} | ${finding.message}`;
+}
 function parseFindingKind2(value) {
   return value === "violation" || value === "setup-gap" || value === "guidance" ? value : void 0;
 }
@@ -222900,21 +222903,24 @@ function renderArchitecturePrCommentMarkdown(input2) {
     (input2.driftComparison?.resolvedViolations ?? []).filter((entry) => resolveKind(entry) === "setup-gap").map((entry) => formatRuleLine(entry.ruleId))
   );
   const activeQualityViolationLines = sortUniqueLines(
-    input2.summary.findings.filter((entry) => resolveKind({ ruleId: entry.id, message: entry.message }) === "violation").map((entry) => formatRuleLine(entry.id))
+    input2.summary.findings.filter((entry) => resolveKind({ ruleId: entry.id, message: entry.message }) === "violation").map((entry) => formatFindingLine(entry))
   );
   const activeSetupGapLines = sortUniqueLines(
-    input2.summary.findings.filter((entry) => resolveKind({ ruleId: entry.id, message: entry.message }) === "setup-gap").map((entry) => formatRuleLine(entry.id))
+    input2.summary.findings.filter((entry) => resolveKind({ ruleId: entry.id, message: entry.message }) === "setup-gap").map((entry) => formatFindingLine(entry))
   );
   const activeGuidanceLines = sortUniqueLines(
-    input2.summary.findings.filter((entry) => resolveKind({ ruleId: entry.id, message: entry.message }) === "guidance").map((entry) => formatRuleLine(entry.id))
+    input2.summary.findings.filter((entry) => resolveKind({ ruleId: entry.id, message: entry.message }) === "guidance").map((entry) => formatFindingLine(entry))
   );
+  const activeQualityViolationCount = activeQualityViolationLines.length;
+  const activeSetupGapCount = activeSetupGapLines.length;
+  const activeGuidanceCount = activeGuidanceLines.length;
   const summaryWithReadiness = input2.summary;
   const trendLine = input2.healthTrend ? formatArchitectureHealthTrendLine(input2.healthTrend) : "Trend: no previous history";
   const scoreDelta = input2.driftComparison?.scoreDelta ?? 0;
   const isScoreDrop = !!input2.driftComparison?.hasPreviousSnapshot && scoreDelta < 0;
-  const hasViolations = activeQualityViolationLines.length > 0;
-  const hasSetupGaps = (summaryWithReadiness.setupGaps ?? 0) > 0 || activeSetupGapLines.length > 0;
-  const hasGuidance = input2.summary.guidanceFindings > 0 || activeGuidanceLines.length > 0;
+  const hasViolations = activeQualityViolationCount > 0;
+  const hasSetupGaps = activeSetupGapCount > 0;
+  const hasGuidance = activeGuidanceCount > 0;
   const elevatedChangeRisk = input2.summary.changeRisk.riskLevel !== "low";
   const useDetailed = hasViolations || hasSetupGaps || hasGuidance || elevatedChangeRisk || isScoreDrop;
   const changedModulesCount = input2.summary.changeRisk.signals.changedModulesCount;
@@ -222941,8 +222947,8 @@ function renderArchitecturePrCommentMarkdown(input2) {
   lines.push("ArchPilot Review");
   lines.push(`Score: ${input2.summary.healthScore} / 100`);
   lines.push(`Change Risk: ${input2.summary.changeRisk.riskLevel.toUpperCase()}`);
-  lines.push(`Violations: ${input2.summary.qualityFindings}`);
-  lines.push(`Setup Gaps: ${summaryWithReadiness.setupGaps ?? 0}`);
+  lines.push(`Violations: ${activeQualityViolationCount}`);
+  lines.push(`Setup Gaps: ${activeSetupGapCount}`);
   lines.push("");
   lines.push(`Change Risk (Diff-Aware PR Impact): ${changeRiskSummary}`);
   lines.push(`Change Risk Summary: ${input2.summary.changeRisk.summary}`);
@@ -222963,7 +222969,7 @@ function renderArchitecturePrCommentMarkdown(input2) {
     );
   }
   lines.push("");
-  lines.push(`Risk level (Governance Risk): ${input2.summary.risk.level.toUpperCase()}`);
+  lines.push(`Architecture Review Level: ${input2.summary.risk.level.toUpperCase()}`);
   for (const reason of input2.summary.risk.reasons) {
     lines.push(`- ${reason}`);
   }
@@ -223022,7 +223028,7 @@ function renderArchitecturePrCommentMarkdown(input2) {
   }
   if (input2.summary.safetyControls?.triggered && (input2.summary.safetyControls.findings.length ?? 0) > 0) {
     lines.push("");
-    lines.push("Missing Safety Controls");
+    lines.push("Recommended Deployment Safety Controls");
     lines.push(`- ${input2.summary.safetyControls.summary}`);
     for (const finding of input2.summary.safetyControls.findings) {
       lines.push(
@@ -223036,7 +223042,7 @@ function renderArchitecturePrCommentMarkdown(input2) {
     lines.push(`Setup Readiness: ${summaryWithReadiness.readinessScore} / 100`);
   }
   if (typeof summaryWithReadiness.setupGaps === "number") {
-    lines.push(`Setup gaps: ${summaryWithReadiness.setupGaps}`);
+    lines.push(`Setup gaps: ${activeSetupGapCount}`);
   }
   lines.push(trendLine);
   if (input2.driftComparison?.hasPreviousSnapshot) {
@@ -223064,7 +223070,7 @@ function renderArchitecturePrCommentMarkdown(input2) {
   lines.push("</details>");
   lines.push("");
   lines.push("<details>");
-  lines.push(`<summary>Violations (${activeQualityViolationLines.length})</summary>`);
+  lines.push(`<summary>Violations (${activeQualityViolationCount})</summary>`);
   lines.push("");
   lines.push(
     activeQualityViolationLines.length === 0 ? "- (none)" : activeQualityViolationLines.map((line) => `- ${line}`).join("\n")
@@ -223072,7 +223078,7 @@ function renderArchitecturePrCommentMarkdown(input2) {
   lines.push("</details>");
   lines.push("");
   lines.push("<details>");
-  lines.push(`<summary>Setup Gaps (${activeSetupGapLines.length})</summary>`);
+  lines.push(`<summary>Setup Gaps (${activeSetupGapCount})</summary>`);
   lines.push("");
   lines.push(
     activeSetupGapLines.length === 0 ? "- (none)" : activeSetupGapLines.map((line) => `- ${line}`).join("\n")
@@ -223080,7 +223086,7 @@ function renderArchitecturePrCommentMarkdown(input2) {
   lines.push("</details>");
   lines.push("");
   lines.push("<details>");
-  lines.push(`<summary>Guidance (${activeGuidanceLines.length})</summary>`);
+  lines.push(`<summary>Guidance (${activeGuidanceCount})</summary>`);
   lines.push("");
   lines.push(
     activeGuidanceLines.length === 0 ? "- (none)" : activeGuidanceLines.map((line) => `- ${line}`).join("\n")
@@ -225662,9 +225668,9 @@ function renderArchitecturePrReviewMarkdown(input2) {
   }
   if (input2.validation.kind === "ok" && input2.validation.data.risk) {
     const governanceRisk = input2.validation.data.risk;
-    lines.push("## Risk Level (Governance Risk)");
+    lines.push("## Architecture Review Level");
     lines.push("- Purpose: governance severity derived from validation results.");
-    lines.push(`- Risk Level: ${governanceRisk.level.toUpperCase()}`);
+    lines.push(`- Architecture Review Level: ${governanceRisk.level.toUpperCase()}`);
     lines.push("- Reasons:");
     lines.push(
       governanceRisk.reasons.length === 0 ? "  - (none)" : governanceRisk.reasons.map((reason) => `  - ${reason}`).join("\n")
@@ -225734,7 +225740,7 @@ function renderArchitecturePrReviewMarkdown(input2) {
   if (input2.validation.kind === "ok" && input2.validation.data.safetyControls) {
     const safety = input2.validation.data.safetyControls;
     if (safety.triggered && (safety.findings?.length ?? 0) > 0) {
-      lines.push("## Missing Safety Controls");
+      lines.push("## Recommended Deployment Safety Controls");
       lines.push(`- Summary: ${safety.summary ?? "Missing safety controls detected."}`);
       lines.push(
         `- Missing controls: ${(safety.missingControls ?? []).length > 0 ? (safety.missingControls ?? []).join(", ") : "(none)"}`
@@ -228260,7 +228266,7 @@ function renderArchitectureReviewReportMarkdown(input2) {
 - Setup Readiness Score: ${summary.readinessScore} / 100
 - Trend: ${String(payload.summary.postureTrend)}
 - Change Risk: ${summary.changeRisk.riskLevel.toUpperCase()} (${summary.changeRisk.summary})
-- Governance Risk: ${summary.risk.level.toUpperCase()}
+- Architecture Review Level: ${summary.risk.level.toUpperCase()}
 - Enforcement Outcome: ${summary.enforcement.enforcementDecision ?? summary.enforcement.action.toUpperCase()}
 - ADR Required: ${adrDisplay.requiredLabel}
 - ADR Satisfied: ${adrDisplay.satisfiedLabel}
@@ -228306,7 +228312,7 @@ ${toLines(adrDisplay.reasons)}
 ${adrDisplay.state === "required" && summary.adrRequirement.suggestedCommand ? `- Suggested ADR command: ${summary.adrRequirement.suggestedCommand}` : ""}
 ${adrDisplay.state === "required" && summary.adrRequirement.suggestedFilenameHint ? `- Suggested ADR filename hint: ${summary.adrRequirement.suggestedFilenameHint}` : ""}
 
-## Missing Safety Controls
+## Recommended Deployment Safety Controls
 - Triggered: ${safetyControls.triggered ? "YES" : "NO"}
 - Applicable: ${safetyControls.applicable ? "YES" : "NO"}
 - Summary: ${safetyControls.summary}
@@ -228360,7 +228366,7 @@ function renderArchitectureDriftReportMarkdown(input2) {
 ## Impact Summary
 - Architecture Health Score: ${input2.summary.healthScore} / 100
 - Change Risk: ${input2.summary.changeRisk.riskLevel.toUpperCase()}
-- Governance Risk: ${input2.summary.risk.level.toUpperCase()}
+- Architecture Review Level: ${input2.summary.risk.level.toUpperCase()}
 
 ## Suggested Actions
 - Create a baseline snapshot if this architecture state is accepted.
@@ -228427,7 +228433,7 @@ function renderArchitectureGovernanceReportMarkdown(input2) {
 - Generated at (UTC): ${summary.generatedAtUtc}
 ${input2.commitSha ? `- Commit SHA: ${input2.commitSha}` : ""}
 - Architecture Score: ${summary.healthScore} / 100
-- Governance Risk: ${summary.risk.level.toUpperCase()}
+- Architecture Review Level: ${summary.risk.level.toUpperCase()}
 - Change Risk: ${summary.changeRisk.riskLevel.toUpperCase()}
 - Enforcement Outcome: ${enforcementDecision}
 - Policy Level: ${summary.enforcement.policyLevel?.toUpperCase() ?? "N/A"}
@@ -230045,6 +230051,9 @@ function validateGovernanceUploadPayload(payload) {
   if (!isFiniteNumber(typed.schemaVersion)) {
     errors.push("schemaVersion must be a finite number.");
   }
+  if (typed.uploadMode !== "manual" && typed.uploadMode !== "ci") {
+    errors.push('uploadMode must be "manual" or "ci".');
+  }
   const organization = typed.organization;
   const repository = typed.repository;
   const snapshot = typed.snapshot;
@@ -230203,6 +230212,13 @@ function deriveOrganizationSlug(input2) {
 function isCiEnvironment(environment) {
   return environment.CI === "true" || typeof environment.GITHUB_ACTIONS === "string";
 }
+function resolveRequestedUploadMode(environment) {
+  const explicit = asString(environment.ARCHPILOT_UPLOAD_MODE);
+  if (explicit) {
+    return explicit.toLowerCase();
+  }
+  return void 0;
+}
 function readEnvironmentIdentity(environment) {
   const branch = asString(environment.GITHUB_REF_NAME) ?? asString(environment.CI_COMMIT_REF_NAME) ?? asString(environment.BRANCH_NAME) ?? null;
   const commitSha = asString(environment.GITHUB_SHA) ?? asString(environment.CI_COMMIT_SHA) ?? asString(environment.COMMIT_SHA) ?? null;
@@ -230296,6 +230312,7 @@ function buildGovernanceUploadPayload(input2) {
   const governanceRisk = asRecord(architectureSummary.risk) ?? {};
   const enforcement = asRecord(architectureSummary.enforcement) ?? {};
   const environment = input2.environment ?? process.env;
+  const requestedUploadMode = resolveRequestedUploadMode(environment);
   const environmentIdentity = readEnvironmentIdentity(environment);
   const repository = resolveRepositoryContract({
     workspaceRoot: input2.workspaceRoot,
@@ -230316,7 +230333,7 @@ function buildGovernanceUploadPayload(input2) {
       environmentIdentity.branch ?? input2.gitMetadata?.branch,
       repository.defaultBranch
     ),
-    source: isCiEnvironment(environment) ? "ci" : "cli",
+    source: requestedUploadMode === "ci" || isCiEnvironment(environment) ? "ci" : "cli",
     architectureScore: asNumber(
       validationSummary.healthScore,
       asNumber(architectureSummary.healthScore, 0)
@@ -230344,8 +230361,10 @@ function buildGovernanceUploadPayload(input2) {
       cliVersion: input2.archpilotVersion
     }
   };
+  const uploadMode = requestedUploadMode ?? (snapshot.source === "ci" ? "ci" : "manual");
   const payload = {
     schemaVersion: 1,
+    uploadMode,
     organization: normalizeOrganization({
       projectIdentity: input2.projectIdentity,
       gitMetadata: input2.gitMetadata,
@@ -230471,6 +230490,23 @@ async function buildGovernanceUploadPayloadForWorkspace(input2) {
 }
 
 // ../core/src/governance/governanceUploadClient.ts
+var GovernanceUploadHttpError = class extends Error {
+  endpoint;
+  statusCode;
+  response;
+  responseMessage;
+  constructor(input2) {
+    const responseMessage = input2.responseMessage?.trim() ?? "";
+    super(
+      `Governance upload failed with status ${input2.statusCode}.${responseMessage ? ` ${responseMessage}` : ""}`
+    );
+    this.name = "GovernanceUploadHttpError";
+    this.endpoint = input2.endpoint;
+    this.statusCode = input2.statusCode;
+    this.response = input2.response;
+    this.responseMessage = responseMessage;
+  }
+};
 function resolveUploadEndpoint(serverUrl) {
   const trimmed = serverUrl.trim();
   if (trimmed.length === 0) {
@@ -230497,6 +230533,26 @@ function parseResponseBody(raw) {
     return { message: raw };
   }
 }
+function extractResponseMessage(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return "";
+  }
+  const record = parsed;
+  if (typeof record.message === "string") {
+    return record.message.trim();
+  }
+  if (typeof record.error === "string") {
+    return record.error.trim();
+  }
+  const nestedError = record.error;
+  if (nestedError && typeof nestedError === "object" && !Array.isArray(nestedError)) {
+    const nestedMessage = nestedError.message;
+    if (typeof nestedMessage === "string") {
+      return nestedMessage.trim();
+    }
+  }
+  return "";
+}
 async function uploadGovernanceSnapshot(input2) {
   const endpoint = resolveUploadEndpoint(input2.serverUrl);
   const timeoutMs = input2.timeoutMs ?? 1e4;
@@ -230523,10 +230579,12 @@ async function uploadGovernanceSnapshot(input2) {
     const raw = await response.text();
     const parsed = parseResponseBody(raw);
     if (!response.ok) {
-      const responseMessage = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? typeof parsed.message === "string" ? parsed.message.trim() : "" : "";
-      throw new Error(
-        `Governance upload failed with status ${response.status}.${responseMessage ? ` ${responseMessage}` : ""}`
-      );
+      throw new GovernanceUploadHttpError({
+        endpoint,
+        statusCode: response.status,
+        response: parsed,
+        responseMessage: extractResponseMessage(parsed)
+      });
     }
     return {
       endpoint,
@@ -233717,6 +233775,35 @@ function parseGovernanceUploadFlags(args) {
     ...readFlagValue(args, "--token") ? { token: readFlagValue(args, "--token") } : {}
   };
 }
+function resolveCliGovernanceUploadMode(environment) {
+  const explicitUploadMode = environment.ARCHPILOT_UPLOAD_MODE?.trim().toLowerCase();
+  if (explicitUploadMode === "ci") {
+    return "ci";
+  }
+  return environment.CI === "true" || typeof environment.GITHUB_ACTIONS === "string" ? "ci" : "manual";
+}
+function normalizeApiMessage(value) {
+  return value.trim().toLowerCase().replace(/\s+/gu, " ").replace(/[.]+$/u, "");
+}
+function isKnownFreePlanCiGovernanceUploadMessage(message) {
+  const normalized = normalizeApiMessage(message);
+  return normalized === "ci governance upload skipped: current plan supports manual uploads only" || normalized === "automatic ci governance upload is not available on the free plan" || normalized === "automatic ci-to-cloud governance upload is not available on the free plan" || normalized === "ci-to-cloud governance upload is not available on the free plan";
+}
+function isFreePlanCiGovernanceUploadSkip(error, uploadMode) {
+  return uploadMode === "ci" && error instanceof GovernanceUploadHttpError && error.statusCode === 403 && isKnownFreePlanCiGovernanceUploadMessage(error.responseMessage);
+}
+function renderGovernanceUploadSkippedByPlan() {
+  return [
+    "ArchPilot Governance Upload",
+    "",
+    "Status: Skipped",
+    "CI governance upload skipped: current plan supports manual uploads only.",
+    "",
+    "What you can do:",
+    "- Use manual governance upload from the CLI or Inspector",
+    "- Upgrade your plan to enable CI-to-Cloud upload on main"
+  ].join("\n");
+}
 function printUsage() {
   console.error("Usage: archpilot init");
   console.error("Usage: archpilot validate [--ci] [--json] [--changed] [--diff] [--base <branch>]");
@@ -236667,12 +236754,20 @@ async function runGovernanceCommand(args) {
       ...flags.server ? { serverUrl: flags.server } : {},
       ...flags.token ? { token: flags.token } : {}
     });
+    console.log("ArchPilot Governance Upload");
+    console.log("");
+    console.log("Status: Uploaded");
     console.log(`Uploaded governance snapshot for ${result.repository} at ${result.commitSha}.`);
     console.log(
       `Findings: ${result.totalFindings} total (${result.errors} errors, ${result.warnings} warnings). Score: ${result.architectureHealth ?? "n/a"}.`
     );
     return 0;
   } catch (error) {
+    const uploadMode = resolveCliGovernanceUploadMode(process.env);
+    if (isFreePlanCiGovernanceUploadSkip(error, uploadMode)) {
+      console.log(renderGovernanceUploadSkippedByPlan());
+      return 0;
+    }
     const message = error instanceof Error ? error.message : "Governance upload failed.";
     console.error(message);
     if (message.includes("Governance upload requires server URL and token")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archpilotlabs/archpilot",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Executable architecture governance CLI",
   "homepage": "https://archpilot.org",
   "bugs": {