review-pack.md
HTML wrapper for HTML-only fetchers; content is shown verbatim.
Raw file
Links (extracted)
Clickable list for reviewers; avoids copy/paste line-wrap issues.
# InfraFabric External Review Bundle (IF.TRACE + ShadowRT + iftypeset)
Audience: external reviewers (humans + sandboxed LLMs).
Goal: give you **one document** with enough context to sanity-check the system, spot major wrong assumptions, and propose concrete patches — without needing internal access.
Formatting constraints (intentional):
- **One URL per line** (avoids line-wrap breakage).
- Prefer **HTML links first**, because some environments block direct `.md`, `.py`, `.tar.gz` downloads.
---
## 1) What this bundle is asking you to evaluate
### A) IF.TRACE (T3 receipts)
IF.TRACE is a **public chain-of-custody receipt surface**.
Black/white:
- It proves **integrity + traceability** (bytes ↔ hashes/signatures).
- It does **not** prove “correct”, “true”, or “compliant”.
Quantum wording (black/white):
- **QUANTUM READY** means: “a post‑quantum receipt exists for this trace.”
- It does **not** mean “quantum secure”.
### B) ShadowRT (@ShadowRT dossiers)
ShadowRT is the **Trojan wrapper**: readable vendor / framework “shadow dossiers” that route skeptical readers to receipts.
Black/white:
- The dossier can be funny and editorial.
- The receipts must stay boring and verifiable.
### C) IF.GOV (governance decision packs)
IF.GOV is a planned “governance-as-a-service” SKU: we produce an **auditable decision pack** (memo + risks + control plan) and bind it to IF.TRACE receipts so third parties can verify the bytes later.
Black/white:
- It helps teams produce a decision record that survives politics, turnover, and “we never said that” disputes.
- It does **not** guarantee compliance, audit outcomes, or safety; it is not legal advice; it is not an external auditor.
- Single-host reality: data-handling modes must be explicit (no-retention / retention window / export-only).
Example deliverable outline (illustrative; not a claim that this is shipped today):
- Decision memo (what / why / owner / deadline)
- Risk register (assumptions, failure modes, mitigations)
- Control plan (gates, stop conditions, evidence signals)
- Evaluation plan (what we will measure, when we will re-evaluate)
- Receipt block (`source_sha256`, `output_sha256`, `receipt_url`)
### D) iftypeset (document CI)
iftypeset is a deterministic **Markdown → HTML/PDF** pipeline with:
- a rule registry (paraphrases + pointers only),
- profiles (“web_pdf”, “print_pdf”, etc),
- lint + QA gates,
- CI artifacts + exit codes.
Black/white:
- It is not “a pretty PDF generator”.
- It’s “CI for document quality”.
---
## 2) Live demo links (copy/paste safe)
### Demo shareId (Snyk AI Code Guardrails dossier)
Trace (receipt):
https://infrafabric.io/static/trace/6qRgcR01kw_qNo63Dbs_ob9n
Pack (HTML):
https://infrafabric.io/static/pack/6qRgcR01kw_qNo63Dbs_ob9n
Pack (Markdown):
https://infrafabric.io/static/pack/6qRgcR01kw_qNo63Dbs_ob9n.md
Dossier (rendered):
https://infrafabric.io/static/dossier/6qRgcR01kw_qNo63Dbs_ob9n
Dossier (download Markdown):
https://infrafabric.io/static/dossier/6qRgcR01kw_qNo63Dbs_ob9n/download
Sandbox fallback:
https://infrafabric.io/r/6qRgcR01kw_qNo63Dbs_ob9n
### IF.TRACE paper update (review pack)
Review pack (HTML):
https://infrafabric.io/static/hosted/review/iftrace-paper-update/2025-12-29/review-pack.html
Review pack (Markdown):
https://infrafabric.io/static/hosted/review/iftrace-paper-update/2025-12-29/review-pack.md
### Triage bundles + offline verifier
Triage selector (HTML):
https://infrafabric.io/static/hosted/review/trace-bundles/b6547c03/index.html
Offline verifier (HTML):
https://infrafabric.io/static/hosted/iftrace.html
Offline verifier (Python):
https://infrafabric.io/static/hosted/iftrace.py
---
## 3) How verification works (black/white)
### What the receipt proves
- The **output bytes** you download match the receipt’s `output_sha256`.
- When a source artifact is provided, the **source bytes** match `source_sha256`.
- A trace receipt exists for this published output (public shareId surface).
### What the receipt does *not* prove
- The dossier’s analysis is “correct”.
- The vendor is “wrong”.
- The policy is “effective”.
- Any compliance claim beyond “you can verify bytes”.
### Offline verification (recommended)
Use the triage selector page to download a bundle, then run the verifier locally.
Note: some sandboxed environments block `.tar.gz` downloads. If you can’t download bundles, review via the HTML pages above and treat the offline step as “best effort”.
---
## 4) What exists today vs roadmap (single-host reality)
Reality gate: everything currently runs on a **single Proxmox host**. We are not claiming multi-cloud HA today.
### Shipped (today)
- Stable, no-login `/static/*` receipt surface with HTML fallbacks.
- At least one live demo shareId with pack + dossier + trace.
- Offline verifier (`iftrace.py`) + triage bundle selector example.
- ShadowRT artifacts exist as published packs (week packs are in hosted review paths; see `docs/iftrace-external-review-pack.md` for the current index links).
- iftypeset is a working CLI pipeline with deterministic artifacts, CI, and a trust contract (details below).
### Not shipped yet (roadmap items)
These are tracked in the umbrella task board:
`/root/docs/13-task-board.md`
P0 roadmap highlights (verbatim intent; not a promise of completion date):
- IF-010 move IF.TRACE from `/` → `/if-trace/` and make `/` a product chooser
- IF-011 add `/if-typeset/` landing page with demos + profiles
- IF-012 simplify IF.TRACE story to a single black/white page
- IF-020 fix “LLM fetcher 400/415” failures for hosted-static assets
- IF-021 upgrade trace page UX (VERIFIED badge at top, offline bundles link)
- IF-030 build ShadowRT public gallery UI (no login)
- IF-031 regenerate ShadowRT Week 1 with post‑Oct‑2025 long-enough sources
- IF-032 add enforced anti-template quality gates to ShadowRT generation
- IF-080 define IF.GOV MVP (SKUs, deliverables, “shipped vs planned”)
- IF-081 add `/if-gov/` landing page (black/white, no compliance claims)
- IF-082 publish one IF.GOV demo decision pack + receipt bundle
- IF-083 document IF.GOV data-handling modes (single-host reality)
- IF-084 document IF.GOV intake contract (iftypeset + IF.TRACE integration)
---
## 5) iftypeset: what reviewers can verify locally (with real code excerpts)
iftypeset is a separate repo at:
`/root/ai-workspace/iftypeset`
The public-facing review pack is captured in:
`/root/docs/14-iftypeset-external-review.md`
### “It’s real” proof points (safe excerpts)
CLI entrypoint:
```toml
[project.scripts]
iftypeset = "iftypeset.cli:main"
```
CI pipeline steps:
```bash
run_step "validate-spec" env PYTHONPATH=src python3 -m iftypeset.cli validate-spec --spec spec --build-indexes
run_step "report" env PYTHONPATH=src python3 -m iftypeset.cli report --spec spec --out out --build-indexes
run_step "tests" python3 -m unittest discover -s tests -p 'test_*.py'
```
One-shot run (CI-friendly summary artifact):
```json
{
"ok": true,
"exit_code": 0,
"started_at_utc": "...",
"finished_at_utc": "...",
"steps": [
{"name": "validate-spec", "rc": 0, "ok": true},
{"name": "lint", "rc": 0, "ok": true},
{"name": "render-html", "rc": 0, "ok": true},
{"name": "render-pdf", "rc": 3, "ok": false},
{"name": "qa", "rc": 0, "ok": true},
{"name": "report", "rc": 0, "ok": true}
]
}
```
Local verification steps (if you have the repo):
```bash
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m pip install -e .
iftypeset validate-spec --spec spec --build-indexes
iftypeset run --input fixtures/sample.md --out out --profile web_pdf --degraded-ok --skip-pdf
iftypeset report --spec spec --out out
```
Expected artifacts after a successful run:
- `out/run-summary.json`
- `out/report/index.html`
- `out/lint-report.json`
- `out/render.html`
- `out/layout-report.json`
- `out/qa-report.json`
---
## 6) Known traps (please verify these claims in your own environment)
### A) Some LLM “web fetchers” block downloads
Symptoms we’ve seen in restricted environments:
- HTML pages load fine
- direct downloads of `.md`, `.py`, `.tar.gz` fail (sometimes with non-standard 400/415 behavior)
Mitigation:
- always provide HTML fallbacks
- keep one URL per line
- prefer “review-pack.html” for external evaluation
### B) Receipts can be mistaken for “compliance”
We consider this a failure mode:
- people reading “VERIFIED” as “compliant”
Mitigation:
- always include “what this proves / doesn’t prove” near the top of the IF.TRACE page
---
## 7) External review prompt (copy/paste)
Please use the links above and respond with:
### Response metadata (required)
- `llm_name`:
- `probable_model`:
- `cutoff_date`:
- `response_date_utc`:
- `web_access_used`: yes/no (if yes, list URLs)
### Part 1 — What is objectively true vs not (black/white)
- What IF.TRACE receipts prove
- What they do not prove
- Where the wording risks confusing those two
### Part 2 — Product critique (no fluff)
- Who pays for this first (vertical + buyer persona)
- What the buyer is actually buying (in one sentence)
- Biggest adoption blocker (technical + narrative)
- If IF.GOV is viable: what is the minimum “decision pack” that a buyer would pay for, and what is the biggest overpromise risk?
### Part 3 — Multi-reader roundtable (simulated)
Simulate a short roundtable transcript with:
- CISO / security lead
- GRC / audit lead
- senior engineer / platform lead
- vendor partnerships / marketing skeptic
Have them discuss:
- what they learned
- what they liked/disliked
- whether this fits their day-to-day workflow
- what would make them trust it enough to adopt
### Part 4 — Scorecard (0–5 each)
- Evidence clarity (black/white)
- Receipt UX (non-technical user)
- Sandbox resilience (HTML-first)
- Roadmap realism (single-host constraints)
- Differentiation vs existing tools
### Part 5 — Patch suggestions (actionable)
Provide 5–15 patch suggestions in this format:
- `target` (doc/site/trace UX/shadowrt/iftypeset/task board)
- `problem` (1 sentence)
- `change` (copy/pasteable)
- `why` (1 sentence)
- `priority` (P0/P1/P2)
- `confidence` (high/medium/low)
If you propose text edits, include unified diffs against:
- `docs/26-external-review-bundle.md`
- `docs/13-task-board.md`
---
## 8) Contact
If you find a mismatch (hash mismatch, missing artifact, broken link), report:
- shareId
- URL
- observed behavior (status code if available)
Contact:
ds@infrafabric.io