Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions config/feed.json
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,14 @@
"close"
]
},
{
"reason": "path_needs_person",
"question": "a_path_needs_you",
"choices": [
"approve",
"close"
]
},
{
"reason": "contract_not_approved",
"question": "contract_needs_approval",
Expand Down
22 changes: 16 additions & 6 deletions controller/configuration.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,25 @@ def _readable(root: pathlib.Path, *parts):


def kernel(root: pathlib.Path) -> dict:
"""The Kernel's configuration as its tests give it: the defaults, and the protected paths and the model Lenses'
inputs, from the one list the session hooks read too."""
held = dict(_json(root, "config", "defaults.json"),
protected_paths=protected.protected_paths(root / "config" / "hooks.json"))
held["model_lens_inputs"] = protected.model_lens_inputs(held["required_lenses"]["model"],
root / "config" / "hooks.json")
"""The Kernel's configuration as its tests give it: the defaults, and the protected paths, the model Lenses'
inputs and the paths only a person decides, from the one list the session hooks read too, read once."""
hooks = protected.load(root / "config" / "hooks.json")
held = dict(_json(root, "config", "defaults.json"), protected_paths=protected.protected_of(hooks))
held["model_lens_inputs"] = protected.model_inputs_of(hooks, held["required_lenses"]["model"])
held["person_only_paths"] = person_only(hooks, held["required_lenses"]["model"])
return held


def person_only(hooks: dict, models: list) -> list:
"""What the Kernel is given as `person_only_paths`, of `hooks`, a reading of `config/hooks.json` by
`tools/hooks/protected.py`: each path only a person decides that no Lens of `models`, the model Lenses, reads,
once, in the file's order. By this list the Kernel names the wait `path_needs_person`, so a path that is a model
Lens's own input as well is left off it: its change waits as a Lens's input does, the stricter name, and is never
passed off as a person's path alone (decision 0207)."""
own = [path for lens, path, _ in hooks["lens_inputs"] if lens in models]
return [path for path in dict.fromkeys(path for path, _ in hooks["person_only"]) if path not in own]
Comment thread
don-petry marked this conversation as resolved.
Resolved


def load(root: pathlib.Path, release: str, app: str) -> dict:
"""`kernel`, `release`, `controller`, `feed` and `lifecycles`, as `pass_.run` takes them, and `app` and `needs`,
the App the reads go through and the needs it is granted under, `apps`, every App by its Role's name, and
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# 0207. A change that touches only paths a person decides waits under its own code
Comment thread
don-petry marked this conversation as resolved.
Resolved

Status: accepted. Decided for "The reason a person-only path waits is named for itself, not as a model Lens's input" (issue 746). It amends two rows of `docs/decisions/0200-a-path-only-a-person-decides-is-listed-apart-from-a-lenss-inputs-and-a-change-to-it-needs-a-persons-approval.md`. "The code it waits in" kept `model_lens_input_needs_person` for a person-only path; for a change that touches no model Lens's input it no longer does. "How the Kernel is told" said the Kernel changes by no line; it now reads a second list. The rest of both rows stands, and so does every other row of 0200.

## Decision

| What | Decided | Because |
|---|---|---|
| The code | A change waits in `verifying` as `path_needs_person` where every path it touches, of the two lists below, is one only a person decides. The evidence names each such path as the configuration has it, once | No Lens reads such a path, and the code a person is shown said one did. The wait and who ends it were already right |
| Beside a model Lens's input | A change that touches a model Lens's input as well keeps `model_lens_input_needs_person`. Its evidence names every path of either list that it touches, the Lenses' inputs first, each once | A Decision has one reason. Of the two, the Lens's says that what judges a change has itself changed, which is the more a person must know; the path stands beside it in the evidence |
| Who ends the wait | As 0052 and 0200 have it, for both codes: a person with write access other than the author and the last pusher approves the head. One approval ends both. In the merge queue without one the change is taken out | Only the name changes |
| How the Kernel is told | It is given a second list, `person_only_paths`: each path of `person_only` in `config/hooks.json` that no model Lens reads, once, from the one reading `tools/hooks/protected.py` makes of that file. `controller/configuration.py::person_only` builds it, for the Controller, the simulator and the tests alike, and the Controller takes all three of its lists from one reading. `model_lens_inputs` is given as 0200 has it, the person-only paths after a model Lens's own | `tools/hooks/protected.py` and `config/hooks.json` are a model Lens's inputs, and neither changes here: the reading already returns both lists. One function for the three that tell a Kernel leaves nothing to drift |
| The Kernel's two lists | The two lists the Kernel is given overlap by design: `model_lens_inputs` holds every person-only path at its end (0200), so each is on both. The Kernel therefore takes a path for a person's by `person_only_paths` alone, and for a model Lens's input where it is on `model_lens_inputs` and not on that list. A path on `person_only_paths` waits for a person even were `model_lens_inputs` given without it. What keeps a model Lens's own input off `person_only_paths` is the next row | Were the two ever given apart, the wait must not be lost with the name, and a list that leaves a path out errs to the Lens's code, the stricter |
| A path on both lists of `config/hooks.json` | No path is listed there both as a model Lens's input and as a person's today. Were one, it is left off `person_only_paths`, so a change to it waits as `model_lens_input_needs_person` | A model Lens's input is the stricter and the more specific reason (0052), and is never to be masked by the other (the Factory Builder's ruling of 2026-11-13) |
| A list that cannot be read | `person_only_paths` not there, or not a list of patterns in the shape every path has, is `protected_paths_unreadable`: the item defers for the Maintainer, and leaves the merge queue. A list that names none is read | A configuration from before 0200 names none. One that says nothing of the list could be hiding one, and a fact that cannot be read is never taken for its default (I-13) |
| What a person is asked | `config/feed.json` gains the row `path_needs_person`: the question `a_path_needs_you`, and the choices of a model Lens's input, approve or close | `tools/check_examples.py` asks a row of every reason that needs a person |
| What is still not held | That a model Lens's input is never named a person's path rests on `controller/configuration.py`, its test and its mutants. That file is neither a protected path nor a model Lens's input, so a later change to it alone is judged by the model Lens, with no person's approval. Only the name and the question asked could be lost that way, never the wait or who ends it. Whether the file is to be listed as one a person must approve is a separate decision, not made here | This repo holds a rule by its test and its mutants, and this one is held so (the Factory Builder's ruling of 2026-11-13). Listing the file is a change to `config/hooks.json`, by the Maintainer's hand |
| From when | From the first Release cut after this record merges. Until then the Release on `next` names the wait as 0200 has it | The Kernel and the Controller that tells it ride one Release |

## Why

0200 put the Maintainer's decision file under the rule for a model Lens's input without a new rule in the Kernel, and said plainly that the code was then narrower than what it held. The person who must act reads the code and the question it maps to, and both told him a Lens's input had changed when none had. The Kernel already matched the change against the list; it needed only to be told which of those paths are a person's.

## Boundaries

| Boundary | Check |
|---|---|
| A change that touches only person-only paths waits for a person as `path_needs_person`, of any class and the Maintainer's own, with the path as evidence; it needs a person's eyes; in the merge queue without one it is taken out; either list alone holds the wait and the person-only list names it; the feed asks under the path's own question with the choices of a model Lens's input; and the Decision's example is the Kernel's own | `tests/test_decide.py::test_a_change_to_a_path_only_a_person_decides_waits_for_a_person`, `kernel/derive.py`, `kernel/decide.py`, `config/feed.json`, `examples/decision.path-needs-person.json`; mutant: "a change to a person-only path alone is named a model Lens's input"; mutant: "a person-only path off the model Lenses' list waits for no one"; mutant: "a rename out of a person-only path is not read"; mutant: "a person-only path is matched as a whole name, never as a pattern"; mutant: "a change to a person-only path is nobody's to see"; mutant: "the feed asks of a person-only path what it asks of a model Lens's input"; mutant: "the feed offers a person no approval of a change to a person-only path"; mutant: "the example of a person-only path's Decision is a model Lens's input's" |
| Beside a model Lens's input the change keeps `model_lens_input_needs_person`, in the queue too, with every touched path of either list as evidence, the Lenses' first and each once; one person's approval ends both waits; and a model Lens's input alone is never named a person's path, nor is a path the change leaves alone named | `tests/test_decide.py::test_the_wait_is_named_for_a_model_lenss_input_wherever_the_change_touches_one`, `tests/test_decide.py::test_a_change_to_a_model_lenss_own_input_waits_for_a_person`, `kernel/derive.py`; mutant: "a change to a model Lens's input beside a person-only path is named for the path"; mutant: "a change to a model Lens's input is named a person-only path"; mutant: "a path on both lists is named in the evidence twice"; mutant: "a model Lens's input beside a person-only path off its list is dropped, and the change named for the path"; mutant: "a person-only path is named in the evidence before a model Lens's input"; mutant: "a person-only path off the model Lenses' list is left out of the evidence beside a Lens's input"; mutant: "a person-only path named twice is in the evidence twice"; mutant: "every person-only path is taken as changed" |
| A list of person-only paths that is not there, is no list, or holds a pattern of no readable shape defers for the Maintainer as `protected_paths_unreadable` and leaves the queue; a list that names none is read | `tests/test_decide.py::test_an_unreadable_list_of_person_only_paths_defers_for_the_maintainer`, `kernel/derive.py`; mutant: "a list of person-only paths that is not there is read as none"; mutant: "a list of person-only paths that is no list is read"; mutant: "a person-only path of no readable shape is read"; mutant: "a configuration that names no person-only path cannot be read" |
| The Controller gives the Kernel the person-only paths of the checkout it runs from, each once, and none where the file has no such list | `tests/test_controller.py::test_the_kernel_is_given_the_paths_only_a_person_decides_from_the_releases_own_list`, `controller/configuration.py`; mutant: "the Controller gives the Kernel no person-only path"; mutant: "the Controller gives the Kernel the lists of the session's checkout, not the Release's"; mutant: "the Controller leaves no model Lens's input off the person-only paths" |
| A path a model Lens reads is left off the person-only paths, whoever lists it as a person's, so its change waits as a Lens's input does; a path only a deterministic Lens reads is not left off; and no path is on both lists today | `tests/test_controller.py::test_a_path_a_model_lens_reads_is_never_given_as_a_persons_alone`, `controller/configuration.py`; mutant: "a path a model Lens reads is given to the Kernel as a person's alone"; mutant: "a path any Lens reads is left off the person-only paths"; mutant: "a person-only path listed twice is given to the Kernel twice" |
| The tests' Kernel and the simulator's are given the same list, as `config/hooks.json` has it | `tests/test_tools.py::test_the_kernel_is_given_the_paths_only_a_person_decides`, `sim/world.py`; mutant: "the simulator's Kernel is given no person-only path" |
| Every reason that needs a person has its row in the feed | `tests/test_tools.py::test_every_reason_that_needs_a_person_says_what_is_asked`, `config/feed.json`; mutant: "the feed asks nothing of a change to a person-only path" |
15 changes: 15 additions & 0 deletions examples/decision.path-needs-person.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"schema": "decision/1",
"item": {
"repo": "combsmith/software-factory",
"type": "pull_request",
"number": 42
},
"state": "verifying",
"reason": "path_needs_person",
"evidence": [
"release/decision-points.json"
],
"attention": "needs_you",
"outcome": "nothing"
}
1 change: 1 addition & 0 deletions kernel/decide.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
"contract_not_approved", "contract_changed", "acceptance_reporters_unreadable",
"run_unreadable", "model_lens_input_needs_person",
"description_edited_after_approval", "description_unreadable",
"path_needs_person",
})


Expand Down
21 changes: 19 additions & 2 deletions kernel/derive.py
Original file line number Diff line number Diff line change
Expand Up @@ -333,9 +333,12 @@ def readable_rules(config: dict) -> bool:
among them: each a list of at least one pattern, each in its shape (readable_pattern). The Controller builds both
from the base branch's config/hooks.json, never the head's, by one function (decision 0020, issue 140). A list that
is empty, or not there, would let a change to the Factory's own rules, or to what a model Lens is given, pass as any
other (I-13)."""
other (I-13). And the paths only a person decides, by which that wait is named (decision 0207): a list of patterns
in the same shape, which may name none, and is never taken as none where it is not there."""
persons = config.get("person_only_paths")
return all(isinstance(rules, list) and len(rules) > 0 and all(readable_pattern(p) for p in rules)
for rules in (config.get("protected_paths"), config.get("model_lens_inputs")))
for rules in (config.get("protected_paths"), config.get("model_lens_inputs"))) \
and isinstance(persons, list) and all(readable_pattern(p) for p in persons)
Comment thread
don-petry marked this conversation as resolved.
Resolved


def fits(pattern: str, path: str) -> bool:
Expand Down Expand Up @@ -414,6 +417,13 @@ def lens_inputs_touched(facts: dict, config: dict) -> list:
return [p for p in dict.fromkeys(config["model_lens_inputs"]) if any(matches(p, path) for path in changed)]


def person_only_touched(facts: dict, config: dict) -> list:
"""Each path only a person decides that this pull request changes, as the configuration names it, once, in its
order: no Lens reads one, and a person's approval is the only judgement of it (decisions 0200 and 0207)."""
changed = names(facts["changed_paths"])
return [p for p in dict.fromkeys(config["person_only_paths"]) if any(matches(p, path) for path in changed)]


def judged_by_a_person(facts: dict) -> bool:
"""Whether a person has judged this head, so that no model Lens is the only judge of a change to its own inputs: an
approval of this content that stands, by a person with write access other than its author and its last pusher
Expand Down Expand Up @@ -1335,8 +1345,15 @@ def reading(facts: dict, runs: list, config: dict, past: tuple) -> dict:

# A change to a model Lens's own inputs needs a person as well as every model Lens's review: with one model family,
# the only judge that is not the Lens is a person (issue 140). It is no wait a queued item is read past.
# So does a change to a path only a person decides, which no Lens reads (decision 0200). Where such paths are all
# the change touches of either list, the wait is named for itself; beside a model Lens's input it keeps the
# Lens's code (decision 0207).
alone = person_only_touched(facts, config)
own = lens_inputs_touched(facts, config)
own = own + [p for p in alone if p not in own]
if own and not judged_by_a_person(facts):
if all(p in alone for p in own):
return {"state": t.VERIFYING, "reason": "path_needs_person", "evidence": own}
return {"state": t.VERIFYING, "reason": "model_lens_input_needs_person", "evidence": own}

# GitHub does not count an approval by the author or the last pusher, so nothing may merge on one (I-26). It is
Expand Down
4 changes: 3 additions & 1 deletion sim/world.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
import pathlib
import random

from controller import configuration
from kernel import terms as t
from kernel.decide import decide, stuck_runs
from tools import check_lifecycle
Expand All @@ -20,10 +21,11 @@

ROOT = pathlib.Path(__file__).resolve().parent.parent
# The Kernel is given the defaults, the Lifecycle whose staleness limits it reads, and the protected paths and Lenses'
# inputs from config/hooks.json.
# inputs from config/hooks.json, and which of them only a person decides, as the Controller gives it them.
CONFIG = dict(json.loads((ROOT / "config" / "defaults.json").read_text()), lifecycle=check_lifecycle.load(),
protected_paths=protected.protected_paths())
CONFIG["model_lens_inputs"] = protected.model_lens_inputs(CONFIG["required_lenses"]["model"])
CONFIG["person_only_paths"] = configuration.person_only(protected.load(), CONFIG["required_lenses"]["model"])
# The world models the Factory once its author Role exists, as the authority table names it: the live configuration
# names none until roles/dev-lead.json does, and defers each fix to a person meanwhile (issue 675).
CONFIG["author_role"] = json.loads((ROOT / "config" / "authority.json").read_text())["author_role"]
Expand Down
3 changes: 3 additions & 0 deletions tests/support.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import time
import unittest

from controller import configuration
from tools.hooks import protected

ROOT = pathlib.Path(__file__).resolve().parent.parent
Expand All @@ -21,6 +22,8 @@
# configuration names none until that Role has its manifest under roles/ (issue 675).
CONFIG["author_role"] = json.loads((ROOT / "config" / "authority.json").read_text())["author_role"]
CONFIG["model_lens_inputs"] = protected.model_lens_inputs(CONFIG["required_lenses"]["model"])
# Which of them only a person decides and no model Lens reads, by which the wait is named, as the Controller gives them.
CONFIG["person_only_paths"] = configuration.person_only(protected.load(), CONFIG["required_lenses"]["model"])
ITEM = {"repo": "combsmith/software-factory", "type": "pull_request", "number": 42}
NOW = "2026-10-11T13:00:00Z"
# Every required check passing, each under its check run's name as GitHub gives it, from its Lens's own App.
Expand Down
Loading
Loading