ergane-cli 0.6.0__tar.gz → 0.7.0__tar.gz

ergane_cli-0.7.0/.agents/skills/refine-spec/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: "refine-spec"
+description: "Reconcile a Spec Kit trio with current source, tests, accepted decisions and capability evidence, then emit one bounded Refinement Record and a real validator report. Stops at review boundaries; it does not implement, transition readiness, answer escalations, or dispatch."
+compatibility: "Requires the ergane CLI and an operator-declared target repository plus specs root"
+metadata:
+  author: "operator session, 2026-09-21"
+  status: "canonical refinement review procedure"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Refine a specification
+
+## Establish the declared roots
+
+Read all three: `spec.md`, `plan.md`, and `tasks.md`. Before evidence work,
+resolve the target declaration, not a checkout guess:
+
+1. Read `ergane.yaml` in the operator-declared target repository.
+2. Read `factory.yaml` in the same target when it is the runtime/gate
+   declaration. `ergane.yaml` is the manifest name in new text; honor the
+   resolver's legacy `factory.yaml` compatibility when that is what the target
+   provides.
+3. Set `TARGET_REPO` and `SPECS_ROOT` explicitly. Never infer either from the
+   current working directory, checked-out branch, or inherited environment.
+
+## Reconcile current evidence
+
+Read the relevant current behavior, current tests, domain vocabulary, accepted
+decision sources, and task slices. A factual answer is traceable to a current
+file, command output, or landed decision. An unresolved product choice is
+different: do not infer it from history, remembered preferences, or authority.
+Expose it as a concrete question in `open_questions`, and let the validator
+block readiness.
+
+Recall available cross-session memory. Write every applicable lesson into the
+plan as a named plan trap, with its mechanism and the check that prevents a
+repeat. Do not turn a lesson into approval, implementation, or dispatch.
+
+## Write tests and preserved behavior
+
+For every story, list concrete test files and assertions. An existing test
+preserved by the story must state the invariant it still proves. A replacement
+must state the replacement assertion and cite a nonempty accepted decision.
+A new test pairs with `add`; an existing test pairs with `preserve` or
+`replace`. Never delete a test merely because it conflicts with a proposed
+behavior. Preserve quality and the applicable selector, renderer, lifecycle,
+timeout, credential-exclusion, and no-residue checks. If a gate timed out,
+preserve both the earlier failed assertions and the timeout fact.
+
+## Separate checks by boundary
+
+The record separates development, handoff, independent verification, and
+release qualification:
+
+- `checks.development` contains focused commands useful while editing.
+- `checks.handoff` is the literal `declared_gates`; no development subset is
+  the handoff boundary.
+- `checks.independent` is the literal `declared_pipeline`; no local run is the
+  independent boundary.
+- `checks.release` names the applicable release requirements and evidence
+  owner. Selector/renderer/lifecycle checks remain in release if they apply.
+
+A green run is evidence, not the verdict. Rerun a relevant check after the
+code, tests, spec, plan, tasks, or skill changes or after a failure.
+
+## Derive ownership from the actual task text
+
+Use actual task text, not a paraphrase, when classifying writes. Inspect the
+actual derived graph, including inferred edges. For a shared write, use the
+existing merge edge or declare the matching ownership; do not remove a path
+from tasks to hide contention. For append-only decision logs, name one
+integration writer, preserve landed entries byte-for-byte, and compare candidate
+epics in the release DAG: an intra-epic graph says nothing about another epic's
+writers. Cross-spec concurrency is advisory only.
+
+## Use capability evidence honestly
+
+Keep declared, available, and executed capabilities distinct. Declared skill
+metadata, filesystem availability, a fixture replay, and observed client
+follow-through are not the same fact. Use the capability table in
+`references/capability-evidence.md`; do not claim execution that did not occur.
+
+Read one unchanged version per working context. Refresh the read when skill
+changes, a newer version appears, or the client loses that context.
+
+## Complete the review
+
+Fill the format in `references/review-record.md`, then run:
+
+```bash
+uv run ergane spec validate "$SPEC_DIR" \
+  --target-repo "$TARGET_REPO" \
+  --specs-root "$SPECS_ROOT" \
+  --json
+```
+
+Do not execute review command strings from the record. End with a review record
+plus the exact validator report. Preserve missing-target, missing-corpus,
+legacy-absence, and skipped states; exit status alone is not release readiness.
+
+## Authority boundary
+
+This skill reviews; it does not implement, transition readiness, or answer
+escalations. It does not grant implementation, readiness, or operational
+authority. It does not dispatch an attempt. It adds no approval for already
+authorized refinement.

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/accepted-replacement/plan.md

@@ -0,0 +1,30 @@
+# Plan
+
+## Refinement Record
+
+```yaml
+version: 1
+reviewed_revision: HEAD
+stories:
+  US1:
+    tests:
+      - path: tests/test_example.py
+        status: existing
+        disposition: replace
+        assertion: the replacement behavior is asserted
+        decision: spec.md:FR-001
+    preserved_behavior:
+      - the prior decision citation and decision identity are preserved
+    checks:
+      development:
+        - uv run pytest tests/test_example.py
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes:
+      - factory/behavior.py
+      - tests/test_example.py
+    no_write_reason: ""
+    shared_writes: []
+    open_questions: []
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/accepted-replacement/spec.md

@@ -0,0 +1,25 @@
+---
+state: draft
+---
+
+# Feature Specification: Accepted replacement fixture
+
+## Requirements *(mandatory)*
+
+- **FR-001**: The accepted behavior MUST replace the current example.
+
+### User Story 1 - Accepted replacement (Priority: P1)
+
+As the operator, I want the accepted behavior to replace the current example.
+
+**Acceptance Scenarios**:
+
+1. **Given** the accepted decision, **When** the example runs, **Then** it asserts the replacement behavior.
+
+## Work Graph
+
+```yaml
+US1:
+  depends_on: []
+  implements: [FR-001]
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/accepted-replacement/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+## Phase 1: User Story 1
+
+- [ ] T001 [US1-S1] Replace the existing assertion in `tests/test_example.py` for `factory/behavior.py`.

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/independent-files/plan.md

@@ -0,0 +1,45 @@
+# Plan
+
+## Refinement Record
+
+```yaml
+version: 1
+reviewed_revision: HEAD
+stories:
+  US1:
+    tests:
+      - path: tests/test_first.py
+        status: existing
+        disposition: preserve
+        assertion: the first bounded behavior remains covered
+        decision: spec.md:FR-001
+    preserved_behavior:
+      - the first behavior remains deterministic
+    checks:
+      development: ['uv run pytest tests/test_first.py']
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes: [factory/first.py]
+    no_write_reason: ""
+    shared_writes: []
+    open_questions: []
+  US2:
+    tests:
+      - path: tests/test_second.py
+        status: existing
+        disposition: preserve
+        assertion: the second bounded behavior remains covered
+        decision: spec.md:FR-002
+    preserved_behavior:
+      - the second behavior remains deterministic
+    checks:
+      development: ['uv run pytest tests/test_second.py']
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes: [factory/second.py]
+    no_write_reason: ""
+    shared_writes: []
+    open_questions: []
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/independent-files/spec.md

@@ -0,0 +1,37 @@
+---
+state: draft
+---
+
+# Feature Specification: Independent writers fixture
+
+## Requirements *(mandatory)*
+
+- **FR-001**: The first story MUST write only its file.
+- **FR-002**: The second story MUST write only its own file.
+
+### User Story 1 - First writer (Priority: P1)
+
+As the operator, I want bounded parallel work.
+
+**Acceptance Scenarios**:
+
+1. **Given** unrelated files, **When** the stories run, **Then** parallelism remains available.
+
+### User Story 2 - Second writer (Priority: P1)
+
+As the operator, I want an unrelated bounded slice.
+
+**Acceptance Scenarios**:
+
+1. **Given** no common file, **When** the stories run, **Then** no contention edge is needed.
+
+## Work Graph
+
+```yaml
+US1:
+  depends_on: []
+  implements: [FR-001]
+US2:
+  depends_on: []
+  implements: [FR-002]
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/independent-files/tasks.md

@@ -0,0 +1,9 @@
+# Tasks
+
+## Phase 1: User Story 1
+
+- [ ] T001 [US1-S1] Edit `factory/first.py` and `tests/test_first.py`.
+
+## Phase 2: User Story 2
+
+- [ ] T002 [US2-S1] Edit `factory/second.py` and `tests/test_second.py`.

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/integration-owner/plan.md

@@ -0,0 +1,50 @@
+# Plan
+
+## Refinement Record
+
+```yaml
+version: 1
+reviewed_revision: HEAD
+stories:
+  US1:
+    tests:
+      - path: tests/test_decisions.py
+        status: existing
+        disposition: preserve
+        assertion: old entries remain byte-for-byte
+        decision: spec.md:FR-001
+    preserved_behavior:
+      - landed decision entries remain byte-for-byte
+    checks:
+      development: ['uv run pytest tests/test_decisions.py']
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes: [docs/decisions.md, factory/decision.py]
+    no_write_reason: ""
+    shared_writes:
+      - path: docs/decisions.md
+        other_spec: 001-refinement
+        other_story: US2
+        disposition: integration_owner
+        reason: US2 supplies a distinct input and does not write the shared log
+    open_questions: []
+  US2:
+    tests:
+      - path: tests/test_decisions.py
+        status: existing
+        disposition: preserve
+        assertion: the input remains covered
+        decision: spec.md:FR-002
+    preserved_behavior:
+      - the input remains bounded and deterministic
+    checks:
+      development: ['uv run pytest tests/test_decisions.py']
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes: [factory/integration-input.py]
+    no_write_reason: ""
+    shared_writes: []
+    open_questions: []
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/integration-owner/spec.md

@@ -0,0 +1,37 @@
+---
+state: draft
+---
+
+# Feature Specification: Integration owner fixture
+
+## Requirements *(mandatory)*
+
+- **FR-001**: The integration writer MUST be the single final writer.
+- **FR-002**: The other story MUST provide a distinct integration input.
+
+### User Story 1 - Integration owner (Priority: P1)
+
+As the operator, I want exactly one final decision writer.
+
+**Acceptance Scenarios**:
+
+1. **Given** a distinct input, **When** story 1 runs, **Then** it preserves the immutable log.
+
+### User Story 2 - Integration input (Priority: P1)
+
+As the operator, I want a separate bounded input.
+
+**Acceptance Scenarios**:
+
+1. **Given** the decision log, **When** story 2 runs, **Then** it writes only its input file.
+
+## Work Graph
+
+```yaml
+US1:
+  depends_on: []
+  implements: [FR-001]
+US2:
+  depends_on: []
+  implements: [FR-002]
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/integration-owner/tasks.md

@@ -0,0 +1,9 @@
+# Tasks
+
+## Phase 1: User Story 1
+
+- [ ] T001 [US1-S1] Integrate the bounded inputs and append to `docs/decisions.md`.
+
+## Phase 2: User Story 2
+
+- [ ] T002 [US2-S1] Write `factory/integration-input.py`.

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/shared-decision-write/plan.md

@@ -0,0 +1,50 @@
+# Plan
+
+## Refinement Record
+
+```yaml
+version: 1
+reviewed_revision: HEAD
+stories:
+  US1:
+    tests:
+      - path: tests/test_decisions.py
+        status: existing
+        disposition: preserve
+        assertion: the input remains covered
+        decision: spec.md:FR-001
+    preserved_behavior:
+      - the bounded decision input remains deterministic
+    checks:
+      development: ['uv run pytest tests/test_decisions.py']
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes: [docs/decisions.md, factory/decision.py]
+    no_write_reason: ""
+    shared_writes:
+      - path: docs/decisions.md
+        other_spec: 001-refinement
+        other_story: US2
+        disposition: merge_order
+        reason: the derived edge lands US1 before US2
+    open_questions: []
+  US2:
+    tests:
+      - path: tests/test_decisions.py
+        status: existing
+        disposition: preserve
+        assertion: old decision entries remain byte-for-byte
+        decision: spec.md:FR-002
+    preserved_behavior:
+      - landed entries in docs/decisions.md remain byte-for-byte
+    checks:
+      development: ['uv run pytest tests/test_decisions.py']
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes: [docs/decisions.md]
+    no_write_reason: ""
+    shared_writes: []
+    open_questions: []
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/shared-decision-write/spec.md

@@ -0,0 +1,37 @@
+---
+state: draft
+---
+
+# Feature Specification: Shared decision write fixture
+
+## Requirements *(mandatory)*
+
+- **FR-001**: The first story MUST prepare the accepted decision.
+- **FR-002**: The second story MUST append without changing landed entries.
+
+### User Story 1 - Decision input (Priority: P1)
+
+As the operator, I want a bounded decision input.
+
+**Acceptance Scenarios**:
+
+1. **Given** the decision source, **When** story 1 runs, **Then** it provides the integration input.
+
+### User Story 2 - Decision append (Priority: P1)
+
+As the operator, I want one append-only integration writer.
+
+**Acceptance Scenarios**:
+
+1. **Given** story 1 is merged, **When** story 2 runs, **Then** it preserves landed entries byte-for-byte.
+
+## Work Graph
+
+```yaml
+US1:
+  depends_on: []
+  implements: [FR-001]
+US2:
+  depends_on: []
+  implements: [FR-002]
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/shared-decision-write/tasks.md

@@ -0,0 +1,9 @@
+# Tasks
+
+## Phase 1: User Story 1
+
+- [ ] T001 [US1-S1] Add `factory/decision.py` input and append its source citation to `docs/decisions.md`.
+
+## Phase 2: User Story 2
+
+- [ ] T002 [US2-S1] Append the accepted decision to `docs/decisions.md`; preserve landed entries byte-for-byte.

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/stale-reference/plan.md

@@ -0,0 +1,29 @@
+# Plan
+
+## Refinement Record
+
+```yaml
+version: 1
+reviewed_revision: HEAD
+stories:
+  US1:
+    tests:
+      - path: tests/missing.py
+        status: existing
+        disposition: preserve
+        assertion: the referenced behavior remains covered
+        decision: spec.md:FR-001
+    preserved_behavior:
+      - the referenced behavior remains covered
+    checks:
+      development:
+        - uv run pytest tests/missing.py
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes:
+      - factory/behavior.py
+    no_write_reason: ""
+    shared_writes: []
+    open_questions: []
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/stale-reference/spec.md

@@ -0,0 +1,25 @@
+---
+state: draft
+---
+
+# Feature Specification: Stale reference fixture
+
+## Requirements *(mandatory)*
+
+- **FR-001**: A stale test reference MUST be refused.
+
+### User Story 1 - Stale reference (Priority: P1)
+
+As the operator, I want stale references to fail by name.
+
+**Acceptance Scenarios**:
+
+1. **Given** a missing referenced test, **When** validation runs, **Then** it refuses the reference.
+
+## Work Graph
+
+```yaml
+US1:
+  depends_on: []
+  implements: [FR-001]
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/stale-reference/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+## Phase 1: User Story 1
+
+- [ ] T001 [US1-S1] Review `tests/missing.py` before changing `factory/behavior.py`.

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/unresolved-intent/plan.md

@@ -0,0 +1,29 @@
+# Plan
+
+## Refinement Record
+
+```yaml
+version: 1
+reviewed_revision: HEAD
+stories:
+  US1:
+    tests:
+      - path: tests/test_example.py
+        status: existing
+        disposition: preserve
+        assertion: the current behavior remains observable
+        decision: spec.md:FR-001
+    preserved_behavior:
+      - the current test remains unchanged
+    checks:
+      development:
+        - uv run pytest tests/test_example.py
+      handoff: declared_gates
+      independent: declared_pipeline
+      release: ['release owner: docs/decisions.md']
+    writes: []
+    no_write_reason: no product choice is accepted
+    shared_writes: []
+    open_questions:
+      - Which product behavior wins?
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/unresolved-intent/spec.md

@@ -0,0 +1,25 @@
+---
+state: draft
+---
+
+# Feature Specification: Unresolved intent fixture
+
+## Requirements *(mandatory)*
+
+- **FR-001**: The product choice MUST be exposed before implementation.
+
+### User Story 1 - Unresolved intent (Priority: P1)
+
+As the operator, I want an unresolved product choice to block readiness.
+
+**Acceptance Scenarios**:
+
+1. **Given** no accepted decision, **When** refinement runs, **Then** it asks the named product question.
+
+## Work Graph
+
+```yaml
+US1:
+  depends_on: []
+  implements: [FR-001]
+```

ergane_cli-0.7.0/.agents/skills/refine-spec/fixtures/unresolved-intent/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+## Phase 1: User Story 1
+
+- [ ] T001 [US1-S1] Preserve `tests/test_example.py` until the product choice is accepted.

ergane_cli-0.7.0/.agents/skills/refine-spec/references/capability-evidence.md

@@ -0,0 +1,10 @@
+# Capability evidence
+
+| Capability | Declared | Available | Executed | Evidence |
+| --- | --- | --- | --- | --- |
+| Skill instruction | Yes | Yes | Not observed | SKILL.md |
+| Skill fixture replay | No | Yes | Yes | deterministic validator report |
+| Client follow-through | No | Unknown | No | authorized release trial |
+
+Do not promote a fixture replay to agent compliance. The release trial must
+observe the authorized client, and the report must say whether it did.

ergane_cli-0.7.0/.agents/skills/refine-spec/references/review-record.md

@@ -0,0 +1,50 @@
+# Review record format
+
+Place exactly one `## Refinement Record` section and exactly one YAML fence in
+the plan. Version 1 has only `version: 1`, `reviewed_revision`, and
+`stories`. `reviewed_revision` is a revision that resolves locally in the
+declared target; a later revision is a review input, not proof of identity.
+`stories` keys exactly match the declared stories. The validator checks
+structure and references, not the semantic truth of assertions or the authority
+of citations.
+
+```yaml
+version: 1
+reviewed_revision: HEAD
+stories:
+  US1:
+    tests:
+      - path: tests/example.py
+        status: existing
+        disposition: replace
+        assertion: the accepted replacement behavior is asserted
+        decision: spec.md:FR-001
+    preserved_behavior:
+      - the previous decision source and landed entries remain identified
+    checks:
+      development:
+        - uv run pytest tests/example.py
+      handoff: declared_gates
+      independent: declared_pipeline
+      release:
+        - 'release owner: docs/decisions.md'
+    writes:
+      - factory/example.py
+    no_write_reason: ""
+    shared_writes: []
+    open_questions: []
+```
+
+For replacement, the decision is a source citation, the assertion names the
+replacement behavior, and `preserved_behavior` names the behavior, citation, or
+landed bytes that must remain. Empty tests require a nonempty
+`no_test_change_reason`; empty writes require a nonempty `no_write_reason`.
+An unresolved product choice goes in `open_questions` and blocks readiness
+instead of being settled by preference.
+
+For one shared immutable decision log, derive the writer set from actual task
+text. A `merge_order` entry must match an actual edge. An `integration_owner`
+entry is valid only when exactly one story declares the final shared-file write
+and the other supplies distinct integration inputs. Preserve landed entries
+byte-for-byte. A cross-spec `concurrent` entry is advisory only; the final
+release DAG resolves it.