Skip to content

Commit feb7a3d

Browse files
StepenkoAnatoliStepenkoAnatoli
committed
Downgrade the architecture note: I deleted the evidence behind it
A reviewer noticed PR #21 called itself "research complete" while changing no corpus files - no discovery contract, no evidence rows, no captures, no ledger entries. That is correct, and the cause is worse than an omission. I DELETED THE EVIDENCE Nine pages were collected on 2026-09-21 through the metered route into a scratch project outside the repository - deliberately outside, to avoid mixing a second research question into the corpus that answers this kit's own unknowns. The findings were read from those captures. Then the scratch project was removed as routine cleanup, taking the captures, the hash-chained ledger, and the provenance for every claim with it. That is the exact failure this kit exists to prevent, committed while using the kit. And the repository's clean preflight - which I cited - validates the EXISTING corpus. It says nothing about this note, and quoting it beside the note implied otherwise. WHAT CHANGED requirements-2026-09-21-* -> preliminary-2026-09-21-*, and the document opens by saying it is not a completed Phase 1 handoff and that formal collection remains outstanding. It also separates findings by how checkable they are, because they are not equally weak: 204 No Content re-verifiable in one command, depends on no capture of mine the correlation race re-verifiable; run ids 35546279728 and 35546293660 are in GitHub's API today retention, billing, SEA, CITATIONS, not evidence. Live URLs anyone can environment rules re-read, with no capture, hash or chain behind them. Leads to confirm, not facts proven. The recommendation rests mostly on the first two, which is why it survives the downgrade rather than being withdrawn. THE STRUCTURAL GAP, WHICH WILL RECUR The scratch project was the only option the kit offers. `readCorpus(root)` reads one `research/` per project root, and a project has one discovery contract; this repository's enumerates U-1..U-8, all about transports. Architecture-decision unknowns are a different question, and one contract asserting two unrelated sets of claims would have `unknown-closure` and `subtopic-coverage` judging them together. Three options, none currently supported well: a nested project under docs/decisions/<name>/, a second repository per decision, or one contract with multiple topics. The first is cheapest and needs no code - it needs a decision that decision-research lives there, so the next person does not reach for a scratch directory and delete the evidence as I did. VERIFIED node research-kit/bin/selftest.mjs -> 645 passed, 0 failed, exit 0 node research-kit/bin/preflight.mjs -> PASS, 0 blocking, 0 warnings (both about the repository's own corpus, which is the point above)
1 parent 1eef1b0 commit feb7a3d

1 file changed

Lines changed: 56 additions & 9 deletions

File tree

docs/requirements-2026-09-21-delivery-architecture.md renamed to docs/preliminary-2026-09-21-delivery-architecture.md

Lines changed: 56 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,37 @@
1-
# Phase 1 research — how Research-Kit should be delivered
1+
# PRELIMINARY note — how Research-Kit should be delivered
22

33
**Question:** Actions-only collector, local Windows `.exe`, hybrid desktop-over-Actions, or
44
REST/API seam only?
55

6-
**Status: research complete, decision NOT taken.** The recommendation below is the
7-
agent's, and the three human-judgment steps this kit refuses to automate apply to *this
8-
document too*: the findings want reading against their sources before anyone builds from
9-
them.
10-
11-
Collected 2026-09-21 through the metered route, 9 primary pages, 9 credits. All sources
12-
are vendor documentation, re-readable at the URLs given.
6+
> ## This is NOT a completed Phase 1 handoff
7+
>
8+
> **Formal Phase 1 collection remains outstanding.** This note has no discovery contract,
9+
> no evidence rows, no cached captures and no ledger entries in this repository, so it
10+
> has not passed — and cannot pass — the gate this project applies to research.
11+
>
12+
> **Why, plainly: I deleted the evidence.** Nine pages were collected on 2026-09-21
13+
> through the metered route into a scratch project outside the repository, to avoid mixing
14+
> a second research question into the corpus that answers this kit's own unknowns. The
15+
> findings below were read from those captures. Then the scratch project was removed as
16+
> routine cleanup, and with it the captures, the hash-chained ledger and the provenance
17+
> for every claim here.
18+
>
19+
> That is the exact failure this kit exists to prevent, committed while using the kit. The
20+
> repository's clean preflight validates its EXISTING corpus; it says nothing about this
21+
> note.
22+
23+
## What is and is not independently checkable
24+
25+
The findings are not equally weak, and the difference matters more than the label:
26+
27+
| Finding | Status |
28+
|---|---|
29+
| `dispatches` returns `204 No Content` | **Independently re-verifiable in one command** — `gh api -X POST .../dispatches -f ref=main -i`. Does not depend on my captures at all. |
30+
| Two dispatches are distinguishable only by timestamp | **Re-verifiable** — run IDs `35546279728` and `35546293660` are in GitHub's API and can be listed today. |
31+
| Artifact retention, Actions billing, SEA stability, environment protection rules | **Citations, not evidence.** Live vendor URLs anyone can re-read, but with no capture, no hash and no chain behind them. Treat as leads to confirm, not as proven. |
32+
33+
The recommendation below rests mostly on the first two, which is why it survives the
34+
downgrade. The supporting facts want re-collecting before anything is built on them.
1335

1436
---
1537

@@ -105,7 +127,32 @@ world. But topics, collected URLs, evidence text and error output all become pub
105127
moment they reach a log, an artifact listing, or a PR. Research whose *subject* is
106128
sensitive should run in a private repository, where finding 1 stops being free.
107129

108-
## What this research does not establish
130+
## The structural gap that caused this, which will recur
131+
132+
The scratch project was not carelessness — it was the only option the kit offers, and that
133+
is worth fixing before the next decision needs evidence.
134+
135+
`readCorpus(root)` reads `research/` relative to one project root, and a project has
136+
exactly one discovery contract. This repository's contract enumerates U-1..U-8, all about
137+
transports. Architecture-decision unknowns are a *different question*, and putting them in
138+
the same contract would mean one corpus asserting two unrelated sets of claims, with
139+
`unknown-closure` and `subtopic-coverage` judging them together.
140+
141+
So there are three options and the kit currently supports none of them well:
142+
143+
1. **A nested project** — `docs/decisions/<name>/research/...`, self-contained and
144+
committed, runnable by `cd`-ing into it. Works with the kit as built, since the project
145+
is the working directory. Costs a convention nobody has agreed.
146+
2. **A second repository** per decision. Clean, heavyweight, and scatters the reasoning
147+
away from the thing it reasons about.
148+
3. **One contract, multiple topics** — a change to the protocol, not to a directory
149+
layout, and the most invasive.
150+
151+
Option 1 is the cheapest and needs no code. What it needs is a decision that decision
152+
research lives there, so the next person does not reach for a scratch directory and
153+
delete the evidence as I did.
154+
155+
## What this note does not establish
109156

110157
- The runner-side `npm install -g firecrawl@1.23.3` path, which has still never executed.
111158
- Whether artifact download is ergonomic enough for the intended beginner; that is a

0 commit comments

Comments
 (0)