spec-kitty / spec-kitty/spec-kitty

Doctrine governance tiers: merge-time enforcement of component-type in merge_three_layers()

Open
#2,592 1 comment 0 reactions 0 assignees View on GitHub
doctrine enhancement priority:P2
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

## Context

Slice of epic #2216 (Doctrine governance tiers — AUTHORITATIVE charters + per-artefact `component-type` immutability). This is proposed breakdown item **2** in the epic body: "Merge-time enforcement ... (Depends on #1.)"

## Scope

In `merge_three_layers()` (`src/doctrine/drg/merge.py`), gate `overrides` / `enhances` / `remove` of a higher-tier node by that node's `component-type`, **only when the owning pack is `AUTHORITATIVE`**:

- `governed` → lower tier may `enhances` only; `overrides`/removal/deactivation are rejected.
- `locked` → all of `enhances`/`overrides`/removal/deactivation are rejected (hard-fail).
- `open` (or the pack is not `AUTHORITATIVE`) → unchanged, today's permitted-but-visible override semantics (WARNING + `node_override` conflict; kind-drift still hard-fails).

This slice enforces at merge-time only; it does not yet parse/thread the charter-level `AUTHORITATIVE` flag itself (see the sibling child for that) — assume the flag is available as an input to the merge gate.

## Acceptance

- [ ] `merge_three_layers()` hard-fails a lower-tier `overrides`/remove against a `locked` higher-tier node from an `AUTHORITATIVE` pack
- [ ] `merge_three_layers()` hard-fails a lower-tier `overrides`/remove against a `governed` higher-tier node from an `AUTHORITATIVE` pack, but permits `enhances`
- [ ] `open` component-type (or non-`AUTHORITATIVE` owning pack) preserves today's permitted-but-visible behavior exactly (no regression)
- [ ] Kind-drift hard-fail behavior is unchanged

Parent: #2216

Contributor guide

Open the contributing guide

Research direction

Read src/doctrine/drg/merge.py and merge_three_layers(), then trace how overrides, enhances, remove, component-type, and authoritative ownership reach the merge gate. Compare the existing WARNING/node_override and kind-drift behavior, including the dependency on #1. Done means the locked, governed, open, and non-AUTHORITATIVE acceptance cases pass without changing kind-drift handling.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.