--- feature_id: FTR-26 title: Install Manifest & Reconciliation category: Health & Maintenance version: 1.1 optional: false depends_on: none (most useful once at least one other feature is installed, but works standalone) source: Not from Project_Kickoff_Seed_Prompt_v2.3.md or Directory_Cleanup_Inventory_Prompt_v1.0.md — a new capability built for this database's hosted-catalog model, since the original Bootstrap's rerun-to-reconcile loop (registry item 1.11) assumed the whole seed prompt got re-dropped into a conversation each time, which doesn't apply once installs happen one feature at a time from a hosted site. See coverage_report.md Section 10. registry_refs: none (see source note above) --- # Install Manifest & Reconciliation ## What this is Two things in one feature. First, a standing record — the **KFB Install Manifest** — a section in `admin\AGENT_INSTRUCTIONS.md` that lists every feature from this database that's been installed in this project, at what version, and when. Second, an on-demand check: fetch this catalog, compare each manifest entry's installed version against the catalog's current version, and report what's current, what's outdated, and what's in the catalog but not yet installed. Never installs or updates anything by itself — it only reports, and waits to be told what to do with what it finds. This is what makes it possible to come back to a project weeks or months later and know exactly what's here, from where, and whether anything's moved on since. Two depths of check (added v1.1): the standard reconciliation above compares version numbers and existence only — cheap, fast, safe to run often. A separate, opt-in DEEP MODE goes further: it fetches each installed feature's real individual spec page and compares its actual requirements against what's genuinely implemented in admin\AGENT_INSTRUCTIONS.md, line by line. A project can pass the standard check cleanly (versions current, nothing missing) while still silently implementing several features incorrectly — version-matching alone can't catch that, since a feature can be recorded at the right version number while its actual implemented text has quietly drifted from what that version's spec really says. ## Assess first - Check `admin\AGENT_INSTRUCTIONS.md` for an existing `◆ KFB INSTALL MANIFEST` section. - If present: that's the record to work from. - If absent but other KFB features are clearly installed (matching section headers like `◆ FOLDER STRUCTURE`, `◆ PROJECT CACHE`, etc. are present): offer to backfill a manifest by matching installed sections to known feature titles, defaulting each to version 1.0 with today's date and a note that the entry was backfilled rather than recorded at install time. - If absent and nothing looks installed: there's nothing to reconcile yet — say so plainly rather than fabricating a manifest. - Check whether a catalog source URL is already recorded (in the manifest's `Source:` line, or mentioned elsewhere in the project). If so, use it. ## Ask, only if needed - If no source URL is recorded and this conversation doesn't already have access to a live version of this catalog (via an already-fetched page, or local files in this project), ask: "What's the URL (or file path) for the feature database you'd like to check against?" - Nothing else to ask — the comparison itself doesn't require input, just the manifest and the catalog. ## Write Add this section to `admin\AGENT_INSTRUCTIONS.md` (create it if this is the first KFB feature being installed; every other feature's install also touches this section, adding or updating its own row — this file just formalizes the format and the on-demand check): ``` ◆ KFB INSTALL MANIFEST Source: [catalog URL, or "local files" if not hosted] Catalog version at last check: [database version, e.g. v3.0] Last reconciliation: [date this was last checked against the live catalog] | Feature ID | Title | Version Installed | Installed | |-----------|-------|-------------------|-----------| | [FTR-XX] | [Title] | [X.X] | [YYYY-MM-DD] | RECORDING RULE Whenever a KFB feature installs (individually or via "install everything"), add or update its row here: feature ID, title, the version it was installed at (per the catalog's version table at that moment), and today's date. This is bookkeeping, not optional — it's what makes reconciliation possible later. Don't skip it because it feels like overhead; it's a few seconds now that saves guessing later. RECONCILIATION — TRIGGER PHRASES "check for KFB updates" / "reconcile installed features" / "what's installed vs available" / "sync with the feature database" / "check what's installed" WHEN TRIGGERED 1. Read this manifest. If it's empty or missing, say so and offer to build one (see Assess above) before going further. 2. Fetch the current catalog's index (index.md's data/index.md, or the equivalent) from the recorded Source. If no source is recorded, ask for one. 3. For every feature listed in the manifest, compare its "Version Installed" against that feature's current version in the catalog. Sort into: - Current: installed version matches the catalog's version - Update available: catalog version is newer — note what the feature's "What this is" or Write payload appears to have changed, if that's determinable - No longer in catalog: the feature ID isn't in the current catalog at all (removed or renumbered upstream) — flag this, don't guess why Then check the catalog for anything NOT in the manifest at all: - Not installed: available in the catalog, no manifest entry 4. Present all four groups as a clear report. Update "Last reconciliation" to today's date regardless of whether anything changed. 5. Do not install, update, or remove anything during this check. Ask what (if anything) the person wants to do with what was found — update specific outdated features, install specific new ones, or just leave the report as information. Proceed only on what's actually requested, one item or "everything found" at a time. DEEP MODE — TRIGGER PHRASES "reconcile against spec" / "deep audit" / "run a specification compliance check" / "audit against the real spec" / "check [FTR-code] against spec" (single-feature spot check) WHAT DEEP MODE DOES DIFFERENTLY Standard reconciliation above compares version NUMBERS against the catalog's index. Deep mode compares actual CONTENT: for each installed, non-pointer feature, fetch that feature's real individual spec page (never the shorter catalog index for this — that gap is exactly what lets drift go undetected) and compare it against what's genuinely implemented in admin\AGENT_INSTRUCTIONS.md, requirement by requirement. Pointer-style features (which hold minimal detail in the main file by design) get their pointer's target file compared instead, if one exists. WHEN TRIGGERED (DEEP MODE) 1. Read admin\AGENT_INSTRUCTIONS.md in full. 2. Read the Install Manifest to get the current list of installed features and their claimed versions. 3. For each installed feature, fetch its real individual spec page and classify every requirement into one of five buckets: - MATCH — implemented as specified. - DRIFT — implemented differently from spec, with no documentation anywhere explaining why. Treat as a bug. - OVERRIDE (documented) — implemented differently from spec, but with an explicit, dated note in the instructions file explaining the deliberate deviation and the reason. Not a bug; a confirmed decision. - OVERRIDE (undocumented) — implemented differently from spec, looks intentional (consistent, sensible), but no note exists explaining it. Flag for the user to confirm: should this be documented, or is it drift that should be fixed? - GAP — spec requirement not implemented at all. 4. For any finding that touches a live document, correspondence, or filing — not just the instructions text itself — flag it with elevated severity: the blast radius extends beyond the instructions file into actual project materials. 5. Present one report (never auto-applied): a summary count per bucket, then per-feature findings (status, the exact spec language quoted, the exact implemented language quoted, and — for DRIFT/GAP/undocumented OVERRIDE — a recommended fix), then any blast-radius flags called out separately. Never bundle a blast-radius finding into a routine fix pass without explicit confirmation — and when a fix is authorized, treat correcting the instructions text and physically relocating or fixing any affected live materials as two separate steps, not one — completing the first does not automatically complete the second. 6. For projects with more than a handful of installed features, recommend running this via Cowork rather than in-conversation — fetching every feature's individual spec page is the expensive part, and parallel sub-agent fan-out keeps it tractable, the same way FTR-25 (Directory Cleanup) already recommends Cowork for large directories. ``` ## Confirm Confirm: Install Manifest & Reconciliation is enabled — a KFB INSTALL MANIFEST section now exists (or will, from the next install onward) in `admin\AGENT_INSTRUCTIONS.md`. Two ways to check it: "check for KFB updates" for the standard, fast version/existence comparison, or "deep audit" (or "reconcile against spec") for the deeper, slower per-feature content comparison against each feature's real spec page. Neither changes anything until told to. Want to install another, or is that everything for now?