@freetesh/canon 0.16.0 → 0.18.0

package/scripts/flow.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""How far each Claude conversation about a product got, measured against the
+product's own stages (`canon pipeline`), and how long each step took. Counts
+and times only; no prompt text leaves this machine.
+
+    canon flow askcal            print the numbers
+    canon flow askcal --write    also write <product>/.context/metrics/flow.json
+
+`canon flow` runs this with CANON_WORKSPACE (the folder holding the products) and
+CANON_FLOW_FORMERLY (each product's older folder names, from `formerly:` in its canon.yaml).
+
+The transcripts live in ~/.claude/projects and CI cannot see them, so this
+runs here and the product repo carries the result.
+
+A conversation is a transcript with at least one typed request. Its commits
+are the repo commits made within MATCH_SECONDS of a `git commit` it ran (rtk
+prints "ok", not the hash, so time is the link). What each stage needs:
+
+  idea          the conversation exists
+  research      it searched or fetched the web, or a commit touched
+                .context/raw/ or .context/wiki/synthesis/
+  plan          a commit touched .context/features/, tasks.md or wiki/decisions/
+  design        a commit touched .context/designs/
+  code          a commit touched anything outside .context/ and .claude/
+  review        a commit is in a merged pull request
+  release       a version tag holds a commit (an untagged version: the commit that set it)
+  store-review  the version release.yml lists as in review holds a commit
+  deployed      a GitHub deployment, or the web commit release.yml lists, holds a commit
+  live          a version release.yml lists as live holds a commit
+
+A conversation counts at every stage up to the furthest it reached.
+"""
+import glob
+import json
+import os
+import re
+import statistics
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+MATCH_SECONDS = 120
+PRODUCTS = os.environ["CANON_WORKSPACE"]
+TRANSCRIPTS = os.path.expanduser("~/.claude/projects")
+COMMIT_CALL = re.compile(r"\bgit\b[^|;&]*\bcommit\b")
+# A release is a version tag; `stash-bak-0` and friends are not.
+RELEASE_TAG = re.compile(r"^(?:[a-z]+-)?v(\d+\.\d+(?:\.\d+)?)")
+WEB_TOOLS = {"WebSearch", "WebFetch"}
+# A renamed product's conversations under its old folder name are still about it.
+ALIASES = json.loads(os.environ.get("CANON_FLOW_FORMERLY") or "{}")
+PRODUCT_PATH = re.compile(re.escape(PRODUCTS) + r"/([A-Za-z0-9._-]+)")
+KNOWN = ["idea", "research", "plan", "design", "code", "review", "release", "store-review", "deployed", "live"]
+TOUCH = {
+    "research": (".context/raw/", ".context/wiki/synthesis/"),
+    "plan": (".context/features/", ".context/tasks.md", ".context/wiki/decisions/"),
+    "design": (".context/designs/",),
+}
+
+
+def ts(s):
+    return datetime.fromisoformat(str(s).replace("Z", "+00:00"))
+
+
+def day(v):
+    """A release.yml date: '2026-10-27' or a full timestamp."""
+    return ts(v) if "T" in str(v) else ts(f"{v}T00:00:00+00:00")
+
+
+def run(*cmd, cwd=None):
+    return subprocess.run(cmd, capture_output=True, text=True, check=True, cwd=cwd).stdout
+
+
+def git(repo, *args):
+    return run("git", "-C", repo, *args)
+
+
+def read_session(path):
+    """Start, typed requests, `git commit` call times, first web-research time, and the
+    product folders it worked in (its working folders and the paths its tools named;
+    never tool output, which can list every product)."""
+    times, commits, asks, web, where = [], [], 0, None, set()
+    with open(path, errors="ignore") as f:
+        for line in f:
+            try:
+                e = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not e.get("timestamp"):
+                continue
+            t = ts(e["timestamp"])
+            times.append(t)
+            where.update(PRODUCT_PATH.findall(e.get("cwd") or ""))
+            content = e.get("message", {}).get("content")
+            if e.get("type") == "user" and not e.get("isMeta") and isinstance(content, str) and not content.lstrip().startswith("<"):
+                asks += 1
+            if e.get("type") == "assistant" and isinstance(content, list):
+                for c in content:
+                    if c.get("type") != "tool_use":
+                        continue
+                    where.update(PRODUCT_PATH.findall(json.dumps(c.get("input", {}))))
+                    if c.get("name") in WEB_TOOLS and web is None:
+                        web = t
+                    if COMMIT_CALL.search(c.get("input", {}).get("command", "")):
+                        commits.append(t)
+    if not times or asks == 0:
+        return None
+    return {"start": min(times), "calls": commits, "web": web, "where": where}
+
+
+def all_sessions():
+    # Every folder: a conversation started in ~ or ~/git can still have worked in a product.
+    return {p: s for p in glob.glob(f"{TRANSCRIPTS}/*/*.jsonl") if (s := read_session(p))}
+
+
+def stages_of(repo):
+    """The product's own stages, as canon resolves them."""
+    ids = [s["id"] for s in json.loads(run("canon", "pipeline", repo, "--json"))]
+    unknown = [i for i in ids if i not in KNOWN]
+    if unknown:
+        sys.exit(f"{repo}: no evidence rule for stage(s) {', '.join(unknown)} — known: {', '.join(KNOWN)}")
+    return ids
+
+
+def release_state(repo):
+    """release.yml as data. Ruby's YAML is on every Mac; Python's is not."""
+    path = os.path.join(repo, ".context", "ops", "release.yml")
+    if not os.path.exists(path):
+        return {}
+    out = run("ruby", "-ryaml", "-rjson", "-rdate", "-e",
+              "puts YAML.load_file(ARGV[0], permitted_classes: [Date, Time, Symbol]).to_json", path)
+    return json.loads(out).get("surfaces") or {}
+
+
+def version_of(value):
+    """'1.4.3', '2.0.1 (15)', {version: '1.4.3'} → '1.4.3'."""
+    if isinstance(value, dict):
+        value = value.get("version") or value.get("string")
+    m = re.match(r"\s*v?(\d+\.\d+(?:\.\d+)?)", str(value)) if value else None
+    return m.group(1) if m else None
+
+
+def reachable(repo, ref):
+    try:
+        return set(git(repo, "rev-list", ref).split())
+    except subprocess.CalledProcessError:
+        return set()
+
+
+def repo_facts(repo):
+    tags = []
+    for line in git(repo, "tag", "--format=%(refname:short) %(creatordate:iso-strict)").splitlines():
+        name, _, date = line.partition(" ")
+        m = RELEASE_TAG.match(name)
+        if m:
+            tags.append((ts(date), name, m.group(1)))
+    tags.sort()
+    released, by_version = {}, {}
+    for date, name, version in tags:  # oldest first: a commit's release is the first tag that holds it
+        held = reachable(repo, name)
+        by_version.setdefault(version, set()).update(held)
+        for sha in held:
+            released.setdefault(sha, date)
+
+    slug = re.sub(r"^.*github\.com[:/]|\.git$", "", git(repo, "remote", "get-url", "origin").strip())
+
+    def version_held(v):
+        """What a version holds: its tag, or — when it was never tagged — everything up to the
+        commit that first set that version (`chore(release): 1.4.3 (build 17)`)."""
+        if v in by_version:
+            return by_version[v]
+        bump = git(repo, "log", "--all", "--reverse", "--format=%H %cI", "-S", f'"version": "{v}"').split("\n")[0].split()
+        if not bump:
+            return set()
+        held = reachable(repo, bump[0])
+        for sha in held:
+            released.setdefault(sha, ts(bump[1]))
+        return held
+
+    surfaces = release_state(repo)
+    in_review, live, deployed = set(), set(), {}
+    review_at = None
+    for key, s in surfaces.items():
+        if not isinstance(s, dict) or s.get("verified") is False:
+            continue
+        v = version_of(s.get("in_review"))
+        if v:
+            in_review |= version_held(v)
+            sub = s["in_review"].get("submitted") if isinstance(s.get("in_review"), dict) else None
+            review_at = day(sub) if sub else review_at
+        lv = version_of(s.get("live"))
+        if lv:
+            live |= version_held(lv)
+        dep = s.get("deployed")
+        if key == "web" and isinstance(dep, dict) and dep.get("commit"):
+            when = day(dep["since"]) if dep.get("since") else None
+            for sha in reachable(repo, str(dep["commit"])):
+                deployed.setdefault(sha, when)
+
+    # Every deployment GitHub recorded (Vercel and Cloudflare post them), oldest first.
+    try:
+        pages = json.loads(run("gh", "api", "--paginate", "--slurp", f"repos/{slug}/deployments?per_page=100"))
+        for d in sorted((d for page in pages for d in page), key=lambda d: d["created_at"]):
+            for sha in reachable(repo, d["sha"]):
+                deployed.setdefault(sha, ts(d["created_at"]))
+    except (subprocess.CalledProcessError, FileNotFoundError, json.JSONDecodeError) as e:
+        print(f"  {os.path.basename(repo)}: deployments not read ({getattr(e, 'stderr', '') or e}); Deployed counts only release.yml", file=sys.stderr)
+
+    merged = {}
+    try:
+        pulls = json.loads(run("gh", "api", "--paginate", "--slurp", f"repos/{slug}/pulls?state=closed&per_page=100"))
+        for pr in (p for page in pulls for p in page if p.get("merged_at")):
+            when = ts(pr["merged_at"])
+            merged[pr["merge_commit_sha"]] = when
+            # A squash merge makes a new commit; the conversation's own commits are the PR's.
+            for c in json.loads(run("gh", "api", "--paginate", "--slurp", f"repos/{slug}/pulls/{pr['number']}/commits?per_page=100")):
+                for commit in c:
+                    merged.setdefault(commit["sha"], when)
+    except (subprocess.CalledProcessError, FileNotFoundError, json.JSONDecodeError) as e:
+        # Review then shows 0, never a guess — and says why.
+        print(f"  {os.path.basename(repo)}: pull requests not read ({getattr(e, 'stderr', '') or e}); Review counts nothing", file=sys.stderr)
+    return {"released": released, "merged": merged, "in_review": in_review, "review_at": review_at,
+            "live": live, "deployed": deployed}
+
+
+def touched(repo, sha):
+    return git(repo, "show", "--name-only", "--format=", sha).split()
+
+
+def reached(session, commits, repo, facts):
+    """{stage: when it was first reached} for one conversation."""
+    at = {"idea": session["start"]}
+    if session["web"]:
+        at["research"] = session["web"]
+    for sha, when in sorted(commits, key=lambda c: c[1]):
+        files = touched(repo, sha)
+        for stage, prefixes in TOUCH.items():
+            if any(f.startswith(prefixes) for f in files):
+                at.setdefault(stage, when)
+        if any(not f.startswith((".context/", ".claude/")) for f in files):
+            at.setdefault("code", when)
+        if sha in facts["merged"]:
+            at.setdefault("review", facts["merged"][sha])
+        if sha in facts["released"]:
+            at.setdefault("release", facts["released"][sha])
+        if sha in facts["in_review"]:
+            at.setdefault("store-review", facts["review_at"] or facts["released"].get(sha))
+        if sha in facts["deployed"]:
+            at.setdefault("deployed", facts["deployed"][sha])
+        if sha in facts["live"]:
+            at.setdefault("live", facts["released"].get(sha))
+    return at
+
+
+def flow(product, sessions):
+    repo = os.path.join(PRODUCTS, product)
+    stages = stages_of(repo)
+    log = [l.split() for l in git(repo, "log", "--all", "--format=%H %cI").splitlines() if l]
+    commits = [(h, ts(d)) for h, d in log]
+    facts = repo_facts(repo)
+    names = {product, *ALIASES.get(product, [])}
+
+    furthest, waits, first = [], {f"{a}→{b}": [] for a, b in zip(stages, stages[1:])}, None
+    for path, s in sessions.items():
+        mine = [c for c in commits if any(abs((c[1] - t).total_seconds()) <= MATCH_SECONDS for t in s["calls"])]
+        if not (s["where"] & names) and not mine:
+            continue  # never worked in this product's folder, under any of its names, nor committed to it
+        first = min(first, s["start"]) if first else s["start"]
+        at = reached(s, mine, repo, facts)
+        hit = [i for i, st in enumerate(stages) if st in at]
+        furthest.append(max(hit))
+        for a, b in zip(stages, stages[1:]):
+            if a in at and b in at and at[a] and at[b] and at[b] >= at[a]:
+                waits[f"{a}→{b}"].append((at[b] - at[a]).total_seconds() / 3600)
+
+    return {
+        "$comment": "GENERATED by `canon flow` from local Claude transcripts, git, GitHub and release.yml. Counts only. Do not hand-edit.",
+        "updated": datetime.now(timezone.utc).date().isoformat(),
+        "since": first.date().isoformat() if first else None,
+        "stages": [{"id": st, "count": sum(1 for f in furthest if f >= i)} for i, st in enumerate(stages)],
+        "medianHours": {k: round(statistics.median(v), 1) if v else None for k, v in waits.items()},
+    }
+
+
+def self_check():
+    assert RELEASE_TAG.match("v1.4.1") and RELEASE_TAG.match("mobile-v0.1.1")
+    assert not RELEASE_TAG.match("stash-bak-0")
+    assert COMMIT_CALL.search('git -C askcal commit -m "x"') and COMMIT_CALL.search("git commit -q -F -")
+    assert not COMMIT_CALL.search("git status; echo commit")
+    assert day("2026-10-27").hour == 0 and day("2026-09-30T17:43:43+00:00").hour == 17
+    assert version_of("2.0.1 (15)") == "2.0.1" and version_of({"version": "1.4.3"}) == "1.4.3" and version_of(None) is None
+
+
+def main():
+    self_check()
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    if not args:
+        sys.exit("usage: canon flow <product>... [--write]")
+    sessions = all_sessions()
+    for product in args:
+        if not os.path.isdir(os.path.join(PRODUCTS, product, ".git")):
+            sys.exit(f"{product}: not a repo under {PRODUCTS}")
+        result = flow(product, sessions)
+        print(product, " → ".join(f"{s['id']} {s['count']}" for s in result["stages"]), "| since", result["since"])
+        if "--write" in sys.argv:
+            out = os.path.join(PRODUCTS, product, ".context", "metrics", "flow.json")
+            os.makedirs(os.path.dirname(out), exist_ok=True)
+            with open(out, "w") as f:
+                json.dump(result, f, indent=2, ensure_ascii=False)
+                f.write("\n")
+
+
+if __name__ == "__main__":
+    main()

package/skills/ingest/SKILL.md

@@ -22,7 +22,7 @@ Source to ingest: `$ARGUMENTS`
    - A user journey description → a concept, only if it holds a rule the designs don't show
    - Write nothing an agent could read from the code, the designs or git.
    - Don't force one source into one page — a meeting note can produce multiple pages.
-   - Folders are the four in the schema plus any listed under `wiki.types` in the repo's or the estate's `.claude/canon.yaml`, each with its folder and its required `sections` (use its `sections` headings). Use an added type only when the source fits it.
+   - Folders are the four in the schema plus any listed under `wiki.types` in the repo's `.claude/canon.yaml`, each with its folder and its required `sections` (use its `sections` headings). Use an added type only when the source fits it.
 
 4. **For each page you will create:**
    - Filename: the topic, lowercase kebab-case, no date.

package/standards/README.md

@@ -1,14 +1,31 @@
 # standards/
 
-canon's default standards. `canon standards` lists the ones that apply to a repo:
-these first, then each folder named under `standards:` in the estate's and the
-repo's `.claude/canon.yaml`. A configured file with the same name as one of these
-replaces it; a configured `constitution.md` adds principles instead.
+canon's standards. `canon standards` lists the ones that apply to a repo.
+
+## Defaults — apply to every repo
 
 | File | What it holds |
 |---|---|
-| `constitution.md` | The principles a request is weighed against (C-01 to C-13) |
+| `constitution.md` | The principles a request is weighed against (C-01 to C-15; C-01 to C-19 are canon's) |
 | `wiki-schema.md` | Wiki page types, frontmatter, required sections, lint rules |
-| `context-layout.md` | The `.context/` ten-folder layout, where each kind of document lives, `features/` and `tasks.md` formats |
+| `context-layout.md` | The `.context/` ten-folder layout, where each kind of document lives, the repo root, `features/` and `tasks.md` formats |
 | `dev-methods.md` | The evidence spec-, test- and data-driven work leaves behind |
 | `agent-contract.md` | What every agent does before, during and after work |
+
+## Library — a repo opts in by name
+
+A repo lists the ones it wants in `.claude/canon.yaml`:
+`standards: [design-sets, pipeline, expo]`.
+
+| Name | What it holds |
+|---|---|
+| `design-sets` | HTML design sets: layout, `routes.js`, the navbar, the flow chart, tokens, checks |
+| `pipeline` | The five stages and their hard gates; principles C-16 and C-17 |
+| `expo` | Scaffolding an Expo app, its layout, the versioned-docs rule, release checks |
+| `frontend` | `.tsx` code rules: one component per file, thin routes, helpers in `lib/` and `hooks/`, UniWind |
+| `performance` | No redraw after a local edit, counted round trips, no blank navigation, a number before and after |
+| `secrets` | Every secret backed up the moment it exists; key names only in `INVENTORY.md` |
+| `store-listing` | `.context/listing/` as fastlane's tree, screenshots, release notes from `features/` |
+
+A library standard may add principles in the constitution's `### C-NN Title`
+format; they apply only to repos that opt in.

package/standards/agent-contract.md

@@ -8,7 +8,9 @@ file with its own `agent-contract.md` in a configured standards folder.
 - Read the repo's `CLAUDE.md` / `AGENTS.md`: stack, layout, the rules that are
   the repo's own.
 - Read `.context/tasks.md`. It is the ordered queue — the top item of `## Now`
-  is the next action. After finishing, delete the task.
+  is the next action. After finishing, delete the task. The repo's `AGENTS.md`
+  (or `CLAUDE.md`) carries these two lines, because without them an agent that
+  was not told about `.context/` never finds it.
 - For a non-trivial request, run the weigh gate first (`/canon:weigh`).
 
 ## Repository rules
@@ -17,10 +19,11 @@ file with its own `agent-contract.md` in a configured standards folder.
    (`context-layout.md`). The wiki is the knowledge base; its schema is
    `wiki-schema.md`.
 2. Do not add top-level `docs/` or `wireframes/` folders, or root `TODO.md`,
-   `STATUS.md` or `SETUP.md`. Files a host or tool reads by exact path —
-   `README.md`, `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`,
-   `.github/` — stay at the root.
+   `STATUS.md` or `SETUP.md`. What stays at the root, and where the rest goes:
+   `context-layout.md`, "Repo root".
 3. Generated folders are never hand-edited; change their source and regenerate.
+4. File names are lowercase kebab-case unless the language says otherwise.
+5. Names follow the repo's current identity, not a legacy name.
 
 ## Replies
 
@@ -34,13 +37,25 @@ Write a comment only to explain **why**. The code already says how.
 
 A comment earns its place when it records something the reader cannot recover
 from the code: a constraint, a trade-off, a bug it prevents, or a non-obvious
-consequence. If it restates what the next line does, delete it. No
+consequence. If it restates what the next line does, delete it.
+
+```ts
+// Good — the reason is invisible in the code:
+// Prune only. Recomputing here would discard the user's per-pack choices
+// on every launch, which is the bug this replaced.
+state.selectedPackIds = prunePackIds(...);
+
+// Bad — narrates the mechanism:
+// Loop over the packs and filter out the locked ones
+```
+
+No
 section-divider comments, no changelog comments, no comments restating a
 function's own name.
 
 ## Before calling work done
 
-1. Update any `.context/` page the change made wrong. Add a page only if an
+1. Update `CLAUDE.md` and any `.context/` page the change made wrong. Add a page only if an
    agent would get something wrong without it.
 2. Run the repo's own lint, typecheck and tests.
 3. Run `canon check`. Every checker the repo declares under `commands:` runs

package/standards/context-layout.md

@@ -24,8 +24,9 @@ folder.
 ## Rules
 
 1. **Ten folders, one job each.** There is no `documents/`, `research/`,
-   `architecture/` or `decisions/` folder: a research brief is a wiki synthesis
-   page, an architecture note is a wiki concept, an ADR is `wiki/decisions/`.
+   `architecture/`, `decisions/` or `email-templates/` folder: a research brief
+   is a wiki synthesis page, an architecture note is a wiki concept, an ADR is
+   `wiki/decisions/`, a transactional email is HTML in `designs/`.
    A product that truly needs another folder adds it in `.claude/canon.yaml`,
    with the reason: `context: { folders: [{ folder: research, reason: … }] }`.
    The ten cannot be removed.
@@ -38,7 +39,8 @@ folder.
 4. **One home per artifact; everything else is an export.** Source art lives in
    `designs/`; store images and press kits are generated from it.
 5. **Authored vs generated is visible.** A generated file is committed but never
-   hand-edited.
+   hand-edited. Its source is a hand-written file such as `marketing/context.md`,
+   `metrics/definitions.yml` or `metrics/events.yml`.
 
 ## What a repo is expected to have
 
@@ -46,14 +48,15 @@ folder.
 |---|---|
 | any repo | `README.md` · `tasks.md` |
 | uses the `docs` or `knowledge` module | + `raw/` · `wiki/` · `features/` |
-| draws its UI | + `designs/` (optional; an estate can require it with a command) |
+| draws its UI | + `designs/` (required for a mobile or web repo: designs come first) |
 | has a store presence | + `listing/` |
 | is live to users | + `marketing/` · `metrics/` · `support/` · `legal/` |
 | once something runs | + `ops/` |
 
 ## Naming and frontmatter
 
-- Dated sources (`raw/`) → ISO date: `YYYY-MM-DD-slug.md`.
+- Dated sources (`raw/`) → ISO date: `YYYY-MM-DD-slug.md`. Month-grain data
+  keeps `YYYY-MM.csv`.
 - Features → zero-padded number: `NNNN-slug.md`.
 - Everything else is named by topic and edited in place.
 - Frontmatter: `last-verified`, kebab-case keys. See the wiki schema.
@@ -74,10 +77,40 @@ separate folder per name.
 | Know-how | `wiki/concepts/`; `ops/` when it is a runbook |
 | Bug | the issue tracker; a wiki concept only when it teaches a rule |
 | Data source | `wiki/entities/` — see the wiki schema, "Data sources" |
+| Setup notes (account IDs, console links, where credentials live) | `ops/setup.md` |
+| What is live right now, per surface | `ops/release.yml` |
+| Runbook | `ops/runbooks/<slug>.md` |
+| Incident | `ops/incidents/YYYY-MM-DD-<slug>.md` |
+| Dated engineering narrative | `CHANGELOG.md` at the repo root |
 
 If a document fits none of these for a real product, add a wiki type or a
 folder in `.claude/canon.yaml` with its reason — not a new convention by hand.
 
+## Inside the folders
+
+A folder holds only what it uses; these are the usual names.
+
+```
+marketing/   context.md (identity, goals, markets) · brand/ (WORDS only — art is in designs/brand/)
+             posts/ · video/ · launch/ · press/ (press/media/ is an export of designs/brand/)
+metrics/     definitions.yml (the KPI dictionary) · events.yml (what each event means)
+             history/YYYY-MM.csv (metric,period,value)
+support/     SUPPORT.md · faq/ · replies/ · reviews/
+legal/       privacy policy · terms · data deletion
+ops/         release.yml · setup.md · runbooks/ · incidents/
+```
+
+## Repo root
+
+These stay at the root, because a host renders them or a tool reads them by
+exact path: `README.md` · `LICENSE` · `CHANGELOG.md` · `CONTRIBUTING.md` ·
+`SECURITY.md` · `CLAUDE.md` · `AGENTS.md` · `.github/`.
+
+`TODO.md`, `STATUS.md` and `SETUP.md` do not. `SETUP.md` becomes `ops/setup.md`.
+The other two are not single documents, so split them: the backlog goes to
+`tasks.md`, what is live to `ops/release.yml`, the dated narrative to
+`CHANGELOG.md`, canonical values to `wiki/entities/`, a how-to to `ops/runbooks/`.
+
 ## `features/` — what is next
 
 One page per feature, `NNNN-<slug>.md`:
@@ -88,7 +121,9 @@ id: FEAT-0031
 type: feature             # feature | experiment | chore | platform
 status: building          # planned | building | shipped | shelved | superseded
 last-verified: 2026-04-02
-release: 3.4.0
+release: 3.4.0            # ties to CHANGELOG.md and the release notes
+superseded-by: null
+surfaces: ["[[settings-screen]]"]
 ---
 ## Summary · ## Motivation · ## Acceptance scenarios (Given/When/Then)
 ## Out of scope · ## Open questions
@@ -100,7 +135,7 @@ An experiment adds `## Hypothesis`, `## Metric` (a name from
 `metrics/definitions.yml`) and `## Result` once it has run.
 
 The wiki describes what *is*; `features/` describes what is *next*. A shipped
-feature goes `status: shipped`.
+feature goes `status: shipped` and is never deleted, so the reasoning survives.
 
 ## `tasks.md` — open work only