# ThesisAnalysisOS: what still holds?

> An operating layer for research done with AI agents. Every result is kept with what it stood on, so it can be asked later whether it still holds.

Research keeps moving under its own results. A check that passed last month is a fact about last month. ThesisAnalysisOS keeps every result an agent records together with what it stood on, so it can be asked later whether it still stands. It answers `holds`, `fails`, `stale` or `unknown`, and says why.

- Repository: https://github.com/JustinBen0131/ThesisAnalysisOS
- Built from revision `a08b62374a15e107c43d5eded56af979a3ea495c` on 2026-11-22. Whether that still holds: compare `standing.json` with the repository.
- Python standard library only. No network and no model calls.

## A recorded run

Output of `./taos demo`, captured when this page was built. Six pendulum swings, a fit for g, a check.

### 1. A result is recorded

An agent runs the check and closes the task. The pass is stored with a fingerprint of the files the check depends on, and the closure with the instructions in force. Asked now, both hold. Read the last line too. A check passing is not a person accepting.

```text
$ taos gate run --task PEN-1 --agent codex
    ok    fit          exit 0
$ taos task transition PEN-1 --to done --agent codex --reason "g = 9.82 +/- 0.02 from six swings" --evidence analysis/fit.py
    PEN-1 -> done
$ taos why PEN-1
    PEN-1  done  Measure g from the six swings
    done when: the fit passes its check and g is quoted with its error
    holds    closure: codex moved it to done on 2026-11-22; the same instructions govern
    holds    check fit: passed 2026-11-22T01:51:29Z; nothing it tested has changed
    PEN-1 stands as recorded. No person has accepted it yet.
```

Code: `taos_core/gates.py`

### 2. Something else changes

The plot style is edited. The check never read it, so nothing is rerun and nothing is doubted. A rule that trusts results by age would have had to guess here.

```text
The plot style is edited. The check never read it.
$ taos why PEN-1
    holds    closure: codex moved it to done on 2026-11-22; the same instructions govern
    holds    check fit: passed 2026-11-22T01:51:29Z; nothing it tested has changed
    PEN-1 stands as recorded. No person has accepted it yet.
```

Code: `taos_core/basis.py`

### 3. An input changes

One swing is measured again. The old pass is still true about the old data. It no longer answers for the new data, so the answer is stale, and it names the file that moved.

```text
One swing is measured again, and data/swings.csv changes.
$ taos why PEN-1
    holds    closure: codex moved it to done on 2026-11-22; the same instructions govern
    stale    check fit: analysis changed: data/swings.csv
    PEN-1 does not stand as recorded: stale.
```

Code: `taos_core/basis.py`

### 4. A second task asks the same question

The check is run again on the new data. Then another agent's task needs the same check on the same files. A result belongs to the files it tested, not to the task that asked, so it is held and not run twice.

```text
$ taos gate run --task PEN-1 --agent codex
    ok    fit          exit 0
Another task needs the same check on the same files. It is not run twice.
$ taos gate run --task PEN-2 --agent claude
    held  fit          not rerun: nothing it tested has changed since 2026-11-22T01:51:30Z
```

Code: `taos_core/gates.py`

### 5. An instruction keeps its date

A person replaces an instruction. Both are kept, each with the day it was said, so what governed on any date can still be answered. Work closed under the old words is marked stale against the new ones, and the new ones are quoted as the person said them.

```text
$ taos rule add --quote "Use the tape-measured lengths" --said-on 2026-01-05 --scope PEN-1
    added rule_be342b850b for PEN-1
$ taos rule add --quote "Use the laser-measured lengths" --said-on 2026-03-01 --scope PEN-1 --supersedes rule_be342b850b
    added rule_cd4ec48565 for PEN-1
$ taos rule governing PEN-1 --on 2026-02-10
    rule_be342b850b  said 2026-01-05, no expiry, scope PEN-1
    "Use the tape-measured lengths"
$ taos rule governing PEN-1 --on 2026-03-02
    rule_cd4ec48565  said 2026-03-01, no expiry, scope PEN-1
    "Use the laser-measured lengths"
PEN-1 was closed before either instruction was recorded, and its closure says so.
$ taos why PEN-1
    stale    closure: codex moved it to done on 2026-11-22; the instructions have changed since: rule_cd4ec48565 governs now and is not one this was recorded under ("Use the laser-measured lengths", said 2026-03-01)
    holds    check fit: passed 2026-11-22T01:51:30Z; nothing it tested has changed
    PEN-1 does not stand as recorded: stale.
```

Code: `taos_core/rules.py`

### 6. Accepted means this version

A person reads the result and accepts it. That acceptance is for these exact files and instructions. A comment added afterwards does not inherit it.

```text
$ taos task accept PEN-1 --note "read the fit and the residuals"
    PEN-1 accepted by human, for the files and instructions as they are now
A comment is added to analysis/fit.py after the person looked.
$ taos why PEN-1
    stale    acceptance: human accepted it on 2026-11-22; since then analysis changed: analysis/fit.py
```

Code: `taos_core/tasks.py`

### 7. A check passes only on what it declared

A second check says it depends only on the analysis and quietly reads the figure style. Marked isolated, it runs in an empty folder that holds only what it declared, so the hidden input is not there to be read. It fails until the declaration is corrected.

```text
A second check reads figures/style.txt, but says it depends only on the analysis. It is marked
isolated, so it runs in an empty folder that holds only the files it declared.
$ taos gate run --task PEN-2 --agent claude
    FAIL  style        exit 2
    grep: figures/style.txt: No such file or directory
    isolated: it could read only analysis. A file it could not find is one it did not declare.
The declaration is corrected to name the figures, and the same check passes.
$ taos gate run --task PEN-2 --agent claude
    ok    style        exit 0
```

Code: `taos_core/gates.py`

## The idea

A record is a statement, who made it, and what it stood on. Asking is one comparison between that basis and the present.

- `holds`: What it stood on is the same.
- `fails`: Checked as things are now, and it does not pass.
- `stale`: Something it stood on changed, and the change is named.
- `unknown`: It cannot be established. It is never rounded to anything else.

1. Validity is the basis, not the age.
2. The original words outrank any summary of them.
3. An observation has a kind and a source. Shown is not repeated. Recommended is not executed. A check passing is not a person accepting.

Where the same comparison is used:

- Checks: A pass holds for as long as the files it tested are the same. (`taos_core/gates.py`)
- Closing work: One enforcement point. No route to done goes around it. (`taos_core/lifecycle.py`)
- Instructions: Kept by date and scope, in the person's own words. (`taos_core/rules.py`)
- Lessons: A correction shown to an agent is counted apart from a mistake repeated. (`taos_core/lessons.py`)
- Acceptance: By a person, of one exact version. (`taos_core/standing.py`)
- Handoffs: What the next session is told, and whether it is still true. (`taos_core/handoff.py`)
- Changes to the system: Say what a change will do before making it. Score it after. (`taos_core/changes.py`)
- This page: Its numbers are read from the records, and it asks the repository if they moved. (`site/build.py`)

## Evidence

- 22 of 22 known failure cases pass here; 22 fail at the first release `071a348`.
- 20 of 20 protections, removed one at a time, are noticed by the tests.
- 42 of 42 claims hold when read back against the code (`claims.json`).

Reuse experiment, 360 results relied on after 60 edits:

| Policy | Executions | Wrong reuses |
|---|---|---|
| rerun everything | 360 | 0 |
| rerun when older than 2 consultations | 180 | 30 |
| rerun when older than 4 consultations | 90 | 83 |
| rerun when older than 8 consultations | 48 | 161 |
| TAOS, 1 domain(s) declared | 360 | 0 |
| TAOS, 2 domain(s) declared | 180 | 0 |
| TAOS, 3 domain(s) declared | 120 | 0 |
| TAOS, 4 domain(s) declared | 120 | 0 |
| TAOS, 6 domain(s) declared | 60 | 0 |
| TAOS, 12 domain(s) declared | 60 | 0 |
| oracle (knows what every check reads) | 60 | 0 |
| TAOS, three tasks asking | 60 | 0 |
| TAOS, each check hides one folder it reads | 29 | 150 |
| TAOS, checks isolated, declared correctly | 60 | 0 |
| TAOS, checks isolated, each hides one folder | 366 | 0 |

What this does not show:

- The evidence is mechanical. Nothing here shows that research comes out better.
- One synthetic workload and one laptop. The counts are counts, not a speed-up.
- In the open, what a check says it reads is trusted. Isolation closes that, at a cost per run.
- Isolation closes the network and the rest of the workspace on macOS only. Elsewhere the record says they were open.

## Where it comes from

- Truth maintenance. A belief is kept with its justification and withdrawn when the justification goes. (Doyle 1979; de Kleer 1986)
- Build systems. Record what a result was made from and redo only what a change reached. (Mokhov, Mitchell and Peyton Jones 2018)
- Temporal databases. When something was true is kept apart from when it was recorded. (Snodgrass and Ahn 1985)
- Provenance. What a result was derived from is itself data. (W3C PROV-DM 2013)
- Hermetic builds. A step can read only the inputs it declared. (Bazel sandboxing; the Nix build sandbox)

## If you are an agent

- Read `AGENTS.md` in the repository first. It says how to examine the system without setting it up.
- `python3 evals/claims.py --json` reads every claim back against the code. Do not take this page's word.
- `./taos demo` runs the measurement above in a throwaway folder. `./taos selftest` runs the tests.
- To use it for a project, create a repository from the template and follow `BOOTSTRAP.md`.

Files beside this one: `llms.txt`, `claims.json`, `standing.json`, `records/`, `evidence/index.md`.
