@skillcap/gdh 0.22.0 → 0.24.0

package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Managed-surface drift classification manifest.
+ *
+ * Single source of truth for assigning every GDH-managed render call site to
+ * one of three drift classes: `"deterministic"`, `"user-data"`, or
+ * `"project-native"`. Required by GOV-03 (.planning/REQUIREMENTS.md) and
+ * locked by Phase 70 decisions D-05, D-06, D-08, D-13..D-24 in
+ * .planning/phases/70-governance-and-managed-surface-drift-classification/70-CONTEXT.md.
+ *
+ * Consumers:
+ *   - Migration registry (Phase 72)
+ *   - Chain matrix (Phase 71)
+ *   - Migration verifier (Phase 74)
+ *   - Renderer-side load-time guards (Plan 70-05) via `assertClassRegistered`
+ *   - `validate:docs` manifest-covers-renderers check (Plan 70-06)
+ *
+ * Out of classification scope per D-23: every path under `.gdh-state/` is
+ * machine-local state owned entirely by GDH; it is intentionally not a
+ * managed surface in the migration sense and is therefore absent from this
+ * manifest. The renderer `renderLocalPathHints` (which writes
+ * `.gdh-state/local-paths.json`) is the canonical example of an excluded
+ * surface.
+ *
+ * Three-class lock (D-24): the union below has exactly three members. No
+ * fourth class. No subclasses. Project-native surfaces declare a narrow op
+ * allowlist instead of a subclass.
+ */
+export type GdhManagedSurfaceClass = "deterministic" | "user-data" | "project-native";
+export interface GdhProjectNativeOpAllowlistEntry {
+    /** Stable op identifier referenced by registry entries (Phase 72). */
+    readonly op: string;
+    /** One-line human-readable description of what the op does. */
+    readonly summary: string;
+}
+export interface GdhManagedSurfaceClassEntry {
+    /**
+     * Stable surface identifier. Audit-time-frozen. No synonyms, no renames
+     * after audit — downstream consumers (registry, matrix, verifier) bind to
+     * these strings.
+     */
+    readonly surfaceId: string;
+    /**
+     * Workspace-relative output path of the surface, or `null` when the path
+     * varies (per-agent skills, per-target paths, multi-file surfaces).
+     */
+    readonly relativePath: string | null;
+    /** One of the three locked drift classes. */
+    readonly class: GdhManagedSurfaceClass;
+    /** Why this class — the audit decision rationale. */
+    readonly notes: string;
+    /**
+     * For project-native surfaces only — the narrow set of ops the
+     * migration registry may invoke against this surface. Anything outside the
+     * allowlist is rejected at audit-time. Adding an op requires both a
+     * manifest update AND a registry entry that declares it explicitly.
+     */
+    readonly projectNativeAllowlist?: readonly GdhProjectNativeOpAllowlistEntry[];
+}
+/**
+ * The classification manifest. Every render call site discovered during the
+ * Phase 70 audit appears here exactly once. The `as const satisfies` form
+ * preserves literal-string typing (downstream narrowing) while shape-checking
+ * each entry against `GdhManagedSurfaceClassEntry`.
+ */
+export declare const GDH_MANAGED_SURFACE_CLASSES: readonly [{
+    readonly surfaceId: "skill.claude.onboard";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'onboard', version). Per-target path: .claude/skills/gdh-onboard/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.claude.status";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'status', version). Per-target path: .claude/skills/gdh-status/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.claude.scan";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'scan', version). Per-target path: .claude/skills/gdh-scan/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.claude.migrate";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'migrate', version). Per-target path: .claude/skills/gdh-migrate/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.claude.update";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'update', version). Per-target path: .claude/skills/gdh-update/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.claude.check";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'check', version). Per-target path: .claude/skills/gdh-check/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.claude.prepare";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'prepare', version). Per-target path: .claude/skills/gdh-prepare/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.claude.run-game";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('claude', 'run-game', version). Per-target path: .claude/skills/gdh-run-game/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.onboard";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'onboard', version). Per-target path: .codex/skills/gdh-onboard/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.status";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'status', version). Per-target path: .codex/skills/gdh-status/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.scan";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'scan', version). Per-target path: .codex/skills/gdh-scan/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.migrate";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'migrate', version). Per-target path: .codex/skills/gdh-migrate/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.update";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'update', version). Per-target path: .codex/skills/gdh-update/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.check";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'check', version). Per-target path: .codex/skills/gdh-check/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.prepare";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'prepare', version). Per-target path: .codex/skills/gdh-prepare/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.codex.run-game";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('codex', 'run-game', version). Per-target path: .codex/skills/gdh-run-game/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.onboard";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'onboard', version). Per-target path: .cursor/skills/gdh-onboard/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.status";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'status', version). Per-target path: .cursor/skills/gdh-status/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.scan";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'scan', version). Per-target path: .cursor/skills/gdh-scan/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.migrate";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'migrate', version). Per-target path: .cursor/skills/gdh-migrate/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.update";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'update', version). Per-target path: .cursor/skills/gdh-update/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.check";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'check', version). Per-target path: .cursor/skills/gdh-check/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.prepare";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'prepare', version). Per-target path: .cursor/skills/gdh-prepare/SKILL.md.";
+}, {
+    readonly surfaceId: "skill.cursor.run-game";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Generated agent skill rendered by renderGdhSkill('cursor', 'run-game', version). Per-target path: .cursor/skills/gdh-run-game/SKILL.md.";
+}, {
+    readonly surfaceId: "cursor_rule";
+    readonly relativePath: ".cursor/rules/gdh-agent.mdc";
+    readonly class: "deterministic";
+    readonly notes: "Cursor rule file rendered by renderCursorRule() in packages/adapters/src/index.ts (line 555). Path constant CURSOR_RULE_RELATIVE_PATH (line 171) defines the workspace-relative location.";
+}, {
+    readonly surfaceId: "claude_onboard_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudeOnboardCommand() (packages/adapters/src/index.ts line 573); delegates to renderClaudeOnboardSkill. Per-target path under .claude/commands/gdh/ (legacy command-file location, retained for backwards compatibility).";
+}, {
+    readonly surfaceId: "claude_status_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudeStatusCommand() (packages/adapters/src/index.ts line 577); delegates to renderClaudeStatusSkill. Per-target path under .claude/commands/gdh/.";
+}, {
+    readonly surfaceId: "claude_scan_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudeScanCommand() (packages/adapters/src/index.ts line 581); delegates to renderClaudeScanSkill. Per-target path under .claude/commands/gdh/.";
+}, {
+    readonly surfaceId: "claude_migrate_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudeMigrateCommand() (packages/adapters/src/index.ts line 585); delegates to renderClaudeMigrateSkill. Per-target path under .claude/commands/gdh/.";
+}, {
+    readonly surfaceId: "claude_update_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudeUpdateCommand() (packages/adapters/src/index.ts line 589); delegates to renderClaudeUpdateSkill. Per-target path under .claude/commands/gdh/.";
+}, {
+    readonly surfaceId: "claude_check_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudeCheckCommand() (packages/adapters/src/index.ts line 593); delegates to renderClaudeCheckSkill. Per-target path under .claude/commands/gdh/.";
+}, {
+    readonly surfaceId: "claude_prepare_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudePrepareCommand() (packages/adapters/src/index.ts line 597); delegates to renderClaudePrepareSkill. Per-target path under .claude/commands/gdh/.";
+}, {
+    readonly surfaceId: "claude_run_game_command";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Legacy Claude command shim rendered by renderClaudeRunGameCommand() (packages/adapters/src/index.ts line 601); delegates to renderClaudeRunGameSkill. Per-target path under .claude/commands/gdh/.";
+}, {
+    readonly surfaceId: "mcp_config_entry";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Managed `gdh` MCP server entry rendered by renderManagedMcpConfig() (packages/adapters/src/index.ts line 3061). Per D-21 the entry GDH owns by marker is deterministic; the surrounding user MCP config (.mcp.json or .cursor/mcp.json) is project-native and not classified — GDH only operates on the entry it owns.";
+}, {
+    readonly surfaceId: "codex_project_mcp_section";
+    readonly relativePath: ".codex/config.toml";
+    readonly class: "deterministic";
+    readonly notes: "Managed `[mcp_servers.gdh]` section in .codex/config.toml rendered by renderManagedCodexProjectSection() (packages/adapters/src/index.ts line 3096) and stitched into the file via renderManagedCodexProjectConfig() (line 3106). Path constant CODEX_PROJECT_CONFIG_RELATIVE_PATH (line 231).";
+}, {
+    readonly surfaceId: "codex_authoring_hook_block";
+    readonly relativePath: ".codex/config.toml";
+    readonly class: "deterministic";
+    readonly notes: "Managed `# BEGIN GDH managed authoring hooks` block in .codex/config.toml rendered by renderManagedCodexAuthoringHookBlock() (packages/adapters/src/index.ts line 3193). Marker-bounded; deterministic per D-22.";
+}, {
+    readonly surfaceId: "authoring_hook";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Authoring validation hook rendered by renderGdhAuthoringHook() in packages/adapters/src/authoring-hook-render.ts (line 10). Per-agent paths: .claude/hooks/gdh-authoring-guard.js (CLAUDE_AUTHORING_HOOK_RELATIVE_PATH) and .codex/hooks/gdh-authoring-guard.js (CODEX_AUTHORING_HOOK_RELATIVE_PATH).";
+}, {
+    readonly surfaceId: "claude_update_hook";
+    readonly relativePath: ".claude/hooks/gdh-check-update.js";
+    readonly class: "deterministic";
+    readonly notes: "Claude SessionStart parent hook rendered by renderClaudeCheckUpdateHook() in packages/adapters/src/claude-update-hook-render.ts. Path constant CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH.";
+}, {
+    readonly surfaceId: "claude_update_worker";
+    readonly relativePath: ".claude/hooks/gdh-check-update-worker.js";
+    readonly class: "deterministic";
+    readonly notes: "Claude background update-check worker rendered by the renderer in packages/adapters/src/claude-update-worker-render.ts. Path constant CLAUDE_CHECK_UPDATE_WORKER_RELATIVE_PATH.";
+}, {
+    readonly surfaceId: "claude_statusline";
+    readonly relativePath: ".claude/hooks/gdh-statusline.js";
+    readonly class: "deterministic";
+    readonly notes: "Optional Claude statusline script rendered by the renderer in packages/adapters/src/claude-statusline-render.ts. Path constant CLAUDE_STATUSLINE_RELATIVE_PATH. GDH bakes the file but does not auto-register it in .claude/settings.json (single-slot conflict); registration is opt-in.";
+}, {
+    readonly surfaceId: "agents_md_managed_block";
+    readonly relativePath: "AGENTS.md";
+    readonly class: "deterministic";
+    readonly notes: "Managed BEGIN/END-marker block in AGENTS.md rendered by renderManagedAgentContractBlock() (packages/docs/src/agent-contract.ts line 24) and stitched in by upsertManagedAgentContract() (line 70). Path constant AGENT_CONTRACT_RELATIVE_PATH (line 12). Per D-18 the managed block specifically is deterministic; surrounding user content in AGENTS.md is project-native and not classified — GDH operates only on the marker-bounded region.";
+}, {
+    readonly surfaceId: "guidance_unit_set";
+    readonly relativePath: null;
+    readonly class: "deterministic";
+    readonly notes: "Managed guidance unit files (multiple) under docs/agent/ rendered by createDefaultGuidanceUnits() in packages/docs/src/guidance.ts (line 27). Each unit is GDH-rendered with metadata + body; relativePath is null because the surface emits multiple files. Class deterministic per D-19 (Session 9 nested-monorepo migration is the canonical drift mode).";
+}, {
+    readonly surfaceId: "guidance_index";
+    readonly relativePath: "docs/agent/README.md";
+    readonly class: "deterministic";
+    readonly notes: "Managed guidance index file rendered by createDefaultGuidanceIndex() in packages/docs/src/guidance.ts (line 391). Path constant GUIDANCE_INDEX_RELATIVE_PATH (line 19). Class deterministic per D-19.";
+}, {
+    readonly surfaceId: "gdh_project_yaml";
+    readonly relativePath: ".gdh/project.yaml";
+    readonly class: "user-data";
+    readonly notes: "Schema is GDH-shape; field values (especially gdh_version pin) are user-installed truth. This file defines the schema being migrated and is the canonical source of 'current schema version' when computing the migration plan. Per D-14.";
+}, {
+    readonly surfaceId: "gdh_rules_yaml";
+    readonly relativePath: ".gdh/rules.yaml";
+    readonly class: "user-data";
+    readonly notes: "Default boilerplate from a prior version is byte-equal-matched against registry-stored prior-version default and auto-migrated; non-byte-equal content is treated as user-customized and routes through the conflict policy. Per D-15.";
+}, {
+    readonly surfaceId: "run_configuration_set";
+    readonly relativePath: null;
+    readonly class: "user-data";
+    readonly notes: "Multiple files under .gdh/run-configurations/ created via `gdh run-config`. User owns content; GDH owns shape; semantic schema changes route through subagent envelope. Per D-16.";
+}, {
+    readonly surfaceId: "verification_scenario_set";
+    readonly relativePath: null;
+    readonly class: "user-data";
+    readonly notes: "Multiple files under .gdh/verification-scenarios/ created via `gdh verification-scenario`. User owns content; GDH owns shape; semantic schema changes route through subagent envelope. Per D-16.";
+}, {
+    readonly surfaceId: "project_godot";
+    readonly relativePath: "project.godot";
+    readonly class: "project-native";
+    readonly notes: "Owned by the Godot project. Anything outside projectNativeAllowlist is rejected at audit-time. Adding an op requires a registry entry that declares it explicitly. Per D-17.";
+    readonly projectNativeAllowlist: readonly [{
+        readonly op: "edit_editor_plugins_array";
+        readonly summary: "Add or remove entries in the [editor_plugins] section.";
+    }, {
+        readonly op: "register_autoload";
+        readonly summary: "Register or unregister an autoload entry.";
+    }];
+}];
+/**
+ * Load-time guard used by renderer modules (Plan 70-05) to assert their
+ * surface is registered in the manifest under the expected class. Throws
+ * loudly on drift — module init aborts before any write can happen.
+ *
+ * Mirrors the throw-on-violation discipline of
+ * packages/core/src/release-span-update-contract.ts (lines 60-83).
+ */
+export declare function assertClassRegistered(surfaceId: string, expectedClass: GdhManagedSurfaceClass): void;
+//# sourceMappingURL=managed-surface-classes.d.ts.map

package/node_modules/@gdh/core/dist/migrations/managed-surface-classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-surface-classes.d.ts","sourceRoot":"","sources":["../../src/migrations/managed-surface-classes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,sBAAsB,GAC9B,eAAe,GACf,WAAW,GACX,gBAAgB,CAAC;AAErB,MAAM,WAAW,gCAAgC;IAC/C,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,gCAAgC,EAAE,CAAC;CAC/E;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiYmB,CAAC;AAE5D;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,sBAAsB,GACpC,IAAI,CAcN"}