@fro.bot/systematic 3.6.1 → 3.7.0

package/dist/lib/capability-snapshot.d.ts

@@ -0,0 +1,195 @@
+declare const CAPABILITY_SNAPSHOT_SCHEMA_VERSION: 'cli-capabilities.v1';
+declare const CAPABILITY_SNAPSHOT_COMMAND: 'systematic capabilities';
+declare const CAPABILITY_SOURCE_IDS: readonly ['config:custom', 'config:global', 'config:project', 'config:user', 'discovery:agents', 'discovery:skills', 'host:runtime', 'package'];
+declare const CONFIG_SOURCE_KINDS: readonly ['custom', 'project', 'user'];
+declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands', 'workflow_guard.debug', 'workflow_guard.mode'];
+declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['workflow_guard', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant'];
+declare const CONFIG_SOURCE_ERROR_CODES: readonly ['parse-failed', 'read-failed', 'schema-invalid', 'source-invalid'];
+declare const CAPABILITY_SOURCE_PRESENCE: readonly ['absent', 'invalid', 'present'];
+declare const CAPABILITY_STATUSES: readonly ['available', 'unknown', 'unavailable'];
+declare const CAPABILITY_FACT_IDS: readonly ['config-authority', 'config-field-authority', 'config-protected-field', 'discovery-summary', 'discovery-source-issue', 'host-runtime'];
+declare const CAPABILITY_DISCOVERY_IDS: readonly ['agents', 'skills'];
+declare const CAPABILITY_LIMITATION_CODES: readonly ['authority-unproven', 'discovery-not-collected', 'host-runtime-unobservable'];
+declare const CAPABILITY_ERROR_CODES: readonly ['source-malformed', 'source-read-failed', 'source-unsupported', 'structural-invalid'];
+declare const CAPABILITY_ROOT_IDS: readonly ['agents', 'cwd', 'global', 'package', 'project', 'skills', 'user', 'workspace'];
+type CapabilitySourceId = (typeof CAPABILITY_SOURCE_IDS)[number];
+type ConfigSourceKind = (typeof CONFIG_SOURCE_KINDS)[number];
+type ConfigAuthorityFieldPath = (typeof CONFIG_AUTHORITY_FIELD_PATHS)[number];
+type ConfigProtectedFieldPath = (typeof CONFIG_PROTECTED_FIELD_PATHS)[number];
+type ConfigSourceErrorCode = (typeof CONFIG_SOURCE_ERROR_CODES)[number];
+type CapabilitySourcePresence = (typeof CAPABILITY_SOURCE_PRESENCE)[number];
+type CapabilityStatus = (typeof CAPABILITY_STATUSES)[number];
+type CapabilityFactId = (typeof CAPABILITY_FACT_IDS)[number];
+type CapabilityStatusFactId = Exclude<CapabilityFactId, 'discovery-source-issue' | 'discovery-summary'>;
+type CapabilityDiscoveryIssueErrorCode = Extract<CapabilityErrorCode, 'source-malformed' | 'source-read-failed'>;
+type CapabilityDiscoveryId = (typeof CAPABILITY_DISCOVERY_IDS)[number];
+type CapabilityLimitationCode = (typeof CAPABILITY_LIMITATION_CODES)[number];
+type CapabilityErrorCode = (typeof CAPABILITY_ERROR_CODES)[number];
+type CapabilityRootId = (typeof CAPABILITY_ROOT_IDS)[number] | string;
+interface CapabilityPackageIdentity {
+    readonly name: string;
+    readonly version: string;
+}
+interface CapabilityRootInput {
+    readonly id: CapabilityRootId;
+    readonly path: string;
+}
+interface CapabilitySourceInput {
+    readonly sourceId: CapabilitySourceId;
+    readonly presence: CapabilitySourcePresence;
+    readonly sourceKind?: ConfigSourceKind;
+    readonly path?: string;
+    readonly errorCode?: CapabilityErrorCode;
+}
+export type CapabilityFactInput = {
+    readonly factId: Exclude<CapabilityFactId, 'config-field-authority' | 'config-protected-field' | 'discovery-source-issue' | 'discovery-summary'>;
+    readonly status: CapabilityStatus;
+    readonly sourceId?: CapabilitySourceId;
+    readonly limitationCode?: CapabilityLimitationCode;
+    readonly errorCode?: CapabilityErrorCode;
+} | {
+    readonly factId: 'config-field-authority';
+    readonly fieldPath: ConfigAuthorityFieldPath;
+    readonly kind: 'authority';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'available';
+} | {
+    readonly errorCode: CapabilityDiscoveryIssueErrorCode;
+    readonly factId: 'discovery-source-issue';
+    readonly kind: 'status';
+    readonly sourceId: 'discovery:skills';
+    readonly status: 'unavailable';
+} | {
+    readonly errorCode: CapabilityErrorCode;
+    readonly factId: 'discovery-summary';
+    readonly kind?: 'status';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'unavailable';
+} | {
+    readonly factId: 'config-protected-field';
+    readonly fieldPath: ConfigProtectedFieldPath;
+    readonly kind: 'protection';
+    readonly outcome: 'blocked';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'available';
+} | {
+    readonly count: number;
+    readonly discoveryId: CapabilityDiscoveryId;
+    readonly factId: 'discovery-summary';
+    readonly kind: 'discovery';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'available';
+    readonly winningRoots: readonly string[];
+};
+interface ConfigSourceMetadata {
+    readonly errorCode?: ConfigSourceErrorCode;
+    readonly kind: ConfigSourceKind;
+    readonly path?: string;
+    readonly presence: CapabilitySourcePresence;
+}
+interface ConfigAuthorityMetadata {
+    readonly fieldPath: ConfigAuthorityFieldPath;
+    readonly sourceKind: ConfigSourceKind;
+}
+interface ConfigProtectedFieldMetadata {
+    readonly fieldPath: ConfigProtectedFieldPath;
+    readonly outcome: 'blocked';
+    readonly sourceKind: ConfigSourceKind;
+}
+export interface ConfigObservationMetadata {
+    readonly authorities: readonly ConfigAuthorityMetadata[];
+    readonly protectedFields: readonly ConfigProtectedFieldMetadata[];
+    readonly sources: readonly ConfigSourceMetadata[];
+}
+export type CapabilityClock = () => number | Date;
+export type CapabilityOutputSink = (serialized: string) => void;
+interface CapabilitySnapshotBuilderOptions {
+    readonly argv: readonly string[];
+    readonly package: CapabilityPackageIdentity;
+    readonly roots: readonly CapabilityRootInput[];
+    readonly sources?: readonly CapabilitySourceInput[];
+    readonly facts?: readonly CapabilityFactInput[];
+    readonly config?: ConfigObservationMetadata;
+    readonly observedAt?: string;
+    readonly clock?: CapabilityClock;
+    readonly outputSink?: CapabilityOutputSink;
+}
+interface CapabilitySnapshotArgvIdentity {
+    readonly executable: string;
+    readonly subcommand: 'capabilities';
+}
+interface CapabilitySnapshotIdentity {
+    readonly argv: CapabilitySnapshotArgvIdentity;
+    readonly package: CapabilityPackageIdentity;
+}
+interface CapabilitySnapshotRoot {
+    readonly id: string;
+}
+interface CapabilitySnapshotSource {
+    readonly errorCode?: CapabilityErrorCode;
+    readonly kind: 'source';
+    readonly presence: CapabilitySourcePresence;
+    readonly sourceId: CapabilitySourceId;
+    readonly sourceKind?: ConfigSourceKind;
+}
+type CapabilitySnapshotFact = {
+    readonly factId: CapabilityStatusFactId;
+    readonly kind: 'status';
+    readonly status: 'available';
+} | {
+    readonly factId: CapabilityStatusFactId;
+    readonly kind: 'status';
+    readonly limitationCode: CapabilityLimitationCode;
+    readonly status: 'unknown';
+} | {
+    readonly errorCode: CapabilityErrorCode;
+    readonly factId: CapabilityStatusFactId;
+    readonly kind: 'status';
+    readonly sourceId?: CapabilitySourceId;
+    readonly status: 'unavailable';
+} | {
+    readonly errorCode: CapabilityErrorCode;
+    readonly factId: 'discovery-summary';
+    readonly kind: 'status';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'unavailable';
+} | {
+    readonly errorCode: CapabilityDiscoveryIssueErrorCode;
+    readonly factId: 'discovery-source-issue';
+    readonly kind: 'status';
+    readonly sourceId: 'discovery:skills';
+    readonly status: 'unavailable';
+} | {
+    readonly factId: 'config-field-authority';
+    readonly fieldPath: ConfigAuthorityFieldPath;
+    readonly kind: 'authority';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'available';
+} | {
+    readonly factId: 'config-protected-field';
+    readonly fieldPath: ConfigProtectedFieldPath;
+    readonly kind: 'protection';
+    readonly outcome: 'blocked';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'available';
+} | {
+    readonly count: number;
+    readonly discoveryId: CapabilityDiscoveryId;
+    readonly factId: 'discovery-summary';
+    readonly kind: 'discovery';
+    readonly sourceId: CapabilitySourceId;
+    readonly status: 'available';
+    readonly winningRoots: readonly string[];
+};
+interface CapabilitySnapshot {
+    readonly command: typeof CAPABILITY_SNAPSHOT_COMMAND;
+    readonly facts: readonly CapabilitySnapshotFact[];
+    readonly identity: CapabilitySnapshotIdentity;
+    readonly observedAt: string;
+    readonly roots: readonly CapabilitySnapshotRoot[];
+    readonly schemaVersion: typeof CAPABILITY_SNAPSHOT_SCHEMA_VERSION;
+    readonly sources: readonly CapabilitySnapshotSource[];
+}
+export declare function buildCapabilitySnapshot(options: CapabilitySnapshotBuilderOptions): CapabilitySnapshot;
+export declare function serializeCapabilitySnapshot(snapshot: CapabilitySnapshot): string;
+export {};

package/dist/lib/config-schema.d.ts

@@ -201,4 +201,4 @@ export declare function validateConfig(input: unknown): ValidationResult;
  *
  * Matches the hand-coded `SECURITY_OVERLAY_FIELDS` set in `src/lib/config.ts`.
  */
-export declare const SECURITY_OVERLAY_FIELDS: readonly string[];
+export declare const SECURITY_OVERLAY_FIELDS: readonly ['model', 'variant', 'skills', 'permission'];

package/dist/lib/config.d.ts

@@ -18,8 +18,35 @@ export interface SourcedOverlayConfigMap {
     agents: Record<string, SourcedOverlayConfig>;
     categories: Record<string, SourcedOverlayConfig>;
 }
+export declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands', 'workflow_guard.debug', 'workflow_guard.mode'];
+export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['workflow_guard', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant'];
+export type ConfigSourceKind = 'custom' | 'project' | 'user';
+export type ConfigSourcePresence = 'absent' | 'invalid' | 'present';
+export type ConfigSourceErrorCode = 'parse-failed' | 'read-failed' | 'schema-invalid' | 'source-invalid';
+export type ConfigAuthorityFieldPath = (typeof CONFIG_AUTHORITY_FIELD_PATHS)[number];
+export type ConfigProtectedFieldPath = (typeof CONFIG_PROTECTED_FIELD_PATHS)[number];
+export interface ConfigSourceMetadata {
+    readonly errorCode?: ConfigSourceErrorCode;
+    readonly kind: ConfigSourceKind;
+    readonly presence: ConfigSourcePresence;
+}
+export interface ConfigAuthorityMetadata {
+    readonly fieldPath: ConfigAuthorityFieldPath;
+    readonly sourceKind: ConfigSourceKind;
+}
+export interface ConfigProtectedFieldMetadata {
+    readonly fieldPath: ConfigProtectedFieldPath;
+    readonly outcome: 'blocked';
+    readonly sourceKind: ConfigSourceKind;
+}
+export interface ConfigObservationMetadata {
+    readonly authorities: readonly ConfigAuthorityMetadata[];
+    readonly protectedFields: readonly ConfigProtectedFieldMetadata[];
+    readonly sources: readonly ConfigSourceMetadata[];
+}
 export interface SourceAwareConfigResult {
     config: SystematicConfig;
+    metadata: ConfigObservationMetadata;
     overlays: SourcedOverlayConfigMap;
 }
 export interface PiSubagentsOverlayMap {
@@ -51,7 +78,7 @@ export declare function computeDroppedNames(names: readonly string[], allowedSet
  * single load call -- callers must NOT share it across independent loads.
  * Passing a fresh set per load ensures no cross-load suppression.
  */
-export declare function warnDroppedNames(dropped: string[], field: string, warned: Set<string>, removalVersion?: string): void;
+export declare function warnDroppedNames(dropped: string[], field: string, warned: Set<string>, removalVersion?: string, warningSink?: (message: string) => void): void;
 export interface LoadConfigOptions {
     /**
      * When false, the project-level config source (`<cwd>/.opencode/systematic.json`)
@@ -60,10 +87,20 @@ export interface LoadConfigOptions {
      * absorbs cwd project overlays (plan R7/R19). Defaults to true.
      */
     includeProject?: boolean;
+    invalidSource?: 'throw' | 'report';
+    homeDir?: string;
+    userConfigDir?: string;
+    customConfigDir?: string | null;
+    warningSink?: (message: string) => void;
 }
 export declare function loadConfig(projectDir: string, options?: LoadConfigOptions): SystematicConfig;
 export declare function loadConfigWithSources(projectDir: string, options?: LoadConfigOptions): SourceAwareConfigResult;
-export declare function getConfigPaths(projectDir: string): {
+interface ConfigPathOptions {
+    readonly homeDir?: string;
+    readonly userConfigDir?: string;
+    readonly customConfigDir?: string | null;
+}
+export declare function getConfigPaths(projectDir: string, options?: ConfigPathOptions): {
     userConfig: string;
     projectConfig: string;
     userDir: string;
@@ -71,3 +108,4 @@ export declare function getConfigPaths(projectDir: string): {
     customConfig?: string | undefined;
     customDir?: string | undefined;
 };
+export {};

package/dist/lib/discovered-skills.d.ts

@@ -11,6 +11,7 @@ import { type SkillFrontmatter } from './skills.js';
  * upstream.
  */
 type DiscoveryRootId = 'global-claude' | 'global-agents' | 'project-claude' | 'project-agents' | 'project-opencode' | 'global-opencode-config';
+export type SkillDiscoveryIssueCode = 'read-failed' | 'source-invalid';
 export interface DiscoveredSkill {
     name: string;
     description: string;
@@ -40,6 +41,8 @@ export interface DiscoverSkillsOptions {
      * discovery pure and testable.
      */
     opencodeConfigDirOverride?: string;
+    /** Optional bounded issue sink; discovery winners and precedence are unchanged. */
+    onIssue?: (issue: SkillDiscoveryIssueCode) => void;
 }
 /**
  * Discover user/project skills, replicating OpenCode v1.17.6's real

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "3.6.1",
+  "version": "3.7.0",
   "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
   "type": "module",
   "homepage": "https://fro.bot/systematic",
@@ -103,7 +103,7 @@
     "agent-browser": "0.33.1",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
-    "conventional-changelog-conventionalcommits": "10.2.1",
+    "conventional-changelog-conventionalcommits": "10.3.0",
     "markdownlint-cli": "0.49.1",
     "rimraf": "6.1.3",
     "semantic-release": "25.0.9",