“There’s something wrong with the world today I don’t know what it is Something’s wrong with our eyes We’re seeing things in a different way And God knows it ain’t His It sure ain’t no surprise, yeah” — Aerosmith
Livin
Livin is a planned cross-language Rust CLI that checks whether a test suite actually exercises the boundary values a piece of code’s own shape implies exist — zero, empty, singleton, duplicate, overflow, every arm of a sum type — rather than only the values a property-based generator happens to sample.
Draft and unimplemented
EARS 1.0.0 and any OpenSpec changes are active proposals awaiting human approval. This site documents intended behavior; it does not claim that the CLI has been implemented.
Start here
- Read the authoritative EARS specification.
- Review the implementation roadmap.
- See the project context for architecture and testing constraints.
- Read contributing before changing requirements or starting implementation.
Documentation provenance
The Pages site is assembled directly from livin-ears-spec.md and
openspec/changes/ during CI. The rendered copies are generated artifacts;
the repository source files remain authoritative.
Source: Generated from
openspec/project.mdduring the documentation build.
Project Context
Purpose
Livin is a cross-language CLI that checks whether a test suite actually exercises the boundary values a piece of code’s own shape implies exist — zero, empty, singleton, duplicate, overflow, every arm of a sum type — rather than only the values a property-based generator happens to sample.
The normative product requirements are in livin-ears-spec.md; OpenSpec
changes select reviewed implementation slices and do not override it. Preserve
its requirement IDs (REQ-*) in proposals, tests, findings, and traceability
notes.
Tech Stack
- Implementation language: Rust, organized as a Cargo workspace and exposed
as the
livinCLI binary. - Rust baseline: stable toolchain, rustfmt formatting, Clippy linting, and Cargo-native unit, integration, and documentation tests.
- Language analysis: tree-sitter or a language-native parser behind front-end plugins.
- Core model: a language-agnostic representation of shapes, shape kinds, boundary values, and reachability classes.
- CLI output: human-readable, JSON, and SARIF.
Project Conventions
Code Style
- Format with rustfmt and keep Clippy clean.
- Use domain terms from the EARS specification consistently: shape, shape kind, boundary value, boundary catalogue, coverage gap, reachability class, shape source, exercised.
- Keep built-in vocabularies closed and project extensions explicitly
declared and validated. Unknown shapes remain
opaque/unclassified; never silently coerce them to a successful/default case. - Use stable requirement and rule IDs. A finding always has a rule ID, file, line, boundary value, reachability class, and shape source.
Architecture Patterns
- Keep language-specific shape extraction and literal/constant-expression matching in versioned, conformance-tested front-end plugins.
- Maintain a versioned boundary catalogue mapping each shape kind to a finite set of named boundary values, validated by conformance fixtures.
- Prefer consuming shape data from an installed composability checker (Vampiro) when available; fall back to standalone extraction at reduced precision otherwise.
- Support diff-scoped analysis as the interactive/agent default and full repository analysis as an incremental mode.
- Never generate or modify test files; only report coverage gaps.
Testing Strategy
- Develop every behavior from an OpenSpec scenario traceable to one or more EARS requirement IDs.
- Maintain a shared, versioned conformance-fixture suite for every front-end plugin and boundary catalogue entry.
- The initial MVP analyzes stable Rust and discovers only built-in
#[test]functions; all other languages, doctests, macro-generated tests, and external test frameworks remain explicitly unsupported. - Test all supported output formats against the same underlying finding data.
- Include negative fixtures for opaque shapes, undefined matchers, unknown reachability, and unconfirmed refinements.
- Benchmark diff-scoped scans with the committed 500-node/100-test fixture and reproducible protocol specified by REQ-22.
Git Workflow
- Use OpenSpec changes for new capabilities, architecture changes, breaking behavior, and performance work. Do not implement a proposal before approval.
- Keep commits focused and preserve requirement IDs in change artifacts and test names where practical.
- Pull-request CI should run diff-scoped check in
gatemode at the configured severity threshold.
Domain Context
Livin asks whether the test suite hits the values most likely to contain a bug. Its core taxonomy of shape kinds:
numeric— zero, min/max, overflow point, NaN/Inf where applicablecollection— empty, singleton, duplicate, maximum declared cardinalitysum/union— each arm treated as a separate obligationrecursive/self-referential— self-reference or cycle instancestring/text— empty string, encoding boundaryrecord/product— field-level boundary compositionopaque— could not be classified
Every boundary obligation has state covered, uncovered, or
indeterminate. Only uncovered obligations are coverage gaps. Coverage gaps
also carry a reachability class (reachable, unreachable, or unknown)
derived from upstream constraints.
Important Constraints
- Static analysis must never execute analyzed source code.
- Unknown or unsupported shapes must be visible in output, never silently omitted.
- The tool must never generate or modify test files.
guidancemode never fails solely because of findings;gatemode fails only when coverage gaps on diff-touched nodes meet the configured threshold.- The repository is greenfield.
openspec/specs/describes built truth, so do not copy aspirational EARS requirements there before implementation; add them through reviewed changes and archive them as capabilities ship.
External Dependencies
- Git diff/repository metadata for diff-scoped analysis and reachability estimation.
- Per-language tree-sitter grammars or native parser APIs.
- Optionally: installed Vampiro composability checker for shape data.
- CI platforms capable of consuming generated pipeline configuration and SARIF.
Document status: Draft, not yet approved. The source file
livin-ears-spec.mdis authoritative.
EARS Specification: Livin
Livin (as in “livin’ on the edge”) is a cross-language CLI that checks whether a test suite actually exercises the boundary values a piece of code’s own shape implies exist — zero, empty, singleton, duplicate, overflow, every arm of a sum type — rather than only the values a property-based generator happens to sample.
This document is the normative product-requirements source. It is self-contained and assumes no prior conversation, no other document, and no familiarity with any other tool, though Section 1 notes where Livin optionally consumes data already produced by a composability checker called Vampiro, if one is present. OpenSpec changes select implementable slices of these requirements; if an OpenSpec artifact conflicts with this document, this document governs until it is explicitly amended.
0. Background & Motivation
Property-based testing (PBT) generates many inputs and checks that a declared property holds for all of them, which is effective for finding unanticipated combinations of ordinary values that happen to violate a law. It is systematically weak at a different, complementary thing: boundary values are a vanishingly small target in a type’s overall space, so a uniform or shrinking-based generator can run thousands of iterations and still never construct the empty collection, the duplicate key, the exact-max-cardinality case, or the identity element — precisely the values most likely to break an invariant, because they are the values most likely to have been handled by a special case someone forgot to write.
Fixed example-based fixtures fix this for known laws (an associativity check can and should include an explicit empty-input example), but that only covers code with a declared law suite. Most functions in a codebase have no declared algebraic law at all, and still have a shape — a domain and codomain with numeric ranges, collection structures, sum types, and so on — that implies a set of boundary values worth exercising regardless of whether any formal property is declared for that function.
Livin targets that gap specifically: given a function’s shape, what are the canonical boundary instantiations for a value of that shape, and does the test suite exercise them anywhere? This is a coverage question about tests, not a composability question about call sites, which is why it is a separate tool rather than an axis inside a composability checker: a composability checker asks whether two pieces fit together; Livin asks whether the test suite hit the values most likely to reveal that they don’t. It is also distinct from mutation testing (which asks “would the suite catch an injected bug”) — Livin asks whether the suite reaches the values most likely to contain a bug in the first place, independent of whether any mutation was ever injected.
Livin explicitly does not cover concurrency-interleaving edge cases (races, retry-under-concurrent-write, partial-failure interleavings). Those are boundaries of execution order, not of a value’s shape, require a different extraction entirely, and are better addressed by a model-checking tool (e.g. TLA+) than by test-suite coverage analysis.
1. Scope & Definitions
- Shape: a structural signature of a value — described by shape kind (below) plus enough structural detail (numeric range, collection element type, union arms, field set) to determine which boundary values apply to it. Livin does not require full nominal types, only this structural description.
- Shape kind: a closed-but-extensible taxonomy tag on a shape:
numeric,collection,sum/union,recursive/self-referential,string/text,record/product, oropaque(shape could not be classified into any other kind). - Boundary value: one canonical, named instantiation of a shape kind
associated with disproportionate real-world defect rates — for
example, for
numeric: zero, the type’s minimum/maximum, the overflow point,NaN/Infwhere the type admits them; forcollection: empty, singleton, a duplicate-key/duplicate-element instance, the maximum declared cardinality; forsum/union: each arm, treated as a separate obligation; forrecursive/self-referential: a self-reference or cycle instance; forstring/text: the empty string and an encoding boundary (multi-byte or unmatched-surrogate input) where relevant. - Boundary catalogue: a versioned, per-shape-kind table mapping shape kind to its finite set of named boundary values, extensible the same way an idiom table is extensible, and validated by conformance fixtures.
- Literal/constant-expression match: Livin’s matching discipline for deciding whether a test exercises a boundary value: syntactic detection of a literal value, or a well-known zero/empty/identity constructor, passed as an argument (or asserted as a produced value) at a call site whose shape includes that boundary’s shape kind. This is deliberately not full symbolic execution, to keep the check deterministic.
- Exercised: true for a given (node, boundary value) pair if some test in the scanned suite contains a literal/constant-expression match for it.
- Obligation state: exactly one of
covered(at least one definite literal/constant-expression match exists),uncovered(all candidate matches were definitely non-matches, including the case where there are no candidates), orindeterminate(no definite match exists and at least one candidate cannot be decided statically, or the language/matcher is unsupported).indeterminateis not a coverage gap and is never treated ascoveredoruncovered. - Coverage gap: a (node, boundary value) pair whose obligation state is
uncovered. Anindeterminateobligation is not exercised, but is not a coverage gap because available static evidence cannot establish absence. - Reachability class:
reachable(no upstream constraint rules the boundary value out at this call site),unreachable(an upstream validation or type refinement statically rules it out — e.g. a parameter constrained to positive integers cannot receive zero), orunknown(reachability cannot be determined from available shape information). - Shape source:
vampiro(shape data consumed from an installed composability checker’s extracted call graph) orstandalone(Livin’s own reduced-precision shape extraction, used when no such checker is present). Every finding records which source produced its shape data. - Suite: the corpus of test files/functions Livin scans for literal/constant-expression matches.
- Initial MVP language scope: Rust source accepted by stable
rustc, with tests discovered only from built-in#[test]functions in the analyzed Cargo workspace. Macro-generated tests, doctests, external test frameworks, and every non-Rust language/framework are unsupported in the initial MVP. Unsupported files or test constructs are reported explicitly and any affected obligations areindeterminate; they are never silently skipped.
2. Ubiquitous Requirements
- REQ-1: The tool shall obtain domain/codomain shapes for analyzed nodes, preferentially by consuming an installed composability checker’s extracted shape data when available, and shall record shape source on every run.
- REQ-2: The tool shall classify every consumed shape into exactly one shape kind from the closed-but-extensible taxonomy in Section 1.
- REQ-3: The tool shall maintain a versioned boundary catalogue mapping each shape kind to a finite set of named boundary values, validated by conformance fixtures using the same mechanism as an idiom-table check: a fixed set of synthetic shapes with known-correct expected boundary sets.
- REQ-4: The tool shall scan the configured test suite for literal/constant-expression matches between test call arguments or assertions and each (node, boundary value) obligation implied by that node’s shape.
- REQ-5: Every finding shall carry a rule ID, the file and line of the under-tested node, the boundary value’s name, its reachability class, and its shape source.
- REQ-6: The tool shall never generate or modify test files; it shall only report coverage gaps, consistent with this tool family’s enforcement-not-generation design.
3. Event-Driven Requirements
-
REQ-7: When a node’s shape kind has one or more applicable boundary values and a given boundary value’s obligation state is
uncovered, the tool shall raise a coverage-gap finding naming the unexercised boundary. It shall not raise a coverage-gap finding forcoveredorindeterminateobligations.Example:
apply_discount(amount: Decimal, pct: float)where no test in the suite calls it withpct == 0oramount == Decimal(0)raises two coverage-gap findings, one per unexercised numeric boundary. -
REQ-8: When a shape kind is
sum/union, the tool shall treat each arm as a separate boundary obligation and raise one coverage-gap finding per uncovered arm, independent of whether other arms are covered.Example:
fn summarize(items: Vec<Order>) -> Result<Summary, SummarizeError>where the test suite calls it only with non-empty input and only exercises theOkarm raises two findings: an unexercisedemptycollection boundary, and an unexercisedErrarm. -
REQ-9: When a coverage gap’s reachability class is
unreachable, the tool shall still report the finding, at a downgraded severity tier, rather than omit it. If the shape’s unreachability rests on a refined type (a smart constructor, per a companion composability checker’s boundary-validation model), that downgrade shall only be trusted if the constructor’s own boundary-value coverage is itself fully exercised; otherwise the finding shall be reported at reachability classunknownrather thanunreachable, since an unconfirmed refinement is not evidence the boundary actually holds.Example: a TypeScript parameter typed as a branded
PositiveIntcannot receive zero or a negative value if the brand’s constructor genuinely rejects them. Livin still reports the gap — nothing in the suite confirms the brand’s construction actually enforces that — at reachability classunreachableonly once the constructor itself has full boundary coverage; until then it is reported asunknown. -
REQ-10: When no installed composability checker’s shape data is available, the tool shall fall back to its own standalone shape extraction (REQ-14) and shall record
shape-source: standaloneon every finding produced in that run.
4. State-Driven Requirements
- REQ-11: While gate mode is
gate, the tool shall exit non-zero if anyreachable-class,uncoveredcoverage gap on a diff-touched node meets or exceeds the configured severity threshold.coveredandindeterminateobligations shall not contribute to the gate exit decision. - REQ-12: While gate mode is
guidance, the tool shall report all findings without forcing a non-zero exit. - REQ-13: While a node’s shape kind is
opaque, the tool shall report it asunclassifiedexplicitly, rather than silently exclude it from output.
5. Optional Feature Requirements
- REQ-14: Where no composability checker’s shape data is installed or accessible, the tool shall perform a standalone shape extraction sufficient to classify shape kind, at reduced precision (e.g. no cross-module shape unification), so the tool can operate without a hard dependency on any other tool in the family.
- REQ-15: Where a custom boundary catalogue entry is supplied for a
project-specific shape (e.g. a domain type
Moneywith a declared “must not be negative” boundary), the tool shall use it in place of, or in addition to, the built-in catalogue. - REQ-16: Where diff-scoped mode is selected, the tool shall restrict coverage-gap checking to nodes touched by the diff.
6. Unwanted Behavior Requirements
- REQ-17: If a boundary catalogue entry has no defined
literal/constant-expression matcher for the active language, the tool
shall report
matcher:undefinedfor that entry rather than silently treat it as covered or uncovered. - REQ-18: If the same node is reachable via multiple call paths with different reachability classes for the same boundary value, the tool shall report the most permissive (most-reachable) class observed, rather than average the classes or pick one arbitrarily.
- REQ-19: If literal/constant-expression matching cannot determine
whether a dynamically constructed test value equals a boundary value
(the value is computed at runtime rather than written as a literal),
and no definite match exists for the same obligation, the tool shall set
the obligation state to
indeterminate, report an indeterminate diagnostic naming the boundary and reason, and shall not emit a coverage-gap finding or fail the gate for that obligation. A definite match takes precedence and makes the obligationcovered.
7. Complex Requirements
- REQ-20: While shape source is
standalone, when a coverage-gap finding’s reachability class would otherwise beunreachable, the tool shall instead reportunknownunless standalone extraction can itself establish the upstream constraint, since standalone mode’s reduced precision cannot reliably confirm unreachability on its own. - REQ-21: When a node participates in a redundancy/fallback chain with divergent codomain shapes across branches, the tool shall evaluate boundary coverage independently per branch shape, rather than merging the branches into one shape before checking coverage.
8. Non-Functional Requirements
- REQ-22: A release-build diff-scoped scan of the committed performance
fixture (500 diff-touched Rust function nodes and 100 built-in
#[test]functions) shall have a median wall-clock time of at most 9.0 seconds over 10 measured runs after one unmeasured warm-up, on an otherwise idle x86-64 machine with at least 2 dedicated CPU cores, 4 GiB RAM, and local SSD. The repository shall provide one documented command that builds the release binary, verifies the fixture checksum, disables network access during the scan, runs this protocol, and emits the raw timings plus median; CI shall retain that output. - REQ-23: The boundary catalogue and its conformance fixtures shall be versioned and reproducible byte-for-byte across repeated runs on unchanged input.
9. Traceability Notes
- Shape acquisition and classification → REQ-1, REQ-2, REQ-10, REQ-14.
- Boundary catalogue and conformance → REQ-3, REQ-15, REQ-23.
- Core coverage-gap detection → REQ-4, REQ-7, REQ-8, REQ-19.
- Reachability grading → REQ-9, REQ-18, REQ-20.
- Reporting discipline (never silently omit, never generate tests) → REQ-5, REQ-6, REQ-13, REQ-17.
- Operational modes → REQ-11, REQ-12, REQ-16, REQ-22.
- Redundancy-chain interaction → REQ-21.
Appendix: Worked Examples
Numeric boundary gap (Python)
def apply_discount(amount: Decimal, pct: float) -> Decimal: ...
# suite only ever calls apply_discount(Decimal("19.99"), 0.15)
Shape kind numeric for both parameters; catalogue includes a zero
boundary for each. Neither is exercised → two REQ-7 findings.
Collection + sum-arm gap (Rust)
#![allow(unused)]
fn main() {
fn summarize(items: Vec<Order>) -> Result<Summary, SummarizeError> { ... }
// tests: summarize(vec![order1, order2]) -> assert Ok(...)
}
items is collection; its empty boundary is unexercised. The return
type is sum/union with arms Ok/Err; only Ok is exercised → one
REQ-7 finding plus one REQ-8 finding.
Reachability downgrade, confirmed refinement (TypeScript)
type PositiveInt = number & { __brand: "PositiveInt" };
function toPositiveInt(n: number): PositiveInt | null { ... } // smart constructor
function setQuantity(q: PositiveInt) { ... }
The zero boundary for q is structurally ruled out by the branded
type, but only if toPositiveInt genuinely rejects zero. If
toPositiveInt itself has full boundary coverage (its own zero case is
exercised and confirmed to return null), the setQuantity finding is
reported at reachability class unreachable, downgraded severity, per
REQ-9. If toPositiveInt’s own boundary coverage is incomplete, the same
finding is reported at reachability class unknown instead — the
refinement is unconfirmed, so it isn’t trusted to rule anything out.
Standalone mode, unconfirmed reachability (Julia, no Vampiro installed)
function apply_rate(x::Float64, rate::Float64)::Float64
x * rate
end
Without an installed composability checker, Livin’s standalone
extraction (REQ-14) can see the Float64 shape but cannot confirm any
upstream constraint on rate. A zero-boundary gap on rate is
reported with reachability class unknown per REQ-20, not
unreachable, since standalone mode cannot establish the negative case.
Per-branch coverage on a redundancy chain (Python)
try:
data = primary_source.fetch(id) # -> FullRecord
except SourceUnavailable:
data = cache.get(id) # -> PartialRecord | None
Per REQ-21, Livin evaluates boundary coverage for FullRecord and for
PartialRecord | None independently rather than as one merged shape —
an empty/None boundary unexercised on the fallback branch is reported
even if the primary branch’s boundaries are fully covered.
Implementation roadmap
Status: These are active, unimplemented OpenSpec changes. They become built truth only after implementation, review, and archival.
| Change | Status | Tasks complete |
|---|---|---|
add-rust-zero-boundary-tracer | Active proposal | 0/11 |
depend-on-genesis | Active proposal | 0/9 |
Each change page includes its proposal, capability delta, design, and approval-gated tracer-bullet task plan.
Status: Active OpenSpec proposal; not implemented or deployed. The source under
openspec/changes/is authoritative.
Change: Add Rust zero-boundary tracer
Why
Livin needs one end-to-end analyzer path that proves its obligation-state semantics before broader catalogues, frameworks, and reporting formats are designed.
What Changes
- Add a
livin checktracer for explicit Rusti32parameters and the built-in numericzeroboundary. - Discover direct calls in built-in
#[test]functions and classify each zero obligation ascovered,uncovered, orindeterminate. - Emit deterministic human-readable diagnostics and enforce gate/guidance exit behavior for this tracer only.
Impact
- Affected capability:
rust-zero-boundary-check - Future implementation: Cargo workspace, Rust parser, CLI, fixture tests
- Source requirements: REQ-4, REQ-5, REQ-6, REQ-7, REQ-11, REQ-12, REQ-19
Dependencies and Order
No predecessor. Approval of the normative EARS specification and this change is required before implementation.
Capability delta
Status: Active OpenSpec proposal; not implemented or deployed. The source under
openspec/changes/is authoritative.
ADDED Requirements
Requirement: Rust i32 zero obligation classification
The system SHALL statically inspect explicit i32 parameters on Rust free
functions and direct calls from built-in #[test] functions, without compiling,
executing, or modifying the analyzed workspace. For the built-in numeric
zero boundary it SHALL classify each obligation as exactly covered,
uncovered, or indeterminate according to REQ-4, REQ-6, REQ-7, and REQ-19.
Scenario: Literal zero covers the obligation
- WHEN a built-in
#[test]function directly calls the analyzed function with literal0for its expliciti32parameter - THEN the zero obligation is
coveredand no coverage-gap finding is emitted
Scenario: Definite non-zero calls leave a gap
- WHEN every direct test call passes a definite non-zero integer literal for the parameter
- THEN the zero obligation is
uncoveredand one coverage-gap finding is emitted
Scenario: Runtime value is indeterminate
- WHEN there is no definite zero match and at least one direct test call passes a runtime-computed value
- THEN the zero obligation is
indeterminate, an indeterminate diagnostic is emitted, and no coverage-gap finding is emitted
Scenario: Definite coverage takes precedence
- WHEN one direct test call passes literal
0and another passes a runtime-computed value - THEN the zero obligation is
covered
Requirement: Tracer reporting and mode exits
The system SHALL emit deterministic human-readable obligation output carrying
the REQ-5 fields available to this tracer: rule ID, file, line, boundary name,
reachability class, and shape source. Guidance mode SHALL return success after
a successful scan. Gate mode SHALL return the documented policy-failure exit
only for an uncovered, reachable tracer obligation, and SHALL return success
for covered and indeterminate obligations (REQ-11, REQ-12, REQ-19).
Scenario: Uncovered obligation gates
- WHEN gate mode successfully scans an uncovered zero obligation
- THEN it emits one reachable standalone coverage-gap finding and exits with the documented policy-failure status
Scenario: Indeterminate obligation does not gate
- WHEN gate mode successfully scans an indeterminate zero obligation
- THEN it emits an indeterminate diagnostic and exits successfully
Scenario: Guidance reports without gating
- WHEN guidance mode successfully scans an uncovered zero obligation
- THEN it emits the finding and exits successfully
Requirement: Explicit tracer scope
The system SHALL identify this capability as limited to stable Rust, built-in
#[test] functions, explicit free-function i32 parameters, direct calls,
and the zero boundary. Encountered unsupported languages, frameworks, or
Rust constructs SHALL be reported explicitly and SHALL NOT be interpreted as
evidence of covered or uncovered obligations.
Scenario: Unsupported test construct is visible
- WHEN the scan encounters a macro-generated test relevant to a tracer candidate
- THEN it reports the construct as unsupported and does not classify that construct as a definite match or non-match
Design
Status: Active OpenSpec proposal; not implemented or deployed. The source under
openspec/changes/is authoritative.
Context
The repository is greenfield. This change must cross the real CLI, parser, obligation model, reporting, and exit boundary without implying broad MVP coverage.
Goals / Non-Goals
- Goals: one deterministic Rust
i32/zero path; all three obligation states; guidance/gate behavior; immutable source files. - Non-goals: other numeric boundaries or types, return assertions, reachability inference, diff scoping, JSON/SARIF, Vampiro input, or unsupported frameworks.
Test Shape
Integration fixtures provide a Cargo workspace, one explicit free-function
i32 parameter, and zero, non-zero, or runtime-computed arguments in built-in
#[test] functions. Tests assert diagnostics, obligation state, and exact exit
status. Parser/unit tests cover classification precedence.
Decisions
- Parse Rust statically; never compile or execute the analyzed workspace.
- A literal
0direct argument covers the obligation. Only definite non-zero literals make it uncovered. A runtime-computed argument with no literal-zero match makes it indeterminate; a definite zero match takes precedence. - Human output has one stable line per obligation, sorted by file, line, function, parameter, and boundary. Uncovered lines are findings; indeterminate lines are diagnostics.
- Guidance always exits zero after a successful scan. Gate exits with the policy-failure code only for an uncovered tracer finding. The implementation shall separately document and test numeric policy and operational exit codes.
Risks / Trade-offs
- The narrow syntax can look like general Rust support. Help and diagnostics must label it a tracer and report encountered unsupported constructs.
- Adding a parser dependency shapes later architecture. Keep parsing behind a front-end interface and avoid exposing parser types in the obligation model.
Approval Gate
Implementation SHALL NOT begin until a human approves this proposal and the normative EARS source.
Tasks
Status: Active OpenSpec proposal; not implemented or deployed. The source under
openspec/changes/is authoritative.
Implementation is blocked until human approval of the normative EARS source and this proposal is recorded.
1. CLI and Parser Seam (red → green)
- 1.1 Add failing help and operational-exit integration tests for
livin check, including the tracer scope and unsupported-syntax wording. - 1.2 Add the minimal stable Rust workspace, CLI, parser front-end seam, and documented numeric exit codes needed to pass those tests; do not add analysis behavior.
- 1.3 Run focused tests, workspace tests, rustfmt, and Clippy with warnings denied; record evidence.
2. Obligation Classification (red → green)
- 2.1 Add failing table-driven unit tests for zero, non-zero, computed, no-call, and zero-plus-computed inputs, tracing REQ-4, REQ-7, and REQ-19.
- 2.2 Implement the minimal parser and closed
covered|uncovered|indeterminatemodel for explicit free-functioni32parameters and built-in#[test]direct calls. - 2.3 Run focused and workspace quality checks; record fixture and requirement traceability evidence.
3. Reporting and Modes (red → green)
- 3.1 Add failing golden integration tests for stable ordering/fields, immutable fixtures, guidance exits, uncovered gate failure, and indeterminate gate success (REQ-5, REQ-6, REQ-11, REQ-12, REQ-19).
- 3.2 Implement deterministic human reporting and guidance/gate decisions only for tracer obligations.
- 3.3 Run all tests and quality checks, verify fixture files are unchanged, and record evidence.
4. Separate Tidy Pass
- 4.1 After behavior is green, remove duplication without changing snapshots or exposing parser-specific types; rerun all checks.
- 4.2 Run
openspec validate add-rust-zero-boundary-tracer --strictand the repository planning/docs checks.
Status: Active OpenSpec proposal; not implemented or deployed. The source under
openspec/changes/is authoritative.
Change: Depend on genesis-vibes
Why
livin is spec-stage with no src/ yet — build on genesis-vibes from day one.
livin’s add-rust-zero-boundary-tracer change establishes the CLI skeleton;
this change composes with it by sourcing cross-cutting CLI/AIX/self-healing
infra from genesis-vibes (tool-craft playbook §8, Appendix A.4).
What Changes
- Add
genesis-vibesdependency ("0.2") toCargo.toml. - Source the JSON envelope from
genesis::envelope(coverage-gap findings underdata). - Source self-healing errors from
genesis::suggestions. - Source the managed-block injector from
genesis::managed_blockso livin carries WAI/OPENSPEC/DONT blocks and is detectable bywai status(wai-bdqw.9). - Ship
llms.txt/llm.txtviagenesis-vibes::aixonce stable. - Keep all livin domain logic (shape extraction, boundary catalogue, reachability classes, tree-sitter front ends). The genesis boundary rule protects this.
Impact
- Affected capability:
cli-foundation(ADDED — envelope, suggestions, and managed-block mechanics sourced from genesis-vibes). Composes with, and does not replace,add-rust-zero-boundary-tracer. - Blocked by: genesis-vibes v0.2.0 published on crates.io.
- Coordinates with livin’s EARS spec (livin-ears-spec.md) — no REQ changes; this is CLI infrastructure.
Status: Active OpenSpec proposal; not implemented or deployed. The source under
openspec/changes/is authoritative.
cli-foundation spec delta: depend on genesis
ADDED Requirements
Requirement: Shared envelope and self-healing from genesis
livin SHALL source its JSON envelope from genesis::envelope and its self-healing error footers from genesis::suggestions, and SHALL source its managed-block injector from genesis::managed_block, so livin composes with the suite from day one.
Scenario: check emits shared envelope
- WHEN
livin check --jsonis run - THEN the emitted JSON SHALL have top-level keys
ok,envelope_version,cli_version,envelope_kind,data,warnings,hints,meta - AND the coverage-gap findings SHALL be nested under
data.
Scenario: typo suggestion from genesis
- WHEN an unknown livin subcommand is run
- THEN livin SHALL emit a “Did you mean …?” footer via
genesis::suggestions - AND SHALL NOT define a local
Suggestionenum.
Tasks
Status: Active OpenSpec proposal; not implemented or deployed. The source under
openspec/changes/is authoritative.
1. Dependency
- 1.1 Add
genesis = { git = "https://github.com/charly-vibes/genesis", tag = "v0.1.0" }toCargo.toml(once the CLI skeleton lands). - 1.2 Verify build with envelope/suggestions/managed_block modules stable.
2. Source envelope
- 2.1 Route
--json(coverage gaps) throughgenesis::envelope, gaps underdata. - 2.2 Conformance: top-level keys match the shared shape.
3. Source suggestions
- 3.1 Register livin’s command list with
genesis::suggestions::SuggestionEngine. - 3.2 Wire the error sink to emit
genesis::suggestionsfix-footers.
4. Source managed_block
- 4.1 Source injector mechanics from
genesis::managed_block. - 4.2 Carry WAI/OPENSPEC/DONT blocks so
wai statusdetects livin (wai-bdqw.9).
5. AIX artifacts
- 5.1 Ship
llms.txt/llm.txtviagenesis::aix(hand-write minimally until stable).
Contributing
Current phase
Livin is in the planning and approval phase. Do not implement application code until the human approval gate accepts EARS 1.0.0 and all active OpenSpec proposals.
Change workflow
- Update the authoritative EARS document when product requirements change.
- Update the affected OpenSpec proposal, design, capability delta, and tasks.
- Run strict OpenSpec validation.
- Keep
.beads/issues.jsonlsynchronized with the approved task graph. - Build the documentation site.
openspec validate --all --strict --no-interactive
python scripts/check_planning.py
python scripts/build_docs.py
mdbook build
Documentation rules
- Do not hand-edit generated files under
docs/book/. - Requirement IDs must remain stable and traceable.
- Active proposal pages must not claim deployed behavior.
- OpenSpec deltas remain under
openspec/changes/until implementation, review, and archival are complete.
GitHub Pages
Pages uses GitHub’s official artifact deployment actions. Pull requests build
the site but do not deploy it. Pushes to main upload the rendered docs/book/
directory and deploy it to the protected github-pages environment. No
publishing branch is created.