This is the development record, published as it was written. It is amended by revision, including where the work went wrong. Nothing here has been rewritten for the web.
Record header
created_at: 2026-09-19T23:58:00-06:00
format: perspicuity-work/1
id: ae-2026-09-19-public-repository-scope
record_status: open
revision: 1
skill_version: 0.4.0
updated: 2026-09-19
updated_at: 2026-09-19T00:14:46-06:00
work_status: submitted
Keep this a separate public repository, not an entry in the tools toolkit
Current position
Parent: RECORD.md, revision 7.
Principal: David. Decider: David for whether this repository becomes public and under what name. Rook for the comparison and the recommendation, inside the delegation in RECORD.md. Work owner: Rook. Decision: recommended — this stays a separate repository rather than becoming an entry in perspicuity-ai/tools. David asked whether it could be a tool in the toolkit; the evidence says no, and the reason is mechanical as much as editorial. He has not selected, and creating the remote and pushing are his. Work scope: where this project's public home is, and the rule that decides where a later project goes. It does not own the tools repository, its decision record, or the naming of anything else. Work: the comparison is below, written after reading the tools decision record and this repository's own shape. Deployment coordinates are stripped from the working tree at 49c0f64. Nothing has been pushed anywhere. Outcome: unknown. No remote exists, so nothing about publication is observable yet. Next: David — select or reject the recommendation, and if he selects it, name the remote and give the word to push. Rook — prepare the repository for publication once the name is known. Dependency: David's selection, and one decision that precedes publication: whether to put the site behind the Cloudflare proxy, since the origin address is already published in the corpus and hiding it is the proxy's job rather than a redaction's.
| Stage | began_at | registered_at / exact basis revision | finished_at |
|---|---|---|---|
| Frame and Decide | 2026-09-19T23:50:00-06:00 | 2026-09-19T23:58:00-06:00 / this revision | 2026-09-19T23:58:00-06:00 |
| Act | pending | pending | pending |
| Review | pending | pending | pending |
Frame and Decide
David asked whether this could be another tool inside the toolkit, noting that the project seems small and that a toolkit of dictation, this, and "a few more" is a plausible shape. That is a reasonable guess from the outside: the tool *is* small — 17 checks and a report. The question is whether the repository is the same size as the tool, and it is not.
The frame worth registering, because it will recur as more projects appear:
What decides whether a project is an entry in the toolkit or its own public home?
Material conditions
| Material condition | Type | Basis | Affects |
|---|---|---|---|
| The tools repository's scope is "small, tested command-line tools" | Given | the tools decision (in the perspicuity repository, Decisions/2026-09-19-tools-repository.md), work scope, read 2026-09-19 | Whether this fits without amending a decision another session owns |
| Its first entry is a CLI tool, 11 files, no service | Given | Same record, Act: "Eleven files prepared" | The shape an entry is expected to have |
| That repository does not exist yet; nothing is pushed | Given | Same record; no tools/ checkout under the perspicuity root | Folding something in would delay both |
| This project is a running service | Given | ops/ units, eligibility/worker.py, a queue, a report store, a Caddy host block, https://agents.perspicuity.ai/ | It cannot be described as a command-line tool without stretching the words |
| This project is 67 tracked files and ~1,900 lines of Python | Given | git ls-files, wc -l | Comparable in size to a small product, not a script |
| Its corpus generator publishes every markdown file in its repository root | Given | eligibility/corpus.py, PUBLISHED and corpus_files() | Inside a larger repository it would publish that repository's documents too |
| The organisation already runs three public homes | Given | decision-toolkit, tools, and this | A fourth is a naming question, not a precedent |
| A repository can be made private again, but clones cannot be recalled | Given | Ordinary fact about publication | The choice is one-way in practice |
Alternatives and consequences
| # | Home | Fits the tools scope | Corpus stays correct | Operationally coherent | Cost |
|---|---|---|---|---|---|
| A1 | An entry in perspicuity-ai/tools, beside the dictation tool | No. The record scopes that repository to command-line tools | No. The generator would publish the tools repository's own decisions and README into this tool's corpus, or would need a path-aware rewrite | No. A hosted service with units, a queue and a database is not a tool entry | Cheapest today; amends another owner's decision and breaks a working generator |
| A2 | Its own public repository, perspicuity-ai/agent-eligibility | Yes — it is not claimed to be a tool | Yes — the generator's world stays exactly its own repository | Yes — release layout, units and CI already assume a repository root | One more public home to look after |
| A3 | Its own repository, but private for now | Yes | Yes | Yes | Nothing external can verify the claims the product makes about being inspectable |
| A4 | Leave it local and unpushed | n/a | n/a | n/a | The whole project exists on one machine; .github/workflows/ci.yml has never run |
The decisive reason is mechanical, not editorial. eligibility/corpus.py publishes the documents in *its own repository*. Inside a larger repository it would either publish that repository's unrelated decisions into this tool's corpus — a small supplier opening the record behind a check would meet the dictation tool's reasoning — or it would need a path-aware rewrite of the one component whose integrity the product's credibility rests on. Neither is acceptable to save one repository.
The secondary reason is that the tools decision is another session's. Its work scope says small command-line tools. Folding a service in would mean amending a record owned by a different project, which this project's own rules say not to do from here.
What would change the answer. If the check were reduced to a command anyone runs locally — no queue, no service, no domain — it would be a tool, and the toolkit would be its right home. That is not a hypothetical: it is the service-only course (A1 in the cycle-one scope) that was rejected for the market test. If that course is ever taken, this decision should be revisited rather than inherited.
Selection
Selected: A2, with a taxonomy around it. David's instruction of 2026-09-19 evening puts tools and services in different classes: "tools be small command line things that run, and then services could be things like this that have their own process." That is a better rule than the one this record recommended, because it says *why* rather than naming a case, and it matches what the host already does.
| Class | What it is | Where it lives | What it has |
|---|---|---|---|
| Tools | A command someone runs | perspicuity-ai/tools, one directory each | A documented install and a test. No process, no address |
| Services | Something with its own process, port, queue or database | Its own repository, and its own origin on the host | A unit, a release directory, a host block, a port, a lifecycle |
| Sites | Static pages | Its own release directory | A document root. No process at all |
The host already implements this, which is the evidence rather than the analogy. Read on 2026-09-19: perspicuity.ai, www.perspicuity.ai and www.peopleandplanet.consulting are static releases with no process behind them; findmynextbite.food runs behind find-my-next-bite.service on its own loopback port; www.peopleandplanet.consulting has an enquiry service on another; and this project now runs two units on its own port. Every service on that server has its own repository, its own port and its own unit, and there is no services monorepo. The rule this record proposes is the rule already in force.
**What is not created yet: a services umbrella. An organisation cannot nest repositories, so "Perspicuity-AI services" is either a naming convention or a GitHub team, and neither is worth making before there is something to put in it. Two services exist; a container for two is ceremony. The trigger to revisit: three services sharing something real** — a deploy script, a health-check convention, a shared library — at which point the shared thing gets its own repository and the umbrella becomes a fact rather than a label. Until then, each service stands alone and the taxonomy lives in this record.
Why not a monorepo, in one line each. It would publish every service's decisions into every service's corpus, since each one generates its corpus from its own repository root. It would couple four release lifecycles that currently move independently — one service's bad commit would need care not to touch another's. And it would require per-service CI plumbing that does not exist and that nothing currently needs.
Act
*Registered once the selection is made.* The work is expected to be: strip what should not be public (done at 49c0f64), prepare a README that tells a stranger what the project is without repeating the corpus, resolve the proxy question, create the remote, and push.
Review
| Criterion | Evidence source | Owner, window or trigger | Finding | Response |
|---|---|---|---|---|
| No credential or operational coordinate is published | A scan of the tracked tree; the record of the scan | Rook, before publication | Met in the working tree at 49c0f64; not met in history, which retains the address in 8 commits | Accept, because the address is published by DNS anyway and rewriting history would break every commit reference the corpus cites. The mitigation is the proxy, not a redaction |
| The corpus stays correct wherever the repository lives | make ci's freshness check | Rook, continuous | Met while the repository is its own root | This is the criterion that rejects A1 |
| A stranger can verify the product's claims | The public repository | David, after publication | Pending | — |
Delivery acceptance is separate from benefit. Preparing a repository for publication establishes nothing about whether anyone reads it.
Changes
Revision 1, 2026-09-19T23:58:00-06:00. Created with the comparison and a recommendation, and no selection. Source: David's question whether this could be a tool in the toolkit, and his remark that the project seems small. Reason: the question recurs with every project and the answer is a rule, not a one-off — and the rule turns out to be mechanical, because this project's corpus generator publishes its own repository. Affects: where this project is published, what the tools repository holds, and the placement of later projects. Nothing has been pushed; no remote exists.
Revision 2, 2026-09-19T00:14:46-06:00. Selects A2 and records the taxonomy it belongs to. Source: David's instruction of the same evening, that tools are "small command line things that run" and services are "things like this that have their own process", with the observation that the services might later be examined for how they play together. Reason: the instruction is a rule rather than a ruling — it says what distinguishes the classes, so the next project does not need this comparison repeated. Changes: the recommendation becomes a selection; the tools/services/sites table is written out with the host's own arrangement as its evidence; the umbrella is deliberately not created, with the trigger that would justify it recorded rather than left to memory; and the monorepo objection is stated in three lines so it does not have to be re-derived. No earlier revision is rewritten: revision 1's recommendation stands, and the selection replaces it by amendment rather than by editing it. Nothing has been pushed; no remote exists; the name remains David's to choose.
How this record connects
It builds on or points to: RECORD, RECORD § authority, 2026-09-19-cycle-one-delivery-scope.