FILE PLACEMENT MAP
OWNER: hand-authored, 01_System/portable/FILE_PLACEMENT_MAP.md REVIEW: whenever a folder is added, a file type appears that fits no row, or the Standard changes.
Mandated by GOV-F3.8 — every project carries a placement map stating which folder takes which kind of file, what is permitted at the root, and what counts as debris. Before writing any file you must name its folder from this map. A file that fits no row is a question for Zaid, never a new folder of your own invention (GOV-F3.8). A mandated folder that is missing is created with python 01_System/tidy.py --ensure before the file is written, never worked around (GOV-F3.9).
1. What may sit at the project root
Exactly two files. Nothing else, ever.
| File | Why it is allowed at the root |
|---|---|
README.md | The single entry point (GOV-F9.6). The one door in. |
Dashboard.html | The single front door for status (GOV-F2.1). |
Everything else at the root is a placement defect and is caught by the checker.
2. Which folder takes which file
| Folder | What belongs here | What must never go here |
|---|---|---|
00_Handover/ | The transfer pack. Generated only — no fact originates here (GOV-F9.12). Plain text, relative paths, a SHA-256 manifest. | Anything hand-written. Anything binary. |
01_System/ | How the project is run: the source of truth, the generators, the checkers, the threat model, the system breakdown, the business plan twin and its generated A3 page, the daily audit log, the source manifest. | Deliverables. The thing the project exists to produce lives in 05_Outputs/ (GOV-F5.6). |
01_System/portable/ | The portable layer — rules and templates that travel to other projects unchanged: this map, the business-plan schema and generator. | Anything project-specific. If it names this project, it is not portable. |
02_Work/ | Working material: research records, verification records, diagrams. | Deliverables. Debris. |
02_Work/_scratch/ | Throwaway probes and one-off experiments (GOV-F3.9). | Anything another file depends on. |
03_Registers/ | The register set as a workbook plus a plain-text .csv projection of every sheet (GOV-F9.8). Generated only. | Hand-maintained register data. |
04_Inputs/ | What was given to the project — uploads, prior work, superseded source material quarantined with its defect ID. | Anything the project produced. |
05_Outputs/ | What the project exists to produce, plus the governing Standard and its projections (GOV-F5.6, GOV-F5.7). | Working files. Scratch. Anything a reader would not call a deliverable. |
06_Archive/_versions/ | Dated snapshots taken before a change. Nothing is ever deleted (GOV-D1.7). | Live files. |
06_Archive/_superseded/ | Superseded material with the change record that retired it. Instruction files here are renamed *.archived so no tool reads them as current (GOV-F3.12). | Anything still in force. |
06_Archive/_debris/<date>/ | What the tidy report swept, with a hash manifest (GOV-F3.10). | Anything still referenced. |
07_Improvements/ | Improvement proposals. Never self-applied (GOV-F7.3). | Applied changes. Those are change records. |
08_Reusable_Knowledge/ | Portable lessons, project detail stripped (GOV-F7.6). | Anything that only makes sense here. |
09_Help_Hub/ | The single help surface. Generated only. | A second overview or status page. |
3. Debris patterns — swept, never deleted
Swept to 06_Archive/_debris/<date>/ with a hash manifest before every handover (GOV-F3.10).
| Pattern | Why it is debris |
|---|---|
__pycache__/, *.pyc | Build caches. Regenerate themselves. |
*.tmp, *.bak, *~, *.orig | Temporary and backup copies. |
*.lock, *.lck | Lock files left by a crashed process. |
* (1).*, *-conflict*, *copy* | Cloud-sync conflict copies. Two copies of a fact are two facts. |
*.log outside 01_System/ | Run logs belong beside the thing that wrote them. |
| One-off scripts beside their target | A script that ran once belongs in 02_Work/_scratch/. |
.env, *.key, *.pem, id_rsa* | Secret stores. These must not exist here at all (GOV-E5.1, INV-5). |
*.lnk, *.url, symbolic links | Links to live files outside the project (GOV-F3.11). |
4. No links to live files
GOV-F3.11. A deliverable, register or note must not reference a file by a path outside the project, a drive letter, a shortcut, a symbolic link, or a hosted URL used as the home of a project file. A file needed from elsewhere is copied in, filed under this map, and referenced by its in-project path.
A source URL cited as evidence for a fact is not a link to a live file and is permitted — that is what the source register is for. The distinction is whether the project would break if the link died. Evidence citations degrade to "re-verify this"; file links break the project.
5. How this is enforced
python 01_System/tidy.py --report lists every violation. --ensure creates missing mandated folders. --sweep archives debris with a manifest. The checker suite fails the build on a loose root file, a debris pattern outside the archive, a shortcut or symbolic link, a folder this map does not know, a missing mandated folder, or a secret-store file — and the check has been proven able to fail by a deliberate negative test (GOV-F3.12).