Codify the two inherited-file manifest states (P1 decisions)

The P1 lingcod manifest declares `retrieved: null` and `class: constructed`
with `builder: null` / `builder_status: unrecovered`. Copilot flagged both as
out of compliance with AGENTS.md — correctly, because the rules had no wording
for inherited files. Rather than patch the manifest to dodge the rules (which
would mean inventing a retrieval date or misclassifying a constructed file as
verbatim), bless both states explicitly so the gap stays visible in the
generated catalog and the rules and the manifest stop contradicting.

- AGENTS.md: add "Two inherited-file states" under the manifest rules —
  `retrieved: null` permitted for inherited-undated bytes (paired with an
  integrity.upstream reason; never reconstructed from git history), and
  `builder_status: unrecovered` for inherited constructed files (Phase 9),
  inherited-only so a new constructed file still must ship its builder.
- manifest-schema.yml: document the `retrieved` null policy and scope
  `unrecovered` to inherited files at the two field sites.

Provisional P1 decisions, to be folded into the convention.
See QuantEcon/meta#338 and QuantEcon/QuantEcon.manual#108.

Author: mmcky

AGENTS.md

@@ -25,6 +25,13 @@ Classify as exactly one of:
 
 A constructed dataset without its committed builder is a bug. Manifest fields: `source`, `license`, `retrieved`, `schema`, `consumers` (repo + lecture file, machine-readable), `maintainer`, `cadence` (dynamic only).
 
+#### Two inherited-file states that look like violations but are tracked, not hidden
+
+The Feb 2025 migration left files that cannot fully satisfy the rules above. The manifest records each gap **explicitly** — visible in the generated catalog — rather than burying it by misclassification. Both are provisional decisions from the P1 pilot ([meta#338](https://github.com/QuantEcon/meta/issues/338)), to be folded into [manual#108](https://github.com/QuantEcon/QuantEcon.manual/pull/108).
+
+- **`retrieved: null` — inherited-undated bytes.** `retrieved` is required, but may be `null` when the bytes were inherited (e.g. from a lecture repo) with **no recorded upstream-retrieval date**. Do **not** reconstruct one from git history — that records when QuantEcon acquired the file, not when it was retrieved from the source, and the false precision is worse than an honest null. A null `retrieved` must be paired with an `integrity.upstream` entry that says why (`status: unverifiable` with a reason).
+- **`builder_status: unrecovered` — constructed without a recoverable builder.** A constructed dataset ships its builder, and one that omits it *silently* is the bug. Several inherited files are constructed with no recoverable extraction steps (PLAN Phase 9 tracks them). Keep `class: constructed` — reclassifying to `verbatim` to dodge the rule is misclassification — set `builder: null` and `builder_status: unrecovered`, and the gap stays visible for Phase 9 to recover. `unrecovered` is for **inherited files only**; never introduce a *new* constructed file without its builder.
+
 ### Corrections vs vintages
 
 - **Corrections** (bad parse, wrong units, corrupt rows): fix **in place**, same filename — every consumer should get the fix. Use the manifest's `consumers` list to know which lectures to rebuild/review.

manifest-schema.yml

@@ -59,7 +59,12 @@ license:
                                         # authority is often not the project
                                         # homepage but its Zenodo/DOI record.
 
-retrieved: 2024-04-10                   # ISO date the bytes were obtained
+retrieved: 2024-04-10                   # ISO date the bytes were obtained, or
+                                        # null for inherited-undated files —
+                                        # never invent one from git history.
+                                        # A null here MUST be paired with an
+                                        # integrity.upstream reason (AGENTS.md,
+                                        # "Two inherited-file states").
 maintainer: QuantEcon                   # who fixes this when it breaks
 
 # ---------------------------------------------------------------------------
@@ -134,6 +139,8 @@ builder: scripts/business_cycle.py      # path to the committed builder, or null
 # repo has inherited several (PLAN Phase 9), and P1's own pilot file is one.
 # The tempting workaround is to misclassify them as `verbatim`, which buries
 # the gap. This field keeps it visible in the generated catalog instead.
+# `unrecovered` is for inherited files only; a NEW constructed file must ship
+# its builder (AGENTS.md, "Two inherited-file states").
 builder_status: committed               # committed | unrecovered | not-applicable
 
 # Dynamic snapshots only. Drives the scheduled refresh-as-PR (PLAN Phase 5).