Plumb

Specification

dev07-5 · report it

A sub-flow of dev07 · run plumb. Entered from the verdicts and the citations behind them. Exits with the board, for any tool to consume and a person to read.

3 of 3 stories proven · 0 passed, not wired · 0 unproven · 0 with nothing holding them

dev07-5-1 render one row per cited story Proven

As a reviewer I want the citing tests and what each of them actually reached, so that I act on evidence rather than taking a verdict on trust.

The tests that cite it (27)
  • tests/test_adoption.py::test_an_internal_runner_error_is_not_reported_as_the_project_s_fault — passed, ungrounded
  • tests/test_artifact.py::test_an_absent_run_file_reads_as_nothing_declared — passed, ungrounded
  • tests/test_artifact.py::test_a_project_shadowing_the_tool_is_surfaced_not_silent — passed, ungrounded
  • tests/test_board.py::test_the_board_reports_status_and_achieved_depth_per_story — passed, ungrounded
  • tests/test_board.py::test_the_board_carries_the_evidence_not_just_the_verdict — passed, ungrounded
  • tests/test_board.py::test_a_step_already_taken_is_no_longer_offered — passed, ungrounded
  • tests/test_board.py::test_the_board_carries_the_mutation_score_as_a_proportion_not_a_word — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations0-best-unproven-silent] — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations0-best-unproven-silent] — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations1-best-proven-holding] — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations1-best-proven-holding] — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations2-worst-unproven-breached] — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations2-worst-unproven-breached] — passed, ungrounded
  • tests/test_board.py::test_a_parameter_reads_as_a_parameter_and_its_folds_reduce_all_of — passed, ungrounded
  • tests/test_board.py::test_the_board_carries_the_extent_it_drew_the_condition_from — passed, ungrounded
  • tests/test_board.py::test_scoping_removes_rows_from_the_view_and_never_moves_a_status — passed, ungrounded
  • tests/test_board.py::test_a_scope_narrows_the_verdicts_and_never_the_run_level_facts — passed, ungrounded
  • tests/test_board.py::test_a_subject_read_per_aspect_is_counted_apart_from_stories — passed, ungrounded
  • tests/test_config.py::test_a_project_that_declares_nothing_gets_an_empty_config_not_an_error — passed, ungrounded
  • tests/test_end_to_end.py::test_the_board_comes_out_of_the_command_line — passed, grounded
  • tests/test_end_to_end.py::test_with_no_entry_points_declared_the_board_says_so — passed, grounded
  • tests/test_end_to_end.py::test_the_emitted_board_carries_evidence_and_its_own_next_step — passed, grounded
  • tests/test_end_to_end.py::test_the_one_field_read_alone_is_never_greener_than_what_earned_it — passed, grounded
  • tests/test_gate.py::test_a_subject_with_several_aspects_derives_one_verdict_each_and_no_overall — passed, ungrounded
  • tests/test_gate.py::test_the_graph_runs_at_the_lowest_input_level_and_still_reports — passed, ungrounded
  • tests/test_grounding.py::test_a_project_that_declares_nothing_degrades_rather_than_erroring — passed, ungrounded
  • tests/test_manifest.py::test_an_adapter_that_knows_nothing_of_grounding_still_emits_a_valid_document — passed, ungrounded
Requirements (13)
What the user needs
  • dev07-5-1-ur1one row per cited story: its status, the rungs its tests reached, and what its checks could not settle, named
  • dev07-5-1-ur2every word rendered above a status is a restatement of what the gate derived, never an addition — a rendering that overstates is indistinguishable from proof
  • dev07-5-1-ur3the evidence restates the citing tests with what each claimed and what the run found, carrying its cost and its measurement time on each entry
  • dev07-5-1-ur4the board totals nothing: there is no denominator to divide by, and a reader's arithmetic is done on figures whose scope they know because they made the run
  • dev07-5-1-ur5a lexicon gives a kind of subject its own word for a derived status; where it has no word it says the status's own name rather than inventing one
  • dev07-5-1-ur6a subject with aspects renders one verdict per aspect and no aggregate; a single-field reader is held at unproven rather than shown an average
  • dev07-5-1-ur7the view narrows to a namespace and never the derivation: a story reads the same in every scope containing it, and run-level facts survive every scope
  • dev07-5-1-ur8the board is derived from however much the project has declared, and says what is missing — a project that declares nothing gets a partial answer, never an error
  • dev07-5-1-ur9the board's totals count stories by status, and a subject read per aspect is counted apart and never as unproven
What the system does
  • dev07-5-1-sr1rows sort by the natural order of the story ids
  • dev07-5-1-sr2how much the project has declared is worked out inside the step and never emitted — a completeness number would be a status about the project rather than about a claim
  • dev07-5-1-sr3the scope filter is a prefix match over ids the run observed; a mistyped scope reports an empty view rather than a refusal, and says that no observed id matched it
How well
  • dev07-5-1-nfr1the board is evidence a person acts on; it renders no opinion

dev07-5-2 surface what a check could not do Proven

As an adopter I want to be told what was skipped and what I would get by fixing it, so that nothing about my setup is silently absent.

The tests that cite it (36)
  • tests/test_board.py::test_the_board_says_what_it_could_not_check_and_names_the_code — passed, ungrounded
  • tests/test_board.py::test_an_unknown_code_still_emits_rather_than_vanishing — passed, ungrounded
  • tests/test_board.py::test_what_the_board_can_say_is_a_list_not_an_open_question — passed, untouched
  • tests/test_board.py::test_the_board_surfaces_what_the_next_step_would_unlock — passed, ungrounded
  • tests/test_board.py::test_a_step_already_taken_is_no_longer_offered — passed, ungrounded
  • tests/test_board.py::test_an_empty_run_advertises_nothing — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations0-best-unproven-silent] — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations1-best-proven-holding] — passed, ungrounded
  • tests/test_board.py::test_a_subject_says_its_status_in_its_own_vocabulary[citations2-worst-unproven-breached] — passed, ungrounded
  • tests/test_board.py::test_a_lexicon_with_no_word_for_a_state_says_the_state_rather_than_inventing_one — passed, ungrounded
  • tests/test_board.py::test_a_session_that_never_finished_is_not_a_run_that_observed_nothing — passed, ungrounded
  • tests/test_board.py::test_a_run_that_observed_nothing_is_not_a_board_with_no_stories — passed, ungrounded
  • tests/test_board.py::test_the_run_level_condition_carries_a_code_and_all_three_parts — passed, ungrounded
  • tests/test_board.py::test_the_run_level_condition_carries_a_code_and_all_three_parts — passed, ungrounded
  • tests/test_board.py::test_an_adapter_that_could_not_count_raises_no_alarm — passed, ungrounded
  • tests/test_board.py::test_the_board_carries_the_extent_it_drew_the_condition_from — passed, ungrounded
  • tests/test_board.py::test_every_condition_a_subject_can_carry_resolves_to_its_prose — passed, ungrounded
  • tests/test_board.py::test_a_cited_story_that_passed_and_is_still_unproven_says_which_reason — passed, ungrounded
  • tests/test_board.py::test_the_advice_says_which_branch_advances_the_story_and_which_only_ends_the_complaint — passed, ungrounded
  • tests/test_board.py::test_lowering_a_depth_ends_the_complaint_and_leaves_the_reason_standing — passed, ungrounded
  • tests/test_board.py::test_a_scope_narrows_the_verdicts_and_never_the_run_level_facts — passed, ungrounded
  • tests/test_docs_match_the_tool.py::test_every_condition_code_the_board_can_emit_is_documented — passed, untouched
  • tests/test_end_to_end.py::test_with_no_entry_points_declared_the_board_says_so — passed, grounded
  • tests/test_end_to_end.py::test_the_emitted_board_carries_evidence_and_its_own_next_step — passed, grounded
  • tests/test_end_to_end.py::test_the_emitted_board_carries_evidence_and_its_own_next_step — passed, grounded
  • tests/test_end_to_end.py::test_a_run_that_observed_nothing_fails_the_step — passed, grounded
  • tests/test_end_to_end.py::test_a_suite_that_cites_nothing_yet_is_a_correct_first_run — passed, grounded
  • tests/test_end_to_end.py::test_a_suite_that_cites_nothing_yet_is_a_correct_first_run — passed, grounded
  • tests/test_end_to_end.py::test_a_condition_names_what_it_is_about — passed, grounded
  • tests/test_end_to_end.py::test_the_text_board_says_an_adapter_ran_blind_as_the_json_does — passed, grounded
  • tests/test_gate.py::test_the_same_citations_reduce_two_ways_and_the_rank_is_the_only_difference[best-proven] — passed, ungrounded
  • tests/test_gate.py::test_the_same_citations_reduce_two_ways_and_the_rank_is_the_only_difference[worst-unproven] — passed, ungrounded
  • tests/test_gate.py::test_a_failing_citation_takes_part_in_the_reduction_rather_than_being_removed_from_it — passed, untouched
  • tests/test_gate.py::test_unproven_says_which_of_its_three_reasons_it_is[citations0-evidence.none] — passed, ungrounded
  • tests/test_gate.py::test_unproven_says_which_of_its_three_reasons_it_is[citations1-evidence.failed] — passed, ungrounded
  • tests/test_gate.py::test_unproven_says_which_of_its_three_reasons_it_is[citations2-evidence.not-observed] — passed, ungrounded
Requirements (14)
What the user needs
  • dev07-5-2-ur01nothing is silently skipped: what a check could not do is surfaced with what would make it possible
  • dev07-5-2-ur02every condition carries a stable code beside its prose, from a finite set; a consumer branches on the code and never on a sentence somebody will improve
  • dev07-5-2-ur03the prose is three separately-renderable parts — the diagnosis, the instruction, the example — and an example is the part advice cannot act without
  • dev07-5-2-ur04every code resolves to its prose locally, wherever it was defined — a board explains itself where there is no network
  • dev07-5-2-ur05a code this build has never seen still emits rather than vanishing
  • dev07-5-2-ur06a passing citation that still did not prove says which of the three reasons: never reached the wired system, executed nothing at all, or executed what a structural claim needed read
  • dev07-5-2-ur07the advice says which branch advances the story and which only ends the complaint
  • dev07-5-2-ur08a run that observed nothing is its own run-level condition, never a board with no stories, because an empty board is also what a correct first run looks like
  • dev07-5-2-ur09a run that saw tests and read no citation is its own condition; it does not guess which cause, and it does not fail the run — a project between init and its first citation is doing the tutorial in order
  • dev07-5-2-ur10an internal error of the runner is never reported as the project's fault
  • dev07-5-2-ur11an unlock is counted from the run's own output and withdrawn once the source already carries the fact; an empty run advertises nothing
  • dev07-5-2-ur12a condition names the subjects it is about, and the evidence names the test that raised it, so a reader with fifty stories is never left to find which one
What the system does
  • dev07-5-2-sr1every code a build can emit resolves to its prose; what is guaranteed is that it resolves, never that all three parts are written
  • dev07-5-2-sr2every condition code and every exit code the board can emit is documented

dev07-5-3 emit the board Proven

As somebody building on plumb's output I want to read the board without knowing plumb's internals, so that consuming it is a parse rather than an integration.

The tests that cite it (14)
  • tests/test_board.py::test_the_board_emits_a_neutral_json_any_tool_can_read — passed, ungrounded
  • tests/test_board.py::test_the_emitted_format_carries_its_version — passed, ungrounded
  • tests/test_board.py::test_the_boards_version_is_its_own_not_the_manifests — passed, ungrounded
  • tests/test_board.py::test_an_aborted_session_cannot_board_rather_than_observing_nothing — passed, untouched
  • tests/test_board.py::test_the_board_says_what_rendered_it_and_when_and_keeps_measurement_on_the_fact — passed, ungrounded
  • tests/test_board.py::test_the_core_is_told_what_rendered_the_board_rather_than_reading_it — passed, ungrounded
  • tests/test_docs_match_the_tool.py::test_every_exit_code_is_documented_with_its_number — passed, untouched
  • tests/test_end_to_end.py::test_the_board_comes_out_of_the_command_line — passed, grounded
  • tests/test_end_to_end.py::test_the_board_comes_out_of_the_command_line — passed, grounded
  • tests/test_end_to_end.py::test_plumb_runs_the_whole_graph_on_a_project_it_has_never_seen — passed, grounded
  • tests/test_end_to_end.py::test_a_run_that_observed_nothing_fails_the_step — passed, grounded
  • tests/test_end_to_end.py::test_unproven_stories_are_not_a_failure — passed, grounded
  • tests/test_end_to_end.py::test_a_suite_that_cites_nothing_yet_is_a_correct_first_run — passed, grounded
  • tests/test_end_to_end.py::test_every_shape_the_rendered_board_prints_is_exercised — passed, grounded
Requirements (11)
What the user needs
  • dev07-5-3-ur1a consumer reading the board reads the board and nothing else; the runner's own messages never mix into it
  • dev07-5-3-ur2the board versions apart from the manifest — an internal refactor never reaches a consumer who pinned
  • dev07-5-3-ur3a breaking change is a new version and never a silent shift, symmetric with the inbound edge
  • dev07-5-3-ur4the board stamps what rendered it and when — render time, and never a measurement time, which stays on each fact
  • dev07-5-3-ur5the exit code reports whether a board was derived, never whether it is proven: an all-unproven board exits zero, and the runner's own failing suite is the runner's exit to give
  • dev07-5-3-ur6an aborted run cannot board — a run that never finished is not a run that observed nothing
  • dev07-5-3-ur7nothing a run finds fails or halts it: every finding is on the board, the way a test report reports, so a pipeline decides what to do about it
What the system does
  • dev07-5-3-sr1the page a person reads is what a run gives by default; the machine-readable format is given when it is asked for
  • dev07-5-3-sr2a translation into a platform's own envelope is given only when asked for, sits outside the core, and never changes the format it translates
How well
  • dev07-5-3-nfr1no shape the board can take is lost from the page a person reads — a person is that page's only reader, and a shape can vanish from it while the machine-readable board stays identical
Still open
  • dev07-5-3-u1whether and how the board is published beyond the desk — a dashboard, a shared place — without making CI the gate is a distribution question, opt-in

← Every chapter