Skip to content

position and watch: the atomic units - #21

Merged
sam-aydlette merged 3 commits into
mainfrom
task/013-position-watch
Aug 31, 2026
Merged

sam-aydlette merged 3 commits into
mainfrom
task/013-position-watch

Conversation

@sam-aydlette

Copy link
Copy Markdown
Owner

Implements backlog/013. The first task that builds after the deletion. 554 tests (451 → 554), make check exit 0.

Both invariants hold at two independent layers

Invariant 2 — every Watch carries a so_what naming a decision. Verified independently at the loader and at the schema:

loader:  neutralise the guard -> 2 tests fail; restore -> 554 pass

raw SQL, bypassing the loader entirely:
  blank so_what -> CHECK constraint failed: ck_watches_so_what_present
  null  so_what -> NOT NULL constraint failed
  belief 1.5    -> CHECK constraint failed: ck_watches_belief_range
  rows stored: 0

Invariant 6 — the system never authors its own watches. watch offers list and sync, nothing else. sync reads the checked-in file. There is no create path, and a test fails if one is added.

triggers is compilable, not prose

This was the task's central design risk: the previous attempt at this idea accumulated prose where it needed structure, and 33 predictions were graded zero times as a result.

triggers:
  - entities: [FedRAMP PMO, GSA]
    terms: [continuous monitoring, ConMon, significant change]
  - sources: [Federal Register]
    terms: [FedRAMP]

A list of clauses over exactly terms, entities, sources — AND within a clause, OR across. Disjunctive normal form, stored as JSON.

It compiles because every axis is already a mechanic that survived task 012: terms and entities are word-boundary regexes from src/matching/entity_matcher.py (with its shouted-acronym case rules), sources is set membership over the producing adapter. Task 015 asks for "a deterministic predicate over entities, terms and source allowlists" — those are the three fields.

Prose is refused by name, citing the precedent:

'triggers' is prose. It must be a list of clauses over ['terms','entities','sources'], because Tier 1 compiles triggers into a deterministic predicate and cannot compile a sentence.

Nothing invalid is ever stored

29 parametrised rejections — empty / whitespace-only / absent / bare-prose so_what, unknown decision, belief out of range or prose, past or absent expiry, staleness 0 or negative, seven bad trigger shapes.

The structural detail that makes this real: the row-count assertion runs whether or not the loader raised. A loader that silently accepts fails on the count, not on a missing exception — testing for the absence of a row rather than the presence of an error.

The author ran mutation testing across ten guards, removing each in turn and counting failures. The reviewer corroborated seven of ten against the test code statically.

Decisions recorded, not assumed

Watch is a new table; Decision lives in Position under git, not the database. The old decisions/decision_factors tables were dropped at 0 rows by task 012, so there was nothing to evolve — and why they stayed empty (prose all the way down) is exactly why belief is a float and triggers is structured.

so_what is a key plus prose — {decision: <key into Position>, because: <sentence>}, both required. The key makes invariant 2 machine-checkable and "which watches serve this decision" a query; the prose makes the answer readable.

Position stays out of this repo. .gitignore refuses position.yaml and watches.yaml at both the root and config/; only the *.example.yaml files are tracked.

One reviewer finding, fixed

The caveat that sync_watches deletes rows for removed watches — and that task 017 will hang belief history off those rows, at which point a delete destroys calibration data — was disclosed only in the IC's report. Same failure as the cadence gap in task 011: a limitation that lives in a conversation is one nobody reads. It is now in sync_watches' docstring and in backlog/017's landmines, where the implementer who would destroy that history will actually be looking.

Known limits

  • The private Position repo does not exist yet; everything was exercised against fixtures and the checked-in examples. Paths and env vars work; pointing at the real repo is untested.
  • The two-page threshold (500 words/page, comments excluded) is a chosen number, not a validated one. It can only warn, so a wrong value costs a spurious warning.
  • _validate.py (385) and position.py (318) exceed the 200–300 guide. Split once along a real seam; further splitting would fragment the design rationale in the docstrings.

sam-aydlette and others added 3 commits August 31, 2026 11:49
Backlog task 013. Position holds the operator's decisions; a Watch is one
pre-registered claim serving one of them. Neither file is in this repo --
they name real decisions, deadlines and exposures, and this repo is public.
The loaders take configurable paths (POSITION_PATH / WATCHES_PATH) defaulting
to ~/.config/insightweaver/, .gitignore refuses a real position.yaml, and what
ships here is the schema plus config/{position,watches}.example.yaml.

Three shape decisions, recorded rather than discovered:

Watch is a new table, not an evolution of Decision + Factor. Task 012 dropped
decision_factors and decisions at 0 rows, so there was nothing left to evolve.
Decision lives in Position, not the database: it is an operator commitment in
a hand-edited file under git, not a row the system writes. One model of the
idea, not two.

so_what is a key plus prose. `decision` is a key into the Position's decisions
and `because` says what changes. The key makes invariant 2 machine-checkable;
an invariant enforced only by prose is what left 25 unfalsifiable predictions
in the deleted ledger.

triggers is structured and must stay so: a list of clauses over terms,
entities and source allowlists -- a disjunction of conjunctions Tier 1 can
compile to word-boundary regexes with no model involved. predictions.
trigger_condition was free text; 33 rows were written against it and graded
zero times, because nothing downstream can evaluate a sentence. A clause that
is a sentence is rejected by name.

Rejection is a claim about the table, so it is tested against the table: every
invalid watch asserts the row count is unchanged, and the assertion runs
whether or not the loader raised. Empty, whitespace-only and absent so_what,
an unknown decision, belief outside [0,1], a past expiry and staleness under
one day all refuse and store nothing; a file with one bad watch stores none of
its watches. Four CHECK constraints enforce the same invariants against raw
SQL, so a row inserted by hand fails the way a bad file does.

There is no `watch add` and there will not be one. It satisfies no acceptance
criterion and is the seam through which auto-generated watches arrive
(invariant 6). `watch sync` mirrors the files and takes no arguments; a test
asserts on the registered subcommands and their parameter lists.

staleness_alert_days accepts a cadence string via src/utils/cadence.py rather
than a second interval parser.

A Position over two pages warns loudly and still loads -- a three-page
Position of real deadlines beats a one-page Position of vague interests, so
length can only ever be a flag. Missing stakes and passed deadlines warn the
same way. Everything structurally checkable rejects.

554 tests pass, 103 of them new. Every enforcement above was verified by
mutation: removing it makes a named test fail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9gY2miAUXijbFm25YnFcq
watches.py had grown to 583 lines, past the 200-300 the repository asks for.
The split is along a real seam rather than a line count: _validate.py takes a
raw YAML value and either appends a sentence to `problems` or returns a clean
one, and touches neither the file system nor the database; watches.py owns the
loaded object, the file, and the sync.

validate_watch returns constructor keywords rather than a Watch. That keeps
the dependency one-way -- watches -> _validate -> position -- where returning
the type would have required _validate to import the module that imports it.
It also puts construction in the loader, which is the thing that admits a
watch; validation only decides whether it is admissible.

Pure move. 554 tests still pass, and the mutation checks still bite: removing
any one enforcement (so_what defaulting, an unknown decision tolerated, the
belief range, the past-expiry check, the staleness floor, prose triggers, or
the all-or-nothing raise) still fails a named test.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9gY2miAUXijbFm25YnFcq
The reviewer's one actionable finding: the caveat that sync_watches deletes
rows for removed watches, and that task 017 will hang belief history off those
rows, was disclosed only in the IC's report. That is the same failure as the
cadence gap in task 011 -- a limitation that lives in a conversation is one
nobody reads.

It is now in sync_watches' own docstring and in backlog/017's landmines,
which is where the implementer who would destroy calibration history will
actually be looking.
@sam-aydlette
sam-aydlette merged commit 56d6980 into main Aug 31, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant