govkit 0.5.0__py3-none-any.whl

cli/agents/claude-code/claude-md/backend-api.md

@@ -0,0 +1,206 @@
+# Governed AI Delivery — Claude Code Instructions
+
+These instructions are mandatory. Claude operates as a governed delivery system, not an open coding environment.
+
+Repository artifacts are the source of truth. Chat history is not.
+
+---
+
+## Operating Mode
+
+Claude operates aligned to:
+
+- Product specifications under `features/`
+- Architecture contracts under `docs/backend/architecture/`
+- Evaluation standards under `docs/backend/evaluation/`
+- Governance rules under `governance/`
+
+Before planning or generating code:
+
+- Read all files under `docs/backend/architecture/`
+- Read `docs/backend/evaluation/eval_criteria.md`
+- Apply architecture, testing, technology, and evaluation contracts as binding constraints
+- Confirm required feature artifacts exist
+
+If required inputs are missing, stop and ask.
+
+---
+
+## Mandatory Feature Structure
+
+Every feature must live under `features/<feature_name>` with these required artifacts:
+
+- `acceptance.feature`
+- `nfrs.md`
+- `eval_criteria.yaml`
+- `plan.md`
+- `architecture_preflight.md`
+
+Implementation must not begin unless all five artifacts exist.
+
+Before proceeding to Architecture Preflight or planning:
+
+- If `nfrs.md` contains TBD entries in any category, stop and request completion
+- If `acceptance.feature` is empty or missing scenarios, stop and request completion
+- If Gherkin tag coverage does not satisfy `docs/backend/architecture/GHERKIN_CONVENTIONS.md`, stop and request completion
+
+---
+
+## Feature Lifecycle (Mandatory Order — no steps may be skipped)
+
+1. Architecture Preflight → run `/architecture-preflight`
+2. ADR creation (if required by preflight)
+3. Plan finalization → run `/spec-planning`
+4. Evaluation Compliance Summary (must be in `plan.md`)
+5. Incremental implementation → guided by `/implementation-plan`
+6. Automated tests
+7. Static analysis and evaluation gates
+
+---
+
+## Planning Discipline
+
+Generate and maintain `features/<feature_name>/plan.md` based on `governance/backend/templates/plan.md`.
+
+The plan must:
+
+- Define explicit increments with deliverables and tests
+- Map Gherkin scenarios to BDD integration tests
+- Include an Evaluation Compliance Summary predicting FIRST and 7 Virtue scores
+- Reference ADRs and architecture contracts
+
+The Evaluation Compliance Summary must use the structured YAML prediction block from `governance/backend/templates/plan.md`. All score and evidence fields must be populated with a numeric value (0–5) and a one-sentence rationale. Null values are not permitted at plan finalization. If any average is below 4.0, revise the plan before writing any code.
+
+---
+
+## ADR Rules
+
+An ADR is required when:
+
+- A standard is extended, overridden, or bypassed
+- A new architectural pattern is introduced
+- A security or auth approach changes
+- A boundary rule or dependency direction changes
+- A shared schema, API contract, event definition, or data model is introduced or modified that will be consumed by other features, services, or agents
+
+ADRs live under `docs/backend/architecture/ADR/`, follow `docs/backend/architecture/ADR/TEMPLATE.md`, and must be Accepted before implementation proceeds.
+
+---
+
+## Project Documentation
+
+Your project's language- and framework-specific conventions and standards are documented in `docs/backend/architecture/`. Before implementing in each layer, read the corresponding document:
+
+| Layer | Document | Content |
+|---|---|---|
+| API / inbound adapter | `API_CONVENTIONS.md` | Routing style, request/response models, authentication, error mapping, testing |
+| Services / domain | `ARCH_CONTRACT.md` | Architecture model, layering, approved libraries, design principles |
+| Ports | `ARCH_CONTRACT.md` | Port interface guidelines and architecture patterns |
+| Adapters / infrastructure | `ARCH_CONTRACT.md` + `BOUNDARIES.md` | Integration patterns, layer boundaries, dependency rules |
+| Security / auth | `SECURITY_AUTH_PATTERNS.md` | Authentication model, token strategy, credential handling, RBAC |
+| Testing | `TESTING.md` | Test philosophy, FIRST principles, BDD approach, test structure |
+| Technology decisions | `TECH_STACK.md` | Approved frameworks, libraries, tools, and versions |
+
+These documents define your stack's specific approach. The architecture principles (hexagonal architecture, boundaries, evaluation) are universal; the implementation details are here.
+
+---
+
+## Implementation Rules
+
+- Implement one increment at a time
+- Respect all rules in `docs/backend/architecture/BOUNDARIES.md`
+- Follow Hexagonal Architecture (ports and adapters)
+- Use only approved frameworks from `docs/backend/architecture/TECH_STACK.md`
+- Use approved auth patterns from `docs/backend/architecture/SECURITY_AUTH_PATTERNS.md`
+- Follow API conventions from `docs/backend/architecture/API_CONVENTIONS.md`
+- Follow design principles from `docs/backend/architecture/DESIGN_PRINCIPLES.md`; use findings from approved tools as defined in `docs/backend/architecture/TECH_STACK.md` — blocking findings must be resolved before proceeding
+
+Layer-specific rules load automatically from `.claude/rules/` when editing files in each layer:
+
+- `api.md` — `**/api/**`
+- `services.md` — `**/services/**`
+- `ports.md` — `**/ports/**`
+- `adapters.md` — `**/adapters/**`
+- `security.md` — `**/security/**` and `**/auth/**`
+
+---
+
+## Evaluation Discipline
+
+Before implementation, read `docs/backend/evaluation/eval_criteria.md` and `features/<feature_name>/eval_criteria.yaml`. Confirm FIRST and 7 Virtue enforcement thresholds.
+
+Implementation must not proceed unless an Evaluation Compliance Summary exists in `plan.md` with predicted averages meeting required thresholds. CI evaluation gates are binding.
+
+---
+
+## Testing Requirements
+
+Each increment must include:
+
+- Unit tests compliant with FIRST principles
+- BDD integration tests derived from Gherkin scenarios
+- Contract tests when APIs, ports, or external integrations are affected
+
+Gherkin scenarios must follow `docs/backend/architecture/GHERKIN_CONVENTIONS.md`:
+
+- Every populated NFR category in `nfrs.md` must have at least one scenario tagged with the corresponding `@nfr-*` tag
+- Features producing shared artifacts must include at least one `@contract` scenario
+- Verify coverage during Architecture Preflight and plan finalization — stop if incomplete
+
+Undocumented Gherkin gaps must be noted in `plan.md`.
+
+---
+
+## Automatic Refactor Conditions
+
+Trigger refactor before proceeding if:
+
+- Duplicate logic detected
+- Structural complexity excessive
+- FIRST or 7 Virtue score below threshold
+- Test flakiness detected
+
+---
+
+## Architecture Preflight Triggers
+
+Architecture Preflight must be re-run (or updated) when:
+
+- Scope expands beyond what the current preflight covers
+- New external dependencies are introduced
+- Security or auth patterns change
+- Evaluation mode changes
+- An ADR trigger condition is met
+- A shared contract or producer relationship is introduced or modified
+
+If Preflight status is Blocked, implementation must not proceed.
+
+---
+
+## Output Expectations
+
+Every plan and implementation output must include:
+
+- Referenced standards (architecture contracts, eval criteria, ADRs)
+- ADR status (Accepted / pending / not required — with justification)
+- Architecture compliance confirmation
+- Test coverage summary
+- Evaluation impact summary
+
+If alignment is unclear, stop and ask.
+
+---
+
+## Commit Discipline
+
+- Complete one increment, then commit before starting the next
+- Each commit must be independently buildable and testable
+- Commit message references the increment: `feat(<feature>): increment N — <name>`
+- Do not combine multiple increments into a single commit
+- If an increment exceeds ~300 lines of production code, split it before committing
+
+---
+
+## Authority
+
+Architecture decisions belong to the Architect. Exceptions require an ADR and explicit approval. Claude follows standards — it does not invent them.

cli/agents/claude-code/claude-md/backend-cli.md

@@ -0,0 +1,206 @@
+# Governed AI Delivery — Claude Code Instructions
+
+These instructions are mandatory. Claude operates as a governed delivery system, not an open coding environment.
+
+Repository artifacts are the source of truth. Chat history is not.
+
+---
+
+## Operating Mode
+
+Claude operates aligned to:
+
+- Product specifications under `features/`
+- Architecture contracts under `docs/backend/architecture/`
+- Evaluation standards under `docs/backend/evaluation/`
+- Governance rules under `governance/`
+
+Before planning or generating code:
+
+- Read all files under `docs/backend/architecture/`
+- Read `docs/backend/evaluation/eval_criteria.md`
+- Apply architecture, testing, technology, and evaluation contracts as binding constraints
+- Confirm required feature artifacts exist
+
+If required inputs are missing, stop and ask.
+
+---
+
+## Mandatory Feature Structure
+
+Every feature must live under `features/<feature_name>` with these required artifacts:
+
+- `acceptance.feature`
+- `nfrs.md`
+- `eval_criteria.yaml`
+- `plan.md`
+- `architecture_preflight.md`
+
+Implementation must not begin unless all five artifacts exist.
+
+Before proceeding to Architecture Preflight or planning:
+
+- If `nfrs.md` contains TBD entries in any category, stop and request completion
+- If `acceptance.feature` is empty or missing scenarios, stop and request completion
+- If Gherkin tag coverage does not satisfy `docs/backend/architecture/GHERKIN_CONVENTIONS.md`, stop and request completion
+
+---
+
+## Feature Lifecycle (Mandatory Order — no steps may be skipped)
+
+1. Architecture Preflight → run `/architecture-preflight`
+2. ADR creation (if required by preflight)
+3. Plan finalization → run `/spec-planning`
+4. Evaluation Compliance Summary (must be in `plan.md`)
+5. Incremental implementation → guided by `/implementation-plan`
+6. Automated tests
+7. Static analysis and evaluation gates
+
+---
+
+## Planning Discipline
+
+Generate and maintain `features/<feature_name>/plan.md` based on `governance/backend/templates/plan.md`.
+
+The plan must:
+
+- Define explicit increments with deliverables and tests
+- Map Gherkin scenarios to BDD integration tests
+- Include an Evaluation Compliance Summary predicting FIRST and 7 Virtue scores
+- Reference ADRs and architecture contracts
+
+The Evaluation Compliance Summary must use the structured YAML prediction block from `governance/backend/templates/plan.md`. All score and evidence fields must be populated with a numeric value (0–5) and a one-sentence rationale. Null values are not permitted at plan finalization. If any average is below 4.0, revise the plan before writing any code.
+
+---
+
+## ADR Rules
+
+An ADR is required when:
+
+- A standard is extended, overridden, or bypassed
+- A new architectural pattern is introduced
+- A security or auth approach changes
+- A boundary rule or dependency direction changes
+- A shared schema, API contract, event definition, or data model is introduced or modified that will be consumed by other features, services, or agents
+
+ADRs live under `docs/backend/architecture/ADR/`, follow `docs/backend/architecture/ADR/TEMPLATE.md`, and must be Accepted before implementation proceeds.
+
+---
+
+## Project Documentation
+
+Your project's language- and framework-specific conventions and standards are documented in `docs/backend/architecture/`. Before implementing in each layer, read the corresponding document:
+
+| Layer | Document | Content |
+|---|---|---|
+| CLI / inbound adapter | `CLI_CONVENTIONS.md` | Command structure, argument handling, output formatting, exit codes, testing |
+| Services / domain | `ARCH_CONTRACT.md` | Architecture model, layering, approved libraries, design principles |
+| Ports | `ARCH_CONTRACT.md` | Port interface guidelines and architecture patterns |
+| Adapters / infrastructure | `ARCH_CONTRACT.md` + `BOUNDARIES.md` | Integration patterns, layer boundaries, dependency rules |
+| Security / auth | `SECURITY_AUTH_PATTERNS.md` | Authentication model, token strategy, credential handling, RBAC |
+| Testing | `TESTING.md` | Test philosophy, FIRST principles, BDD approach, test structure |
+| Technology decisions | `TECH_STACK.md` | Approved frameworks, libraries, tools, and versions |
+
+These documents define your stack's specific approach. The architecture principles (hexagonal architecture, boundaries, evaluation) are universal; the implementation details are here.
+
+---
+
+## Implementation Rules
+
+- Implement one increment at a time
+- Respect all rules in `docs/backend/architecture/BOUNDARIES.md`
+- Follow Hexagonal Architecture (ports and adapters)
+- Use only approved frameworks from `docs/backend/architecture/TECH_STACK.md`
+- Use approved auth patterns from `docs/backend/architecture/SECURITY_AUTH_PATTERNS.md`
+- Follow CLI conventions from `docs/backend/architecture/CLI_CONVENTIONS.md`
+- Follow design principles from `docs/backend/architecture/DESIGN_PRINCIPLES.md`; use findings from approved tools as defined in `docs/backend/architecture/TECH_STACK.md` — blocking findings must be resolved before proceeding
+
+Layer-specific rules load automatically from `.claude/rules/` when editing files in each layer:
+
+- `cli.md` — `**/cli/**` and `**/commands/**`
+- `services.md` — `**/services/**`
+- `ports.md` — `**/ports/**`
+- `adapters.md` — `**/adapters/**`
+- `security.md` — `**/security/**` and `**/auth/**`
+
+---
+
+## Evaluation Discipline
+
+Before implementation, read `docs/backend/evaluation/eval_criteria.md` and `features/<feature_name>/eval_criteria.yaml`. Confirm FIRST and 7 Virtue enforcement thresholds.
+
+Implementation must not proceed unless an Evaluation Compliance Summary exists in `plan.md` with predicted averages meeting required thresholds. CI evaluation gates are binding.
+
+---
+
+## Testing Requirements
+
+Each increment must include:
+
+- Unit tests compliant with FIRST principles
+- BDD integration tests derived from Gherkin scenarios
+- Contract tests when APIs, ports, or external integrations are affected
+
+Gherkin scenarios must follow `docs/backend/architecture/GHERKIN_CONVENTIONS.md`:
+
+- Every populated NFR category in `nfrs.md` must have at least one scenario tagged with the corresponding `@nfr-*` tag
+- Features producing shared artifacts must include at least one `@contract` scenario
+- Verify coverage during Architecture Preflight and plan finalization — stop if incomplete
+
+Undocumented Gherkin gaps must be noted in `plan.md`.
+
+---
+
+## Automatic Refactor Conditions
+
+Trigger refactor before proceeding if:
+
+- Duplicate logic detected
+- Structural complexity excessive
+- FIRST or 7 Virtue score below threshold
+- Test flakiness detected
+
+---
+
+## Architecture Preflight Triggers
+
+Architecture Preflight must be re-run (or updated) when:
+
+- Scope expands beyond what the current preflight covers
+- New external dependencies are introduced
+- Security or auth patterns change
+- Evaluation mode changes
+- An ADR trigger condition is met
+- A shared contract or producer relationship is introduced or modified
+
+If Preflight status is Blocked, implementation must not proceed.
+
+---
+
+## Output Expectations
+
+Every plan and implementation output must include:
+
+- Referenced standards (architecture contracts, eval criteria, ADRs)
+- ADR status (Accepted / pending / not required — with justification)
+- Architecture compliance confirmation
+- Test coverage summary
+- Evaluation impact summary
+
+If alignment is unclear, stop and ask.
+
+---
+
+## Commit Discipline
+
+- Complete one increment, then commit before starting the next
+- Each commit must be independently buildable and testable
+- Commit message references the increment: `feat(<feature>): increment N — <name>`
+- Do not combine multiple increments into a single commit
+- If an increment exceeds ~300 lines of production code, split it before committing
+
+---
+
+## Authority
+
+Architecture decisions belong to the Architect. Exceptions require an ADR and explicit approval. Claude follows standards — it does not invent them.

cli/agents/claude-code/claude-md/l3-backend-api.md

@@ -0,0 +1,141 @@
+# Spec-Driven Development — Claude Code Instructions
+
+These instructions are mandatory. Claude operates as a spec-driven delivery system.
+
+Repository artifacts are the source of truth. Chat history is not.
+
+---
+
+## Operating Mode
+
+Claude operates aligned to:
+
+- Product specifications under `features/`
+- Design principles under `docs/backend/architecture/DESIGN_PRINCIPLES.md`
+- Testing conventions under `docs/backend/architecture/TESTING.md`
+
+Before planning or generating code:
+
+- Read `docs/backend/architecture/DESIGN_PRINCIPLES.md`
+- Read `docs/backend/architecture/TESTING.md`
+- Confirm required feature artifacts exist
+
+If required inputs are missing, stop and ask.
+
+---
+
+## Mandatory Feature Structure
+
+Every feature must live under `features/<feature_name>` with these required artifacts:
+
+- `acceptance.feature`
+- `nfrs.md`
+- `plan.md`
+
+Implementation must not begin unless all three artifacts exist.
+
+Before proceeding to planning:
+
+- If `nfrs.md` contains TBD entries in any category, stop and request completion
+- If `acceptance.feature` is empty or missing scenarios, stop and request completion
+
+---
+
+## Feature Lifecycle (Mandatory Order — no steps may be skipped)
+
+1. Write acceptance criteria (`acceptance.feature`)
+2. Complete NFRs (`nfrs.md`)
+3. Plan finalization → run `/spec-planning`
+4. Implementation planning → run `/implementation-plan`
+5. Incremental implementation (test-first)
+6. Automated tests
+7. CI gates (lint, tests)
+
+---
+
+## Planning Discipline
+
+Generate and maintain `features/<feature_name>/plan.md` based on `governance/backend/templates/l3-plan.md`.
+
+The plan must:
+
+- Define explicit increments with deliverables and tests
+- Map Gherkin scenarios to integration tests
+- List tests before implementation in each increment
+
+---
+
+## Project Documentation
+
+Your project's language- and framework-specific conventions are documented in `docs/backend/architecture/`. When implementing:
+
+- **Architecture decisions:** Review `docs/backend/architecture/DESIGN_PRINCIPLES.md`
+- **Testing approach:** Review `docs/backend/architecture/TESTING.md`
+- **Framework and libraries:** Review `docs/backend/architecture/TECH_STACK.md`
+- **Boundaries and dependencies:** Review `docs/backend/architecture/BOUNDARIES.md`
+
+These documents define your stack's specific approach to the universal architecture principles (SOLID, DRY, YAGNI, KISS).
+
+---
+
+## Implementation Rules
+
+- Implement one increment at a time
+- Write tests before implementation code (test-first)
+- Follow design principles from `docs/backend/architecture/DESIGN_PRINCIPLES.md` (SOLID, DRY, YAGNI, KISS)
+- Follow testing conventions from `docs/backend/architecture/TESTING.md`
+
+Generic rules load automatically from `.claude/rules/`:
+
+- `test-first.md` — test-first development discipline
+- `spec-compliance.md` — feature artifact and Gherkin conventions
+
+---
+
+## Testing Requirements
+
+Each increment must include:
+
+- Unit tests written before implementation code
+- Integration tests derived from Gherkin scenarios
+
+Gherkin scenarios must follow conventions:
+
+- Every populated NFR category in `nfrs.md` must have at least one scenario tagged with the corresponding `@nfr-*` tag
+
+---
+
+## Automatic Refactor Conditions
+
+Trigger refactor before proceeding if:
+
+- Duplicate logic detected
+- Structural complexity excessive
+- Test flakiness detected
+
+---
+
+## Output Expectations
+
+Every plan and implementation output must include:
+
+- Referenced design principles
+- Test coverage summary
+
+If alignment is unclear, stop and ask.
+
+---
+
+## Commit Discipline
+
+- Complete one increment, then commit before starting the next
+- Each commit must be independently buildable and testable
+- Commit message references the increment: `feat(<feature>): increment N — <name>`
+- Do not combine multiple increments into a single commit
+- If an increment exceeds ~300 lines of production code, split it before committing
+
+---
+
+## Authority
+
+Architecture decisions belong to the team. Claude follows specifications — it does not invent them.

cli/agents/claude-code/claude-md/l3-backend-cli.md

@@ -0,0 +1,142 @@
+# Spec-Driven Development — Claude Code Instructions
+
+These instructions are mandatory. Claude operates as a spec-driven delivery system.
+
+Repository artifacts are the source of truth. Chat history is not.
+
+---
+
+## Operating Mode
+
+Claude operates aligned to:
+
+- Product specifications under `features/`
+- Design principles under `docs/backend/architecture/DESIGN_PRINCIPLES.md`
+- Testing conventions under `docs/backend/architecture/TESTING.md`
+
+Before planning or generating code:
+
+- Read `docs/backend/architecture/DESIGN_PRINCIPLES.md`
+- Read `docs/backend/architecture/TESTING.md`
+- Confirm required feature artifacts exist
+
+If required inputs are missing, stop and ask.
+
+---
+
+## Mandatory Feature Structure
+
+Every feature must live under `features/<feature_name>` with these required artifacts:
+
+- `acceptance.feature`
+- `nfrs.md`
+- `plan.md`
+
+Implementation must not begin unless all three artifacts exist.
+
+Before proceeding to planning:
+
+- If `nfrs.md` contains TBD entries in any category, stop and request completion
+- If `acceptance.feature` is empty or missing scenarios, stop and request completion
+
+---
+
+## Feature Lifecycle (Mandatory Order — no steps may be skipped)
+
+1. Write acceptance criteria (`acceptance.feature`)
+2. Complete NFRs (`nfrs.md`)
+3. Plan finalization → run `/spec-planning`
+4. Implementation planning → run `/implementation-plan`
+5. Incremental implementation (test-first)
+6. Automated tests
+7. CI gates (lint, tests)
+
+---
+
+## Planning Discipline
+
+Generate and maintain `features/<feature_name>/plan.md` based on `governance/backend/templates/l3-plan.md`.
+
+The plan must:
+
+- Define explicit increments with deliverables and tests
+- Map Gherkin scenarios to integration tests
+- List tests before implementation in each increment
+
+---
+
+## Project Documentation
+
+Your project's language- and framework-specific conventions are documented in `docs/backend/architecture/`. When implementing:
+
+- **Architecture decisions:** Review `docs/backend/architecture/DESIGN_PRINCIPLES.md`
+- **Testing approach:** Review `docs/backend/architecture/TESTING.md`
+- **Framework and libraries:** Review `docs/backend/architecture/TECH_STACK.md`
+- **CLI conventions:** Review `docs/backend/architecture/CLI_CONVENTIONS.md`
+- **Boundaries and dependencies:** Review `docs/backend/architecture/BOUNDARIES.md`
+
+These documents define your stack's specific approach to the universal architecture principles (SOLID, DRY, YAGNI, KISS).
+
+---
+
+## Implementation Rules
+
+- Implement one increment at a time
+- Write tests before implementation code (test-first)
+- Follow design principles from `docs/backend/architecture/DESIGN_PRINCIPLES.md` (SOLID, DRY, YAGNI, KISS)
+- Follow testing conventions from `docs/backend/architecture/TESTING.md`
+
+Generic rules load automatically from `.claude/rules/`:
+
+- `test-first.md` — test-first development discipline
+- `spec-compliance.md` — feature artifact and Gherkin conventions
+
+---
+
+## Testing Requirements
+
+Each increment must include:
+
+- Unit tests written before implementation code
+- Integration tests derived from Gherkin scenarios
+
+Gherkin scenarios must follow conventions:
+
+- Every populated NFR category in `nfrs.md` must have at least one scenario tagged with the corresponding `@nfr-*` tag
+
+---
+
+## Automatic Refactor Conditions
+
+Trigger refactor before proceeding if:
+
+- Duplicate logic detected
+- Structural complexity excessive
+- Test flakiness detected
+
+---
+
+## Output Expectations
+
+Every plan and implementation output must include:
+
+- Referenced design principles
+- Test coverage summary
+
+If alignment is unclear, stop and ask.
+
+---
+
+## Commit Discipline
+
+- Complete one increment, then commit before starting the next
+- Each commit must be independently buildable and testable
+- Commit message references the increment: `feat(<feature>): increment N — <name>`
+- Do not combine multiple increments into a single commit
+- If an increment exceeds ~300 lines of production code, split it before committing
+
+---
+
+## Authority
+
+Architecture decisions belong to the team. Claude follows specifications — it does not invent them.