--- feature_id: FTR-13 title: Document Registry category: Trackers optional: false depends_on: [FTR-07, FTR-36] registry_refs: [2.09, 5.14] --- # Document Registry Depends on: [FTR-07 — Folder Structure](../items/folder-structure.md), [FTR-36 — Excel Tracker (Base Capability)](../items/excel-tracker-base-capability.md) ## What this is An Excel-workbook tracker (via FTR-36's mechanics) that turns a pile of files into a live command center: a workbook (source of truth), a commit protocol, the tracker README, and the tracker index. This nests under FTR-36's own EXCEL TRACKER section on install rather than duplicating its access/backup/verification mechanics — see FTR-36 for those. This is the foundation the Project Cache (FTR-15) and Active Flags (FTR-14) trackers build on. **Renamed from "Document Tracker System" (same feature, FTR-13, same number) when its default data layer moved from markdown+HTML to Excel, at user's direct request — drafted from real production use in the S.D project, where every tracker in that project was converted from the two-layer markdown/HTML pattern to Excel-as-source-of-truth using FTR-36's mechanics uniformly.** For a project with genuinely separable sub-scopes (see FTR-38, Multi-Sub-Project Awareness, if installed): one workbook per sub-scope plus a roll-up workbook built by re-reading and rewriting from the sub-scope workbooks, never via live cross-workbook formulas, since a live link would embed absolute local file paths inside the workbook itself. A roll-up's own commit protocol always rebuilds from the sub-scope workbooks after they're each individually committed and verified — never hand-edited directly in the roll-up. ## Assess first - Confirm FTR-36 (Excel Tracker Base Capability) is installed — this feature nests under it, not beside it. - Check `trackers\` and its subfolders (`data\`, `templates\`) — create if missing (Folder Structure normally does this). - Check whether `trackers\README.md` and `trackers\tracker_index.md` already exist. If they do, read and carry them forward; if not, generate them at first setup. - Read `admin\AGENT_INSTRUCTIONS.md` for any existing Active Trackers table and carry it forward. - Scan the conversation and project for tracking needs (multiple documents, procurement items, tasks, deadlines) so you can suggest a first tracker. - If a project already has an ACTIVE markdown-based tracker under the pre-Excel default: this is a migration, not a fresh install — see the MIGRATION note in Write, below, before doing anything else. ## Ask, only if needed - If no trackers exist but tracking needs are evident: "It sounds like you're managing [X]. Want me to set up a tracking dashboard? I'll create the Excel workbook, build the folder structure, and write the README." Confirm which tracker type(s) to create. - If trackers already exist and are current, nothing to ask — just record the guide. ## Write Create `trackers\data\` (workbooks live here now, replacing the old data\/templates\ split), generate `trackers\README.md` and `trackers\tracker_index.md` at first tracker setup. Then add this guide to `admin\AGENT_INSTRUCTIONS.md`: ``` ◆ DOCUMENT REGISTRY (nests under FTR-36's EXCEL TRACKER section) This guide applies whether or not trackers are active at project start. When tracking needs emerge — read it, follow it, suggest it. See the EXCEL TRACKER section above for access method, backup convention, and verification discipline — not restated here. WHEN TO SUGGEST A TRACKER If the project has no trackers yet but the conversation reveals tracking needs (multiple documents, procurement items, tasks, deadlines, status questions), suggest one — don't wait to be asked: "It sounds like you're managing [X]. Want me to set up a tracking dashboard? I'll create the Excel workbook, build the folder structure, and write the README." SINGLE SOURCE OF TRUTH — one workbook, no separate display layer: Location: trackers\data\[ProjectCode]_[TrackerName].xlsx Written and edited via FTR-36's PowerShell + Excel COM automation. What Claude reads, updates, and commits. Survives every conversation. This is the record — there is no separate generated view to fall out of sync with it; opening the workbook IS viewing current state. Filename rule: tracker filenames are static — never change. Version rule: version number lives on a dedicated cell/row inside the workbook itself (e.g. a Meta sheet, or a header cell on the main sheet). Increment on every commit. No version numbers in filenames. TRACKER FOLDER STRUCTURE (create when trackers\ is first initialized) trackers\ data\ <- workbooks live here (\[ProjectCode]_[Name].xlsx) _backup\ <- per FTR-36's backup convention, timestamped, pre-edit README.md <- auto-generated — explains this folder README.md — GENERATE AT FIRST SETUP When trackers\ is first created, generate trackers\README.md immediately. It contains: project name and code; the single-workbook-source-of-truth model (no separate display layer to keep in sync); list of active trackers (workbook path, what each tracks); how to read current state (open the workbook, or ask the agent to summarize it); how to update (tell the agent → it edits the workbook via FTR-36's COM automation, backs it up first, verifies the write); a project-cache markdown sidecar note per FTR-36's own sidecar rule; commit protocol reminder; note that the folder was created by the project bootstrap (version, date). Update the README whenever a new tracker is added. HOW TO DISPLAY A TRACKER "render the [tracker name] in the conversation" or "show me the document registry." Read the workbook (via FTR-36's access method) and present its current rows in the conversation — markdown table by default, an actual Excel file open/download only if explicitly asked. There is no separate HTML file to search for or regenerate; the workbook itself is always sufficient. SCHEMA (per FTR-36's dropdown/text-date conventions for Status and date columns respectively) | Column | Purpose | |---|---| | ID | Unique document code (T02, MTN-001, EXH-A) | | Sub-Project | Only if FTR-38 (Multi-Sub-Project Awareness) is installed and this workbook spans more than one sub-project; blank otherwise | | Title | Document title | | Status | Dropdown: Needed · Seeded · Draft · Active · Final · Restricted | | File Path | Where the actual document lives | | Internal Version | Document's own version, distinct from the tracker workbook's own version | | Last Updated | True Excel date or fixed text, decided explicitly per FTR-36's own date-handling guidance | | Notes | Free text | COMMIT PROTOCOL — NON-NEGOTIABLE (uses FTR-36's mechanics directly, no separate regeneration step) A commit is complete only when the workbook is updated and written, per FTR-36's own sequence: 1. Confirm the workbook exists and is non-zero before opening. 2. Take the pre-edit backup; confirm it is non-zero. 3. Open via COM, make the edit(s), increment the internal version cell, save, close, quit, release the COM object. 4. Confirm the file's modified timestamp changed and its size is sane. 5. Re-open in a fresh, separate COM session and read back the edited cell(s) to confirm the write actually persisted. 6. Update trackers\tracker_index.md with new version and commit date. There is no step for regenerating an HTML display file — that step from the markdown-era version of this feature no longer exists. SESSION COMMIT PROMPTING During tracker work — not just at conversation close — prompt at natural stopping points when a cluster of changes accumulates: "We've made [X] updates to the registry this session. Ready to commit?" Always prompt before the conversation ends if any updates remain seeded. CROSS-CONVERSATION CONTINUITY The workbook makes a tracker durable. Any future session opens it and reconstructs full state directly — no separate display file to lose or regenerate. If a future conversation asks "what's in the registry?" read the workbook directly from trackers\data\. MIGRATION — for any project converting an existing markdown tracker to this default When a project already has an active markdown-tracker under the pre- Excel default: the old data\ markdown file is superseded, not deleted — moved to the project's archive location with a dated `_superseded` suffix, per whatever versioning rule the project's own File Naming feature specifies. Any HTML display file that existed for it is retired the same way (or simply noted as never having been generated, if that's the case). Existing rows migrate into the new workbook as part of the same conversion pass, verified via FTR-36's own round-trip check before being considered complete — a conversion is not done until the migrated data has been read back from a fresh COM session and confirmed to match what was in the source markdown. ACTIVE TRACKERS | Tracker | Code | Workbook | Version | Last Commit | | [Name] | [C] | trackers\data\[f].xlsx | v[X.X] | [Date] | Tracker index: trackers\tracker_index.md — all trackers, workbook path, internal version, last commit date. Also in Project Files. TRACKER TYPES AVAILABLE Document · Project Status · Procurement/Vendor · Evidence/Exhibit · Research · Contact · Decision Log · Compliance · Pipeline · Active Flags · Project Cache Manifest. REFERENCING ITEMS Every item has a code name on its row (T02, MTN-001, EXH-A). "Show me [ProjectCode]-T02" → markdown in conversation. Default: markdown; Word only when explicitly asked. ``` ## Confirm Confirm: your Document Registry is installed — single-workbook architecture (via FTR-36), commit protocol, tracker README, and tracker index are all in place, and the agent will suggest trackers proactively. Want to install another, or is that everything for now?