Plumb

Specification

dev00-1 · bring plumb to a project

What a team does to get plumb, point it at their project, and keep the install accounted for — without ever reading plumb's repository. Exits to A developer's workflow, handing over the project's declaration the workflow runs on. The channel, artifact and release statement it consumes are produced by whoever publishes the tool, and arrive here already made.

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

dev00-1-1 install the tool from a channel Unproven

As a team with no access to plumb's repository I want to install it anyway, so that the tool's claims are true for people who are not already inside it.

the citations that passed reached nothing wired — what ran was the implementation on its own, which is not evidence the story holds where it is used

the citing test neither ran the production artifact nor read it, so nothing it did is evidence about the subject it names

The tests that cite it (15)
  • tests/test_adoption.py::test_a_java_project_is_told_exactly_what_to_paste — passed, ungrounded
  • tests/test_adoption.py::test_a_java_project_is_told_exactly_what_to_paste — passed, ungrounded
  • tests/test_adoption.py::test_nothing_is_written_into_a_java_project_beyond_its_config — passed, ungrounded
  • tests/test_adoption.py::test_the_installed_artifact_says_which_version_it_is — passed, ungrounded
  • tests/test_adoption.py::test_a_missing_adapter_names_plumbs_install_and_not_the_project — passed, ungrounded
  • tests/test_adoption.py::test_a_project_supplying_the_adapter_itself_is_not_refused — passed, ungrounded
  • tests/test_artifact.py::test_the_bundled_vocabulary_is_the_one_published_to_maven_central — passed, untouched
  • tests/test_docs_match_the_tool.py::test_every_flag_the_tool_accepts_is_in_the_reference — passed, ungrounded
  • tests/test_docs_match_the_tool.py::test_no_flag_any_page_documents_has_been_removed_from_the_tool — passed, ungrounded
  • tests/test_docs_match_the_tool.py::test_every_subcommand_is_in_the_reference — passed, ungrounded
  • tests/test_docs_match_the_tool.py::test_every_condition_code_the_board_can_emit_is_documented — passed, untouched
  • tests/test_docs_match_the_tool.py::test_every_exit_code_is_documented_with_its_number — passed, untouched
  • tests/test_docs_match_the_tool.py::test_both_adapters_declare_the_manifest_shape_the_contract_documents — passed, untouched
  • tests/test_docs_match_the_tool.py::test_help_speaks_to_its_reader_and_never_cites_the_spec — passed, ungrounded
  • tests/test_docs_match_the_tool.py::test_the_holder_s_help_shows_the_bounds_it_enforces_and_their_defaults — passed, ungrounded
Requirements (13)
What the user needs
  • dev00-1-1-ur1installing runs from a built artifact, and never requires reading, cloning or reaching plumb's source
  • dev00-1-1-ur2one artifact carries every adapter it supports
  • dev00-1-1-ur3which verification ran is said; one is skipped only when the adopter asks for that by name, and an emptied key fingerprint is refused by name rather than replaced
  • dev00-1-1-ur4a contradiction — a verified signature and no signature at once — is refused rather than resolved
  • dev00-1-1-ur5the installed artifact names the version it was built as, out of itself
  • dev00-1-1-ur6the channel is a property of the install, written down when it is resolved
  • dev00-1-1-ur7when the tool cannot supply machinery it ships, it refuses first, names its own install as the fault, and says how to repair it
What the system does
  • dev00-1-1-sr1the citation vocabulary ships as its own artifact — minimal, dependency-free, stable across releases
  • dev00-1-1-sr2an install that stops part-way leaves nothing of its download behind
  • dev00-1-1-sr3every shipped document is reachable from one index and leads with what the reader gets
How well
  • dev00-1-1-nfr1the checksum runs always and the signature runs when it can; silence about not checking is worse
  • dev00-1-1-nfr2every command the install offers is the adopter's to perform
Still open
  • dev00-1-1-u1how the tool is present for a build nobody installed it on — CI that provisions from nothing — is undecided

dev00-1-2 declare the project to it Proven

As a team adopting plumb I want adopting to write exactly one file into my repository, so that adopting a verifier is not adopting somebody's workflow.

The tests that cite it (10)
  • tests/test_adoption.py::test_adoption_writes_what_is_missing_and_keeps_what_is_there — passed, ungrounded
  • tests/test_adoption.py::test_what_it_writes_is_a_config_the_tool_can_actually_read — passed, ungrounded
  • tests/test_adoption.py::test_the_written_config_carries_no_note_that_acting_on_it_makes_false — passed, ungrounded
  • tests/test_adoption.py::test_the_sources_comment_says_which_language_reads_it — passed, grounded
  • tests/test_artifact.py::test_both_adapters_are_handed_the_same_resolved_facts — passed, ungrounded
  • tests/test_config.py::test_a_project_declares_itself_in_one_file_whatever_language_it_is — passed, ungrounded
  • tests/test_config.py::test_the_declared_values_stay_in_the_adapters_own_spelling — passed, ungrounded
  • tests/test_end_to_end.py::test_adoption_is_one_command_one_file_and_then_a_board — passed, grounded
  • tests/test_end_to_end.py::test_a_setting_the_run_cannot_use_is_named_and_the_run_carries_on[endpoint = "https://example.invalid"\n-`endpoint`] — passed, grounded
  • tests/test_end_to_end.py::test_a_setting_the_run_cannot_use_is_named_and_the_run_carries_on[[java]\nspecs = ["APP"]\n-`specs` is written inside [java]] — passed, grounded
Requirements (8)
What the user needs
  • dev00-1-2-ur1one project declaration and one command, whatever the project is written in
  • dev00-1-2-ur2adopting writes the project's declaration and nothing else
  • dev00-1-2-ur3what is missing is written, what is there is kept, and the run reports both
  • dev00-1-2-ur4a file the tool wrote once belongs to the project the moment it lands
  • dev00-1-2-ur5the project's declaration carries the version that wrote it
  • dev00-1-2-ur6a setting the run cannot use where it is written — a key filed under the wrong section, an address, a declaration left in a file no longer read — is named on the board and the run carries on; only a declaration that cannot be read at all leaves no board
What the system does
  • dev00-1-2-sr1every adapter is handed values already resolved and reads no configuration format of its own
Still open
  • dev00-1-2-u1whether a project authoring a spec is any of this tool's business is undecided; nothing blocks a project that keeps none

dev00-1-3 take the named next step Unproven

As an adopter with a config file and no idea what to do with it I want the concrete next command, so that I can continue on my own.

the citations that passed reached nothing wired — what ran was the implementation on its own, which is not evidence the story holds where it is used

The tests that cite it (3)
  • tests/test_adoption.py::test_adoption_ends_by_saying_what_to_do_next_in_commands — passed, ungrounded
  • tests/test_adoption.py::test_a_python_project_is_told_python_things — passed, ungrounded
  • tests/test_adoption.py::test_what_it_could_not_work_out_is_said_rather_than_guessed — passed, ungrounded
Requirements (3)
What the user needs
  • dev00-1-3-ur1the last thing an adopter is told is the concrete next action, in commands
  • dev00-1-3-ur2the next step teaches no method
Still open
  • dev00-1-3-u1what a citing test is when the artifact is a decision — a document, not code — is undecided

dev00-1-4 account for what the tool wrote Proven

As an adopter deciding what to back up, carry or delete I want the tool to hold that list, so that answering it never means reading somebody's source.

The tests that cite it (5)
  • tests/test_sessions.py::test_every_place_the_tool_writes_is_in_the_documented_inventory — passed, ungrounded
  • tests/test_sessions.py::test_the_footprint_is_printed_with_the_paths_this_machine_actually_uses — passed, grounded
  • tests/test_sessions.py::test_the_inventory_says_what_losing_each_place_would_cost — passed, ungrounded
  • tests/test_sessions.py::test_the_footprint_says_which_places_exist_and_names_this_project_s_cache — passed, grounded
  • tests/test_sessions.py::test_the_sent_mark_says_what_losing_it_costs_without_claiming_the_holder_dedupes — passed, ungrounded
Requirements (9)
What the user needs
  • dev00-1-4-ur1an upgrade stays on the stream the install was on, decided against the statement of what changed
  • dev00-1-4-ur2every footprint entry carries a disposition: rebuilds itself, the repository has it, this project's alone, or carries a credential
  • dev00-1-4-ur3the list names which entries nothing else holds, so somebody can decide what to protect without reading the source
  • dev00-1-4-ur4each entry says whether it is on this machine now, and an entry kept per project names this project's own path, so the list describes this machine rather than the manual
What the system does
  • dev00-1-4-sr1the footprint the tool reports and the one its documentation shows are one list, never two kept in step
How well
  • dev00-1-4-nfr1the tool lists what it wrote and never archives, copies or deletes it on the adopter's behalf
  • dev00-1-4-nfr2into the repository the tool writes only the project's declaration, the session cursor and, where the project keeps one, a series
  • dev00-1-4-nfr3a disposition states what an entry is and never what to do about it; what follows from it is the adopter's to judge
Still open
  • dev00-1-4-u1whether the list should be emitted in a form another tool consumes rather than read by a person is undecided; the answer decides whether point your backup at these is a sentence or an integration

dev00-1-5 add a module Proven

As an adopter whose team needs a capability plumb lacks I want to install a module by the ordinary package gesture, so that the one CLI grows the verb and nothing else changes.

The tests that cite it (1)
  • tests/test_modules.py::test_the_command_prints_what_modules_declared — passed, grounded
Requirements (13)
What the user needs
  • dev00-1-5-ur1the module's verbs appear in the one CLI, and the tool lists every mounted module and its version
  • dev00-1-5-ur2a module that fails to import is named as an install fault, never silently absent
  • dev00-1-5-ur3a module the mount refuses, on the grounds in dev08-1-2-ur1 and dev08-1-2-ur5, is named whenever its verb is invoked and is never silently absent
  • dev00-1-5-ur4a module speaking a surface version the core does not is refused by name, with what the core speaks
  • dev00-1-5-ur5the module's declared footprint joins the tool's
  • dev00-1-5-ur6a module reaches an adopter carried inside the artifact they installed or installed separately beside it, and both mount by the module's declaration; what enables one is the name its package registers and never where its code came from
What the system does
  • dev00-1-5-sr1installing a module is the whole of enabling it: the tool mounts what the installed package declares (dev08-1-4-ur1), and there is no second switch
  • dev00-1-5-sr2an artifact that carries a module carries what discovery reads, so a channel that delivers the tool delivers its modules mounted
How well
  • dev00-1-5-nfr1installing a module is the trust decision, made on the verbs, writes and reach its declaration states (dev08-1-2)
  • dev00-1-5-nfr2the core's own gates run with no modules mounted
Still open
  • dev00-1-5-u1whether an adopter should be able to tell a module carried in the artifact from one installed beside it is undecided; where did this come from is the first question anybody asks when one needs replacing
  • dev00-1-5-u2whether the tool should ever look for a newer core or module is undecided, and it is a decision about the guarantee rather than about convenience: a check is a network call in a tool whose promise is that it transmits nothing unless a destination is named. The candidates are refusing precisely and leaving the fetching to whoever packages, or an opt-in check as explicit as enrolment
  • dev00-1-5-u3where an adopter obtains a newer module is answered nowhere; the mount refuses a version it cannot speak and says what it speaks, which tells somebody they are stuck without telling them where to go

← Every chapter