diff --git a/extensions/catalog.json b/extensions/catalog.json index 6f2c8aac1a..9438facbf6 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -144,7 +144,7 @@ "repository-governance": { "name": "Repository Governance", "id": "repository-governance", - "version": "3.0.0", + "version": "3.0.1", "description": "Generate project-governance projections from Spec Kit metadata", "author": "bigben", "repository": "https://github.com/bigsmartben/spec-kit-agent-governance", diff --git a/extensions/repository-governance/CHANGELOG.md b/extensions/repository-governance/CHANGELOG.md index d8c503cb7f..e51c8cc2d6 100644 --- a/extensions/repository-governance/CHANGELOG.md +++ b/extensions/repository-governance/CHANGELOG.md @@ -4,6 +4,7 @@ ### Changed +- Restructure generated projections into Copilot-like repository-wide, SSOT routing, path/task scope, and agent harness instruction layers while preserving the single active-target write surface. - Merge Toolchain SSOT coverage into Engineering SSOT to remove overlapping vertical ownership. - Remove the cache/managed-section model; generation now overwrites the active agent platform target from the current repository scan. - Make generated projections subordinate to vertical SSOT documents and source-backed repository facts on substantive conflicts. diff --git a/extensions/repository-governance/README.md b/extensions/repository-governance/README.md index 0c750f1656..667642caa3 100644 --- a/extensions/repository-governance/README.md +++ b/extensions/repository-governance/README.md @@ -12,13 +12,15 @@ Generate project-governance projections for the active Spec Kit agent platform t - Generate the resolved active agent platform target when missing. - Update existing active target project-governance projections. - Distill detected repository areas into action rules. -- Capture repository facts as vertical SSOT evidence. +- Capture repository facts as vertical SSOT evidence and routing input. +- Structure generated instructions with Copilot-like repository-wide, path-scope, and agent-harness layers. - Project agent platform adapter rules from Spec Kit integration metadata. - Build a scenario capability index for repository-local skills and MCP-backed external tool evidence. - Analyze repository areas to depth 2 only. - Include hidden and cache directories in repository area governance. - Enforce one primary responsibility per directory. - Overwrite the active agent platform target on generation. +- Do not generate Copilot `.github/instructions/*.instructions.md` companion files. - Generate repository evidence from the current repository state on every run. - Review only the active agent platform target. - Remove legacy managed sections only from non-active context files enumerated by `CONTEXT_FILES`. @@ -26,7 +28,7 @@ Generate project-governance projections for the active Spec Kit agent platform t ## Install ```bash -specify extension add repository-governance --from https://github.com/bigsmartben/spec-kit-agent-governance/archive/refs/tags/v3.0.0.zip +specify extension add repository-governance --from https://github.com/bigsmartben/spec-kit-agent-governance/archive/refs/tags/v3.0.1.zip ``` Local development: @@ -68,6 +70,14 @@ uv run python tools/build_repository_governance_zip.py - Directory Structure SSOT evidence from repository areas scanned to depth 2. - Agent Harness SSOT evidence from active agent context files, Spec Kit metadata, repository-local skills, and MCP config candidates. +## Instruction Layers + +- Repository-wide instructions summarize authority, active-target scope, write boundaries, validation commands, and handoff expectations. +- SSOT routing maps task types and path families to Architecture, Engineering, Code Style, Directory Structure, and Agent Harness SSOT entries. +- Path and task scope rules keep generated guidance deterministic without expanding the write surface. +- Agent harness instructions cover adapter behavior, repository-local skills, MCP discovery, external tools, permissions, and failure handling. +- Copilot's instruction model is a structural reference only; this extension still emits one active target file. + ## Evidence Coverage - Repository fact evidence from README files, project docs, repository policy files, feature specs, source/test paths, and runtime/build configuration. diff --git a/extensions/repository-governance/commands/speckit.repository-governance.generate.md b/extensions/repository-governance/commands/speckit.repository-governance.generate.md index 4c55897e99..8e201afc2c 100644 --- a/extensions/repository-governance/commands/speckit.repository-governance.generate.md +++ b/extensions/repository-governance/commands/speckit.repository-governance.generate.md @@ -12,6 +12,7 @@ $ARGUMENTS - Active agent platform target. - Generated `PROJECT GOVERNANCE` projection file. +- Copilot-like instruction layers inside the single active target. ## Procedure @@ -21,10 +22,15 @@ $ARGUMENTS - `.specify/integration.json` `default_integration` or `integration` - default context target from `CONTEXT_FILES` 3. Generate or overwrite the active agent platform target. -4. Distill detected repository areas into action rules. +4. Reference the Copilot custom-instructions model for projection structure, but emit only the active agent platform target. + - repository-wide instructions + - path and task scope routing + - agent harness guidance + - no `.github/instructions/*.instructions.md` companion files +5. Distill detected repository areas into action rules. - depth: 2 - include hidden and cache directories -5. Capture repository facts from the current repository state as vertical SSOT evidence. +6. Capture repository facts from the current repository state as vertical SSOT evidence and SSOT routing input. - Architecture evidence - Engineering evidence - Code Style evidence @@ -34,15 +40,21 @@ $ARGUMENTS - extension assets, command/template governance contracts, manifests, lockfiles, task runners, build config, and runtime config - feature specs, API contracts, source paths, and test paths - development commands from package scripts or Python/uv test conventions -6. Resolve the Spec Kit Agent Adapter for the active integration. +7. Resolve deterministic SSOT routing rules by task type and path family. + - Architecture SSOT for source, route, API, runtime, infra, dependency-boundary, and architecture decision work + - Engineering SSOT for build, release, CI, manifest, lockfile, command, template, package, and runtime configuration work + - Code Style SSOT for formatting, linting, typing, testing, logging, comments, naming, and error-handling work + - Directory Structure SSOT for new files, moved files, generated assets, and directory responsibility work + - Agent Harness SSOT for agent instructions, permissions, MCP, external tools, skills, validation, and failure handling +8. Resolve the Spec Kit Agent Adapter for the active integration. - active agent platform target - repository-local skill discovery behavior - MCP runtime discovery behavior - repository MCP config candidates as evidence only -7. Project the scenario capability index. +9. Project the scenario capability index. - repository-local skill capabilities from `SKILL.md` name, description, trigger, and source path - MCP-backed external tool capability with runtime enumeration before use -8. Run: +10. Run: ```bash uv run python .specify/extensions/repository-governance/scripts/generate_repository_governance.py diff --git a/extensions/repository-governance/extension.yml b/extensions/repository-governance/extension.yml index b93cc329c4..6c281de79b 100644 --- a/extensions/repository-governance/extension.yml +++ b/extensions/repository-governance/extension.yml @@ -3,7 +3,7 @@ schema_version: "1.0" extension: id: repository-governance name: "Repository Governance" - version: "3.0.0" + version: "3.0.1" description: "Generate project-governance projections from Spec Kit metadata" author: "bigben" repository: "https://github.com/bigsmartben/spec-kit-agent-governance" diff --git a/extensions/repository-governance/scripts/generate_repository_governance.py b/extensions/repository-governance/scripts/generate_repository_governance.py index 710735f594..ca58dece47 100755 --- a/extensions/repository-governance/scripts/generate_repository_governance.py +++ b/extensions/repository-governance/scripts/generate_repository_governance.py @@ -608,64 +608,60 @@ def render_projection(root: Path, target: Path, state: dict[str, Any], init_opti f"- Active integration: {default_key}", "- Projection source: current repository scan.", "", - "## Scope", - "- Project-governance projection for the active agent platform target", - "- Review and report only the active agent platform target", - "- Legacy managed-section cleanup limited to non-active context files enumerated by `CONTEXT_FILES`", - "- Spec Kit extension routing and target resolution", - "- top-level SSOT registry and routing", - "- vertical SSOT discovery and read order", - "- missing SSOT handling from repository evidence", - "- conflict priority and handoff requirements", - "- architecture methodology: owned by Architecture SSOT", + "## Repository-Wide Instructions", + f"- {style_lead(style)}", + "- Generate and review only the resolved active agent platform target.", + "- Use the Copilot instruction model for layering only; do not emit Copilot path-specific companion files.", + "- Keep instructions short, self-contained, and free of conflicting rules.", + "- Project-governance projection for the active agent platform target.", + "- Legacy managed-section cleanup limited to non-active context files enumerated by `CONTEXT_FILES`.", + "- architecture methodology: owned by Architecture SSOT.", "", - "## Vertical SSOT Registry", - *vertical_ssot_registry_default(), - "", - "## Context", + "### Context", f"- Installed integrations: {', '.join(installed) if installed else 'none'}", f"- Skills: {', '.join(scan_skills(root)) or 'none'}", f"- MCP configs: {', '.join(scan_mcp_configs(root)) or 'none'}", f"- Extensions config: .specify/extensions.yml ({extensions_status(root)})", "", - "## Agent Platform Adapter", - *agent_adapter_lines(root, target, default_key), + "### Authority", + *authority_default(), "", - "## Capability Index", - *capability_index_lines(root), + "## SSOT Routing", + *vertical_ssot_registry_default(), + "", + *vertical_ssot_routing_lines(root, state, init_options), + "", + "### Missing SSOT Handling", + *missing_ssot_handling_default(), "", "## Repository Evidence", *repository_evidence_lines(root, state, init_options), "", - "## Vertical SSOT Evidence", - *vertical_ssot_evidence_lines(root, state, init_options), + "## Path And Task Scope Rules", + *task_scope_rules_default(), "", - "## Repository Areas", + "### Repository Areas", *repository_area_lines(root), "", - "## Directory Governance", + "### Directory Governance", *directory_governance_default(), "", - "## Development Commands", - *development_command_lines(root), + "## Agent Harness", + *agent_adapter_lines(root, target, default_key), "", - "## Missing SSOT Handling", - *missing_ssot_handling_default(), + *capability_index_lines(root), "", - "## Authority", - *authority_default(), + *mcp_default(style), + "", + *skill_default(style), "", - "## Repository Workflow", *repository_workflow_default(), "", "## Write Boundaries", *write_boundary_default(style), "", - "## MCP And External Tools", - *mcp_default(style), - "", - "## Skills", - *skill_default(style), + "## Development Commands", + *development_command_lines(root), "", "## Handoff", *handoff_default(style), @@ -719,6 +715,17 @@ def directory_governance_default() -> list[str]: ] +def task_scope_rules_default() -> list[str]: + return [ + "- Source, API, route, runtime, infra, or dependency-boundary changes: read Architecture SSOT before planning edits.", + "- Build, release, CI, manifest, lockfile, command, template, or runtime configuration changes: read Engineering SSOT before edits.", + "- Formatting, linting, typing, testing, logging, comments, naming, or error-handling changes: read Code Style SSOT before edits.", + "- New files, moved files, generated assets, or directory responsibility changes: read Directory Structure SSOT before edits.", + "- Agent instructions, permissions, MCP, external tools, skills, validation, or failure-handling changes: read Agent Harness SSOT before edits.", + "- If multiple rules match, read every matched SSOT and apply the highest authority non-conflicting rule.", + ] + + def development_commands_default() -> list[str]: return ["- none recorded"] @@ -733,6 +740,22 @@ def vertical_ssot_registry_default() -> list[str]: ] +def vertical_ssot_routing_lines(root: Path, state: dict[str, Any], init_options: dict[str, Any]) -> list[str]: + evidence = vertical_ssot_evidence_lines(root, state, init_options) + return [ + "- Architecture SSOT route: use for source roots, route files, API contracts, runtime constraints, deployment assumptions, and architecture decisions.", + evidence[0], + "- Engineering SSOT route: use for branch, version, release, CI/CD, command entrypoints, manifests, lockfiles, build config, runtime config, and extension packaging.", + evidence[1], + "- Code Style SSOT route: use for naming, formatting, comments, error handling, logging, tests, linting, typing, and quality standards.", + evidence[2], + "- Directory Structure SSOT route: use for directory layout, file placement, module organization, configuration locations, and generated artifact placement.", + evidence[3], + "- Agent Harness SSOT route: use for agent task boundaries, tool usage, permissions, audit, validation, failure handling, skills, and MCP config candidates.", + evidence[4], + ] + + def missing_ssot_handling_default() -> list[str]: return [ "- If a vertical SSOT is missing or incomplete, infer temporary guidance from current repository evidence.", @@ -758,11 +781,11 @@ def authority_default() -> list[str]: def repository_workflow_default() -> list[str]: return [ - "- Classify task type before changing files.", - "- Route task to relevant vertical SSOT entries.", - "- Read: Repository Evidence", - "- Run: Development Commands", - "- Scope: active task only", + "- Classify task type and path family before changing files.", + "- Read every SSOT route matched by Path And Task Scope Rules.", + "- Use Repository Evidence as source-backed facts, not as higher authority than explicit SSOT.", + "- Run Development Commands that match the changed surface.", + "- Scope: active task only.", "- Preserve: user-authored edits.", "- Protected files: implementation paths, CI configuration, MCP configuration, secrets, permissions, tool settings, and arbitrary repository paths outside the resolved write surface.", "- Protected-file writes: explicit user request, named matching contract or regression test, and passing validation commands.", diff --git a/extensions/repository-governance/templates/repository-governance-template.md b/extensions/repository-governance/templates/repository-governance-template.md index 0a85a01990..ded767bdb0 100644 --- a/extensions/repository-governance/templates/repository-governance-template.md +++ b/extensions/repository-governance/templates/repository-governance-template.md @@ -9,25 +9,16 @@ Sync Impact Report - active agent platform project-governance projection - generated active agent platform target file -## Scope +## Repository-Wide Instructions -- Project Governance Projection Framework -- Spec Kit extension routing for supported agent platforms -- top-level SSOT registry and routing -- vertical SSOT discovery and read order -- missing SSOT handling from repository evidence -- conflict priority and handoff requirements -- architecture methodology: owned by Architecture SSOT - -## Vertical SSOT Registry - -- Architecture SSOT: owns architecture boundaries, interfaces, dependencies, runtime constraints, deployment assumptions, and scenario-level architecture decisions. -- Engineering SSOT: owns branch, version, release, CI/CD, collaboration process, standard tools, command entrypoints, configuration templates, and execution constraints. -- Code Style SSOT: owns naming, formatting, comments, error handling, logging, tests, and quality standards. -- Directory Structure SSOT: owns directory layout, file placement, module organization, and configuration locations. -- Agent Harness SSOT: owns agent task boundaries, tool usage, permissions, audit, validation, and failure handling. +- Framework: Project Governance Projection Framework. +- Generate and review only the resolved active agent platform target. +- Use the Copilot instruction model for layering only; do not emit Copilot path-specific companion files. +- Keep instructions short, self-contained, and free of conflicting rules. +- Legacy managed-section cleanup: non-active context files enumerated by `CONTEXT_FILES`. +- architecture methodology: owned by Architecture SSOT. -## Authority +### Authority 1. Current user instruction 2. Safety and permission constraints @@ -40,35 +31,41 @@ Sync Impact Report - Active projection is generated routing guidance and is subordinate to explicit vertical SSOT documents or source-backed repository facts on substantive conflicts. -## Repository Workflow +## SSOT Routing -- Classify task type before changing files. -- Route task to relevant vertical SSOT entries. -- Read: Repository Evidence -- Run: Development Commands -- Scope: active task only -- Preserve: user-authored edits -- Protected files: implementation paths, CI configuration, MCP configuration, secrets, permissions, tool settings, and arbitrary repository paths outside the resolved write surface -- Protected-file writes: explicit user request, named matching contract or regression test, and passing validation commands -- External writes: authorized target and action only -- Handoff: changed files, commands, validation, risks. +- Architecture SSOT: owns architecture boundaries, interfaces, dependencies, runtime constraints, deployment assumptions, and scenario-level architecture decisions. +- Engineering SSOT: owns branch, version, release, CI/CD, collaboration process, standard tools, command entrypoints, configuration templates, and execution constraints. +- Code Style SSOT: owns naming, formatting, comments, error handling, logging, tests, and quality standards. +- Directory Structure SSOT: owns directory layout, file placement, module organization, and configuration locations. +- Agent Harness SSOT: owns agent task boundaries, tool usage, permissions, audit, validation, and failure handling. +- Architecture evidence: none detected +- Engineering evidence: none detected +- Code Style evidence: none detected +- Directory Structure evidence: none detected +- Agent Harness evidence: none detected -## Missing SSOT Handling +### Missing SSOT Handling - If a vertical SSOT is missing or incomplete, infer temporary guidance from current repository evidence. - Mark inferred guidance as pending SSOT solidification. - Do not present inferred guidance as an approved repository rule. - Do not let inference override explicit SSOT content. -## Vertical SSOT Evidence +## Repository Evidence -- Architecture evidence: none detected -- Engineering evidence: none detected -- Code Style evidence: none detected -- Directory Structure evidence: none detected -- Agent Harness evidence: none detected +- Repository facts are descriptive source-backed evidence. +- Repository facts do not override explicit vertical SSOT content. + +## Path And Task Scope Rules + +- Source, API, route, runtime, infra, or dependency-boundary changes: read Architecture SSOT before planning edits. +- Build, release, CI, manifest, lockfile, command, template, or runtime configuration changes: read Engineering SSOT before edits. +- Formatting, linting, typing, testing, logging, comments, naming, or error-handling changes: read Code Style SSOT before edits. +- New files, moved files, generated assets, or directory responsibility changes: read Directory Structure SSOT before edits. +- Agent instructions, permissions, MCP, external tools, skills, validation, or failure-handling changes: read Agent Harness SSOT before edits. +- If multiple rules match, read every matched SSOT and apply the highest authority non-conflicting rule. -## Directory Governance +### Directory Governance - Responsibility: one primary purpose per directory. - Depth: 2. @@ -76,43 +73,35 @@ Sync Impact Report - Mixed concerns: follow existing repo convention or split responsibility. - Change impact: review linked code, tests, docs, config/env, data, assets, generated files, and tool outputs; update only when in scope and authorized. -## Write Boundaries - -- Scope: active task only -- Active agent platform target: generated output, overwritten on generation. -- Legacy managed-section cleanup: non-active context files enumerated by `CONTEXT_FILES`. -- Protected files: implementation paths, CI configuration, MCP configuration, secrets, permissions, tool settings, and arbitrary repository paths outside the resolved write surface -- Protected-file writes: explicit user request, named matching contract or regression test, and passing validation commands - -## Agent Platform Adapter +## Agent Harness - Repository Capability: abstract repository-local skill and MCP evidence into scenario capabilities. - Spec Kit Agent Adapter: map integration metadata to the active agent platform target and supported discovery behavior. - Platform Projection: emit only the rules the active agent platform target can safely apply. - -## Capability Index - - Repository-local skills: use when the task matches a declared skill name, description, or trigger. - MCP-backed external tools: use when the task needs external tool or resource access; enumerate runtime tools before use. - Repository config candidates are evidence only unless the active adapter supports them. - -## Skill Contract - - Repository-local skill specs should declare name, description or trigger, allowed read paths, allowed write paths, forbidden paths, outputs, and validation command. - Read matching `SKILL.md` files before planning or editing. +- MCP default: read-only. +- MCP mutation: explicit user intent with target, action, and expected effect. +- Secrets: never log, never write. + +## Write Boundaries + +- Scope: active task only. +- Active agent platform target: generated output, overwritten on generation. +- Legacy managed-section cleanup: non-active context files enumerated by `CONTEXT_FILES`. +- Protected files: implementation paths, CI configuration, MCP configuration, secrets, permissions, tool settings, and arbitrary repository paths outside the resolved write surface. +- Protected-file writes: explicit user request, named matching contract or regression test, and passing validation commands. -## MCP Policy +## Development Commands -- Default: read-only -- Mutation: explicit user intent with target, action, and expected effect. -- Runtime discovery: enumerate available servers, resources, and tools before use. -- Config candidates: evidence only, not proof of active tools. -- External writes: target, action, result -- Secrets: never log, never write +- none recorded -## Validation +## Handoff - changed files - commands run -- tests/validation result +- validation result - unresolved risks