feat: show task maturity and better card intros

Author: zh1peng

README.md

@@ -59,6 +59,11 @@ It:
    - optional metadata `task.yaml` / `task.yml` / `task.json` (repo root)
 4. Produces conservative inferred tags when metadata is missing (primarily from repo name).
 
+Additional parsing:
+
+- If the README includes the standard metadata table, the indexer will use `Short Description`, `PsyFlow Version`, `Language`, and `Voice Name` when present.
+- If the README includes a maturity badge like `![Maturity: smoke_tested]`, the maturity value is extracted and shown on cards.
+
 Rate limits:
 
 - Without token, GitHub API is rate-limited and the script may fail.
@@ -83,6 +88,7 @@ keywords:
   - stroop
   - interference
 
+maturity: "smoke_tested"    # optional (e.g. smoke_tested, piloted)
 psyflow_version: "^0.2.0"  # optional
 has_voiceover: false        # optional
 ```

scripts/build-index.mjs

@@ -171,6 +171,76 @@ function stripMarkdownInline(s) {
     .trim();
 }
 
+function truncate(s, max = 140) {
+  const t = String(s ?? "").trim();
+  if (!t) return "";
+  return t.length > max ? `${t.slice(0, max - 1)}?` : t;
+}
+
+function readmeTableValue(markdown, fieldName) {
+  const wanted = String(fieldName ?? "").trim().toLowerCase();
+  if (!wanted) return "";
+
+  const lines = String(markdown ?? "").split(/\r?\n/);
+  for (const line of lines) {
+    const t = String(line ?? "").trim();
+    if (!t.startsWith("|")) continue;
+
+    // Separator rows like: |-----|-----|
+    if (/^\|\s*:?-+:?\s*\|/.test(t)) continue;
+
+    let cols = t.split("|").map((c) => c.trim());
+    while (cols.length && cols[0] === "") cols = cols.slice(1);
+    while (cols.length && cols[cols.length - 1] === "") cols = cols.slice(0, -1);
+    if (cols.length < 2) continue;
+
+    const key = String(cols[0] ?? "").trim().toLowerCase();
+    if (!key || key !== wanted) continue;
+
+    const value = stripMarkdownInline(cols.slice(1).join(" | "));
+    if (!value) continue;
+    return value;
+  }
+
+  return "";
+}
+
+function normalizeLanguageLabel(v) {
+  const s = String(v ?? "").trim();
+  if (!s) return "";
+  const lower = s.toLowerCase();
+  if (lower === "en" || /\benglish\b/i.test(lower)) return "English";
+  if (lower === "zh" || /^zh\b/.test(lower) || /\bchinese\b/i.test(lower) || /\u4e2d\u6587/.test(s)) return "Chinese";
+  return s;
+}
+
+function normalizeMaturity(v) {
+  const s = String(v ?? "").trim();
+  if (!s) return "";
+  return s.toLowerCase().replace(/\s+/g, "_");
+}
+
+function extractMaturityFromReadme(markdown) {
+  const fromTable = readmeTableValue(markdown, "Maturity");
+  if (fromTable) return fromTable;
+
+  const m1 = /!\[\s*Maturity\s*:\s*([^\]]+?)\s*\]/i.exec(String(markdown ?? ""));
+  if (m1?.[1]) return m1[1].trim();
+
+  // shields.io style: .../badge/Maturity-smoke_tested-...
+  const m2 = /badge\/Maturity-([^\-\s\)]+)-/i.exec(String(markdown ?? ""));
+  if (m2?.[1]) {
+    try {
+      return decodeURIComponent(m2[1]).trim();
+    } catch {
+      return String(m2[1]).trim();
+    }
+  }
+
+  return "";
+}
+
+
 function firstParagraphDescription(markdown) {
   const text = String(markdown ?? "").replace(/<!--([\s\S]*?)-->/g, "");
   const lines = text.split(/\r?\n/).map((l) => l.trim());
@@ -254,7 +324,9 @@ function inferTagsFromRepo(repoName, markdown) {
   const language = [];
   // Only infer language when explicitly stated.
   if (/\blanguage\s*:\s*en\b/i.test(hay) || /\benglish\b/i.test(hay))
-    language.push("en");
+    language.push("English");
+  if (/\blanguage\s*:\s*zh\b/i.test(hay) || /\bchinese\b/i.test(hay) || /\u4e2d\u6587/.test(hay))
+    language.push("Chinese");
 
   return {
     paradigm: uniq(paradigm),
@@ -354,9 +426,15 @@ async function buildIndex() {
     const readmeUrl = `${GH_API}/repos/${encodeURIComponent(ORG)}/${encodeURIComponent(repo)}/readme`;
     const readme = await ghGetRaw(readmeUrl, { allow404: true });
 
+    const shortFromReadmeTable = readmeTableValue(readme, "Short Description");
     const shortFromReadme = firstParagraphDescription(readme);
     const shortFromRepo = String(r.description ?? "").trim();
 
+    const maturity = normalizeMaturity(
+      (typeof meta?.maturity === "string" ? meta.maturity : "") ||
+        extractMaturityFromReadme(readme)
+    ) || null;
+
     const tagsFromMeta = normalizeTags(meta?.tags);
     const tagsInferred = inferTagsFromRepo(repo, readme);
 
@@ -367,6 +445,14 @@ async function buildIndex() {
       language: uniq([...(tagsFromMeta.language ?? []), ...(tagsInferred.language ?? [])])
     };
 
+    // Prefer explicit README table language if present.
+    const languageFromReadme = normalizeLanguageLabel(readmeTableValue(readme, "Language"));
+    if (languageFromReadme) {
+      tags.language = uniq([...(tags.language ?? []), languageFromReadme]);
+    }
+
+    tags.language = uniq((tags.language ?? []).map(normalizeLanguageLabel).filter(Boolean));
+
     const keywords = uniq([
       ...toArray(meta?.keywords).map(String),
       ...tags.paradigm,
@@ -377,15 +463,31 @@ async function buildIndex() {
     ]);
 
     let short_description = String(meta?.short_description ?? "").trim();
-    if (!short_description) short_description = shortFromRepo;
+    if (!short_description) short_description = shortFromReadmeTable;
     if (!short_description) short_description = shortFromReadme;
+    if (!short_description) short_description = shortFromRepo;
     if (!short_description) {
       const p = tags.paradigm?.[0];
       short_description = p
         ? `${p} task template (PsyFlow/TAPS).`
         : `${repo} task template (PsyFlow/TAPS).`;
     }
 
+    short_description = truncate(short_description);
+
+    let psyflow_version = meta?.psyflow_version ?? null;
+    if (!psyflow_version) {
+      const v = readmeTableValue(readme, "PsyFlow Version");
+      psyflow_version = v || null;
+    }
+
+    let has_voiceover =
+      typeof meta?.has_voiceover === "boolean" ? meta.has_voiceover : null;
+    if (has_voiceover === null) {
+      const voiceName = readmeTableValue(readme, "Voice Name");
+      if (voiceName) has_voiceover = true;
+    }
+
     const run_anchor = readme ? detectRunAnchor(readme) : "#run";
 
     const item = {
@@ -394,11 +496,11 @@ async function buildIndex() {
       html_url: r.html_url,
       default_branch: r.default_branch,
       short_description,
+      maturity,
       tags,
       keywords,
-      psyflow_version: meta?.psyflow_version ?? null,
-      has_voiceover:
-        typeof meta?.has_voiceover === "boolean" ? meta.has_voiceover : null,
+      psyflow_version,
+      has_voiceover,
       last_updated: r.pushed_at || r.updated_at,
       structure,
       readme_run_anchor: run_anchor
@@ -416,7 +518,7 @@ async function buildIndex() {
   tasks.sort((a, b) => (a.last_updated < b.last_updated ? 1 : -1));
 
   const index = {
-    schema_version: 1,
+    schema_version: 2,
     generated_at: new Date().toISOString(),
     org: ORG,
     tasks

src/app/_components/gallery-client.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useMemo, useState } from "react";
-import type { TaskIndexItem, TaskTagFacet } from "@/lib/task-index";
+import type { TaskFacet, TaskIndexItem, TaskTagFacet } from "@/lib/task-index";
 import {
   emptySelectedFacets,
   facetValues,
@@ -10,6 +10,7 @@ import {
 } from "@/lib/task-filter";
 import { TagChip } from "@/components/tag-chip";
 import { TaskCard } from "@/components/task-card";
+import { formatMaturityLabel } from "@/components/maturity-badge";
 
 function FacetSection({
   title,
@@ -19,10 +20,10 @@ function FacetSection({
   onToggle
 }: {
   title: string;
-  facet: TaskTagFacet;
+  facet: TaskFacet;
   values: string[];
   selected: SelectedFacets;
-  onToggle: (facet: TaskTagFacet, value: string) => void;
+  onToggle: (facet: TaskFacet, value: string) => void;
 }) {
   if (values.length === 0) return null;
 
@@ -42,7 +43,7 @@ function FacetSection({
         {values.map((v) => (
           <TagChip
             key={`${facet}:${v}`}
-            label={v}
+            label={facet === "maturity" ? formatMaturityLabel(v) : v}
             selected={selected[facet].has(v)}
             onClick={() => onToggle(facet, v)}
           />
@@ -56,6 +57,7 @@ export function GalleryClient({ tasks }: { tasks: TaskIndexItem[] }) {
   const [query, setQuery] = useState<string>("");
   const [selected, setSelected] = useState<SelectedFacets>(() => emptySelectedFacets());
 
+  const allMaturities = useMemo(() => facetValues(tasks, "maturity"), [tasks]);
   const allParadigms = useMemo(() => facetValues(tasks, "paradigm"), [tasks]);
   const allResponses = useMemo(() => facetValues(tasks, "response"), [tasks]);
   const allModalities = useMemo(() => facetValues(tasks, "modality"), [tasks]);
@@ -65,14 +67,16 @@ export function GalleryClient({ tasks }: { tasks: TaskIndexItem[] }) {
 
   const anyFilters =
     query.trim().length > 0 ||
+    selected.maturity.size > 0 ||
     selected.paradigm.size > 0 ||
     selected.response.size > 0 ||
     selected.modality.size > 0 ||
     selected.language.size > 0;
 
-  function toggleFacet(facet: TaskTagFacet, value: string) {
+  function toggleFacet(facet: TaskFacet, value: string) {
     setSelected((prev) => {
       const next: SelectedFacets = {
+        maturity: new Set(prev.maturity),
         paradigm: new Set(prev.paradigm),
         response: new Set(prev.response),
         modality: new Set(prev.modality),
@@ -121,6 +125,13 @@ export function GalleryClient({ tasks }: { tasks: TaskIndexItem[] }) {
             </div>
           </section>
 
+          <FacetSection
+            title="Maturity"
+            facet="maturity"
+            values={allMaturities}
+            selected={selected}
+            onToggle={toggleFacet}
+          />
           <FacetSection
             title="Paradigm"
             facet="paradigm"
@@ -177,7 +188,7 @@ export function GalleryClient({ tasks }: { tasks: TaskIndexItem[] }) {
               <TaskCard
                 key={t.repo}
                 task={t}
-                onTagClick={(facet, value) => toggleFacet(facet, value)}
+                onTagClick={(facet: TaskTagFacet, value) => toggleFacet(facet, value)}
               />
             ))}
           </div>

src/app/about/page.tsx

@@ -90,6 +90,7 @@ keywords:
   - stroop
   - interference
 
+maturity: "smoke_tested"    # optional (e.g. smoke_tested, piloted)
 psyflow_version: "^0.2.0"  # optional
 has_voiceover: false        # optional`}</code>
             </pre>

src/app/tasks/[repo]/page.tsx

@@ -5,6 +5,7 @@ import type { Metadata } from "next";
 import { notFound } from "next/navigation";
 
 import { CopyButton } from "@/components/copy-button";
+import { MaturityBadge } from "@/components/maturity-badge";
 import { Markdown } from "@/components/markdown";
 import { formatShortDate } from "@/lib/format";
 import { findTaskByRepo, getTasks, taskLinks } from "@/lib/task-index";
@@ -132,6 +133,13 @@ export default function TaskPage({ params }: { params: { repo: string } }) {
                   </div>
                 </div>
 
+                {task.maturity ? (
+                  <div className="flex items-center justify-between gap-3">
+                    <div className="text-slate-600">Maturity</div>
+                    <MaturityBadge maturity={task.maturity} className="shrink-0" />
+                  </div>
+                ) : null}
+
                 {task.psyflow_version ? (
                   <div className="flex items-center justify-between gap-3">
                     <div className="text-slate-600">PsyFlow</div>

src/components/maturity-badge.tsx

@@ -0,0 +1,58 @@
+import clsx from "@/components/utils/clsx";
+
+export function formatMaturityLabel(maturity: string) {
+  const k = String(maturity ?? "").trim().toLowerCase().replace(/\s+/g, "_");
+  const s = k.replace(/[_-]+/g, " ").trim();
+  if (!s) return "";
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function maturityClasses(maturity: string) {
+  const k = String(maturity ?? "").trim().toLowerCase().replace(/\s+/g, "_");
+
+  if (k === "smoke_tested") {
+    return "border-amber-200 bg-amber-50 text-amber-950";
+  }
+
+  if (k === "piloted") {
+    return "border-lime-200 bg-lime-50 text-lime-950";
+  }
+
+  if (k === "alpha") {
+    return "border-fuchsia-200 bg-fuchsia-50 text-fuchsia-950";
+  }
+
+  if (k === "beta") {
+    return "border-sky-200 bg-sky-50 text-sky-950";
+  }
+
+  if (k === "validated" || k === "production") {
+    return "border-emerald-200 bg-emerald-50 text-emerald-950";
+  }
+
+  return "border-slate-200 bg-slate-50 text-slate-800";
+}
+
+export function MaturityBadge({
+  maturity,
+  className
+}: {
+  maturity: string;
+  className?: string;
+}) {
+  const label = formatMaturityLabel(maturity);
+  if (!label) return null;
+
+  return (
+    <span
+      title={`Maturity: ${label}`}
+      className={clsx(
+        "inline-flex items-center rounded-full border px-3 py-1 text-xs font-semibold",
+        maturityClasses(maturity),
+        className
+      )}
+    >
+      {label}
+    </span>
+  );
+}

src/components/task-card.tsx

@@ -5,6 +5,7 @@ import type { TaskIndexItem, TaskTagFacet } from "@/lib/task-index";
 import { taskLinks } from "@/lib/task-index";
 import { formatShortDate } from "@/lib/format";
 import { TagChip } from "@/components/tag-chip";
+import { MaturityBadge } from "@/components/maturity-badge";
 import { IconArrowRight, IconDownload, IconGithub, IconPlay } from "@/components/icons";
 
 function TagRow({
@@ -52,14 +53,15 @@ export function TaskCard({
     <div className="group flex h-full flex-col rounded-2xl border border-slate-200 bg-white/85 p-5 shadow-sm transition-colors hover:border-brand-200 hover:bg-white">
       <div className="flex items-start justify-between gap-4">
         <div className="min-w-0">
-          <div className="flex items-center gap-2">
+          <div className="flex flex-wrap items-center gap-2">
             <Link
               className="tb-focus-ring rounded-md font-heading text-base font-semibold tracking-tight text-slate-900 hover:text-brand-900"
               href={`/tasks/${encodeURIComponent(task.repo)}`}
             >
               {task.repo}
             </Link>
             <IconArrowRight className="size-4 text-slate-400 transition-colors group-hover:text-brand-700" />
+            {task.maturity ? <MaturityBadge maturity={task.maturity} /> : null}
           </div>
           <div className="mt-2 text-sm leading-6 text-slate-700">
             {task.short_description || "No description provided."}