linx-superproject

name	linx-superproject
description	LinxISA superproject governance and cross-repo execution workflow. Use when managing submodule topology, dual-lane pin/external sync, AVS gate reproducibility, SHA manifest reporting, or workload matrix publication across llvm/qemu/linux/LinxCore/pyCircuit/glibc/musl.

Linx Superproject

Overview

Use this skill for root-level coordination in /Users/zhoubot/linx-isa: topology rules, lane sync, gate truth, and cross-stack reporting.

Core policy (mandatory)

• Keep LinxISA links in root .gitmodules only.
• Keep no inter-leaf LinxISA submodule links.
• Keep a single in-repo source of truth; do not route work to external trees such as /Users/zhoubot/qemu or /Users/zhoubot/linux.
• Keep required submodules in sync:
  • compiler/llvm
  • emulator/qemu
  • kernel/linux
  • rtl/LinxCore
  • tools/pyCircuit
  • lib/glibc
  • lib/musl
  • workloads/pto_kernels
  • skills/linx-skills

LinxCore maturity collaboration contract

• Canonical governance files:
  • docs/bringup/agent_runs/manifest.yaml
  • docs/bringup/agent_runs/waivers.yaml
  • docs/bringup/gates/latest.json
• Active phase is controlled by manifest.phase_policy.active_phase (G0..G5).
• Waivers are phase-bound and must include owner, issue, phase, and expires_utc.
• Required non-waived gates must pass in both pin and external lanes.
• Evidence pack per run must include:
  • canonical gate report row,
  • SHA manifest,
  • gate logs,
  • multi-agent summary JSON.

Owner map for collaboration

• arch: architecture docs and contract lint gates.
• linx-core: RTL/cosim/superscalar gates.
• testbench: ROB/replay/verification gates.
• pycircuit: pyCircuit flow and interface-contract gates.
• trace: LinxTrace schema/compatibility/viewer-sync gates.
• integration: strict closure, performance floor, dual-lane parity.

Canonical sync commands

git submodule sync --recursive
git submodule update --init --recursive
bash tools/ci/check_repo_layout.sh

Worktree Hygiene (single canonical checkout)

• For bring-up, keep a single canonical superproject folder: /Users/zhoubot/linx-isa.
• Avoid creating persistent linx-isa-* clones/worktrees under /Users/zhoubot/.

Audit and cleanup:

git -C /Users/zhoubot/linx-isa worktree list
git -C /Users/zhoubot/linx-isa worktree prune

If a worktree contains submodules, removal may require --force:

git -C /Users/zhoubot/linx-isa worktree remove --force <path>
git -C /Users/zhoubot/linx-isa worktree prune

Generated Artifact Storage Hygiene

• Treat workloads/generated/, avs/qemu/out, .omx/tmp*.log, and generated QEMU/model trace logs as disposable unless a current report explicitly cites a small artifact from that run.
• After workload or QEMU triage, preserve the machine-readable summary (report.json, summary.md, gate JSON/MD, and any manifest cited in docs) before deleting bulky rerunnable products such as QEMU logs, *.trace, generated initramfs *.cpio, copied SPEC run directories, and temporary debug output.
• Do not delete source workload trees, SPEC installed input data, submodule git object packs, compiler/QEMU build trees, or user documents as routine cleanup. If storage pressure requires those, make it an explicit user-visible tradeoff.
• Before continuing a broad loop after a large run, check du -xhd1 /Users/zhoubot/linx-isa and prune generated artifacts if workloads/generated or avs/qemu/out has grown beyond the evidence needed by the current packet.

Skills sync policy (mandatory per bring-up cycle)

git -C /Users/zhoubot/linx-isa submodule update --init --recursive skills/linx-skills
git -C /Users/zhoubot/linx-isa/skills/linx-skills fetch origin main
git -C /Users/zhoubot/linx-isa/skills/linx-skills checkout origin/main

# Install/prune canonical skills into $CODEX_HOME/skills (defaults to $HOME/.codex/skills).
bash /Users/zhoubot/linx-isa/skills/linx-skills/scripts/install_canonical_skills.sh

python3 /Users/zhoubot/linx-isa/skills/linx-skills/scripts/check_skill_change_scope.py \
  --repo-root /Users/zhoubot/linx-isa/skills/linx-skills --base origin/main

• Start each superproject bring-up run from latest skills/linx-skills.
• Summarize skill deltas after bring-up and repin skills/linx-skills SHA.
• Use $linx-skills-submodule for safe, non-destructive skill maintenance.

Tooling reliability (common)

• If git fetch fails with LibreSSL SSL_connect: SSL_ERROR_SYSCALL, force Git to HTTP/1.1:

git config http.version HTTP/1.1
# or per-submodule:
git -C tools/pyCircuit config http.version HTTP/1.1

• If gh GraphQL calls fail with TLS handshake timeout / EOF, retry with a larger timeout:

GH_HTTP_TIMEOUT=300 gh <command>

• linx-isa disallows merge commits; use squash merges:

gh pr merge <PR> --squash

Skill evolve loop (mandatory closeout)

• Every module agent must run an explicit update/no-update decision at run closeout.
• Update skills only for material reusable findings:
  • new cross-module contract/invariant/gate,
  • new recurring triage workflow,
  • new mandatory reproducibility command/env/artifact.
• Skip skill updates for minor optimizations, wording, or one-off local workarounds.
• Require one evidence line per module in integration notes:
  • skill-evolve: update ... or skill-evolve: no-update ....
• To avoid loops/churn, bundle material findings from a run into one skills update.

Canonical gate commands

Retired public 0.3/0.4 guard scripts and historical compatibility wrappers are not active gates. Use the canonical v0.57 checks directly. v0.57 is built as the sole active ISA release; the v0.57 release manifest records its reviewed assignments and conformance policy:

python3 /Users/zhoubot/linx-isa/tools/isa/build_golden.py --profile v0.57 --check
python3 /Users/zhoubot/linx-isa/tools/isa/validate_spec.py --profile v0.57
python3 /Users/zhoubot/linx-isa/tools/isa/check_canonical_v057.py --root /Users/zhoubot/linx-isa
python3 /Users/zhoubot/linx-isa/tools/isa/check_pto_v057_manifest.py --root /Users/zhoubot/linx-isa
python3 /Users/zhoubot/linx-isa/tools/bringup/check_sail_model.py --require-parser --require-c-backend

Keep CI/workflow names on active public-v057 surfaces. Legacy retired-public surfaces are historical comparison only and must not be used to claim v0.57 closure.

v0.57 integration handoff must prove cross-repo agreement on:

• scalar CAS and DMA forms in ISA golden, compiler MC coverage, and QEMU decode;
• TPREFETCH as destination-free TLOAD, encoded adjacent to TLOAD/TSTORE and publishing no destination/result;
• dense TMA selector coverage 0..8;
• unique named CUBE block/template identities across ISA, compiler, PTOAS, and QEMU metadata;
• the 111-operation PTO map from the v0.57 PTO workbook/manifest; and
• rejection of stale legacy selector, template, and PTO spellings unless the v0.57 catalog explicitly admits them.

PR tier strict closure:

LINX_GATE_TIER=pr RUN_EXTENDED_CROSS_GATES=1 \
bash /Users/zhoubot/linx-isa/tools/regression/strict_cross_repo.sh

Nightly tier strict closure:

LINX_GATE_TIER=nightly RUN_EXTENDED_CROSS_GATES=1 RUN_PERF_FLOOR_GATES=1 \
bash /Users/zhoubot/linx-isa/tools/regression/strict_cross_repo.sh

Dual-lane runtime convergence:

LINX_GATE_TIER=pr RUN_EXTENDED_CROSS_GATES=1 \
bash /Users/zhoubot/linx-isa/tools/bringup/run_runtime_convergence.sh --lane pin --run-id <run-id-pin>
LINX_GATE_TIER=pr RUN_EXTENDED_CROSS_GATES=1 \
bash /Users/zhoubot/linx-isa/tools/bringup/run_runtime_convergence.sh --lane external --run-id <run-id-ext>

Benchmark/QEMU/Linux hard-break flow:

python3 /Users/zhoubot/linx-isa/tools/bringup/run_benchmark_linux_flow.py --profile pr --dry-run
python3 /Users/zhoubot/linx-isa/tools/bringup/run_benchmark_linux_flow.py --profile pr --report-out /Users/zhoubot/linx-isa/workloads/generated/flow-pr/report.json

• Use this flow before TSVC, SPEC, or full benchmark work.
• Stop at the first red hard-break stage in the same lane; do not debug downstream Linux/rootfs/SPEC failures while ISA/compiler/QEMU/TSVC prerequisites are red.
• If a human explicitly runs downstream work after that hard break, publish it only as required=false with an out-of-order-diagnostic-* classification. It must not upgrade the blocked lane to closure. When execution and publication manifests differ, do not describe the result as same-manifest nightly or release evidence.
• Put new benchmark artifacts under workloads/generated/<run-id>/, not ad-hoc workloads/generated-* sibling directories.

AI workload/QEMU/LinxCoreModel hard-break flow:

python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile smoke --dry-run
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile smoke --run-id <run-id>
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile smoke \
  --run-id <run-id> --case avs-pto-parity-smoke --case avs-tile-smoke \
  --case supernpu-tileop_api
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-MatMacc'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-test_MatMul'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-test_MatMacc'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TSub'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TSubs'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TAdds'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TAdd_mask'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TDiv'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TDivs'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TRem'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TRecip'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TSqrt'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TExp'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TAbs'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TCI'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TExpandCol'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TExpandRow'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TExpandScalar'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TLoad'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TStore'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TCopy'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TCvt'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TReshape'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TTrans'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TPad'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TMul'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TMuls'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TMax'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TMaxs'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TAnd'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TOr'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TCmp'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TRowSum'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TRowMax'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TRowSumExpand'
python3 /Users/zhoubot/linx-isa/tools/bringup/run_ai_workload_flow.py --profile pr \
  --run-id <run-id> --case '=supernpu-tileop_api-TRowMaxExpand'

• Use this flow to promote PTO and SuperNPUBench AI workloads from source contracts through in-repo Linx LLVM, Linx QEMU, and C++ tools/LinxCoreModel.
• Strict lanes require an explicit clean QEMU binary built from the pinned emulator/qemu checkout. Do not search fallback build directories or accept an implicit binary whose source SHA and opcode metadata are unknown.
• Direct-boot AI workload QEMU runs require LINX_VIRT_TEST_FINISHER=1 so SuperNPUBench and AVS pass/fail MMIO writes become host-visible exits instead of long-running guest spins.
• Treat workloads/generated/<run-id>/ai-bringup/report.json as the machine-readable source of truth; summary.md is a generated human view.
• --case <text> is a substring selector. Use quoted exact selectors such as --case '=supernpu-tileop_api-TSub' when a case name is a prefix of another case, for example TSub versus TSubs.
• SuperNPUBench PLAT=linx cases are linked as direct-boot Linx ELFs with _start first at 0x10000; preserve the generated linker script, objdump, raw bin, and compile logs as triage artifacts.
• Discover SuperNPUBench manifests only below workloads/SuperNPUBench/benchmark/two-level-arch/test. With an explicit OBJ_ROOT, the ELF contract is <OBJ_ROOT>/<suite>/elf/<suite-with-slashes-replaced>_<TESTCASE>_linx.elf; the repository-default output root is benchmark/two-level-arch/output. Do not restore or probe the retired top-level test, tests, or benchmarks trees.
• For SuperNPUBench manifest rows with a generic TESTCASE, resolve concrete source files from TYPE first and keep the filesystem's actual case in source manifests. kernel/gemm/matmul TESTCASE=matmul TYPE=HIF4_HIF4 resolves src/HiF4_HiF4.cpp; TYPE=A16W4 resolves src/A16W4.cpp.
• Treat SuperNPUBench compile.all as a machine-readable case manifest for the AI flow. Keep rows as concrete make commands with expanded values; shell loops or literals such as ${num_col} and ${debug} create benchmark-owned source-contract failures because the runner reads make rows literally.
• Current SuperNPUBench Tier-0/Tier-1 direct-boot green cases are MatMul, MatMul_e4m3, MatMacc, test_MatMul, test_MatMacc, TAdd, TAbs, TCI, TLoad, TStore, TCopy, TCvt, TReshape, TExpandCol, TExpandRow, TExpandScalar, TTrans, TPad, TSub, TSubs, TAdd_mask, TAdds, TDiv, TDivs, TExp, TRem, TRecip, TSqrt, TMul, TMuls, TMax, TMaxs, TAnd, TOr, TCmp, TRowSum, TRowMax, TRowSumExpand, TRowMaxExpand, and kernel/control hashtable_lookup_simt. hashtable_lookup_simt currently has two bounded kNum=16 embedded-data direct smokes over the generated 2048-entry table: LINX_HT_SCAN=1 for the linear-scan fallback and a no-scan MurmurHash3 initial-slot plus linear-probe path. The hash/probe row must stay promoted through QEMU and gfsim as the regression for C++ model SRLW/SRLIW low32, 5-bit shift, sign-extended result semantics. Keep only these kNum=16 FOR_GFSIM rows in Tier 1; the kNum=6144 SIMT rows and SIMD NUM_COL=256/512/1024 rows are Tier 2 until their large/debug source contracts are adapted for Linx direct boot. For kernel/control data-object cases, keep output object paths under $(OBJ_ROOT)/kernel/control/... and give generated .o targets explicit no-op recipes after the data-object builder runs; otherwise Make may rebuild generated .s files with a host/default assembler when the AI runner redirects OBJ_ROOT. MatMacc, test_MatMul, test_MatMacc, TAbs, TCI, TExpandCol, TExpandRow, TExpandScalar, TLoad, TStore, TCopy, TCvt, TReshape, TTrans, TPad, TSub, TSubs, TAdd_mask, TAdds, TDiv, TDivs, TExp, TRem, TRecip, TSqrt, TMul, TMuls, TMax, TMaxs, TAnd, TOr, TCmp, TRowSum, TRowMax, TRowSumExpand, and TRowMaxExpand are the first Tier-1 scalar arithmetic/logical/compare/unary/data-movement/reduction promotions: each uses a jcore/<op>.hpp Linx scalar/direct-copy path and a bounded integer direct-boot source branch, then must pass QEMU before gfsim -f <elf>. For MatMacc, keep direct smoke at 4x4 int64 row-major multiply-accumulate with nonzero initial C tile values; col-major MatMacc currently has QEMU-pass/model-fail evidence and belongs in the model lane before promotion. For test_MatMul, keep direct smoke at 4x4 int64 row-major MATMUL; the original TileLeft/TileRight/TileAcc plus TCVT float path remains deferred until the Linx direct-boot model lane supports that runtime contract. For test_MatMacc, keep direct smoke at 4x4 int64 row-major MATMUL+MATMACC; the original TileLeft/TileRight/TileAcc plus TCVT float path remains deferred on the same model-lane runtime contract. For MatMul_e4m3, keep the original FP8 e4m3 conversion, TileLeft/TileRight inputs, TileAcc output, and vector-kernel conversion contract for non-Linx builds, but use a source-local 4x4 int64 MATMUL direct-boot smoke under __linx until boxed, ACC, and FP8 runtime support is available. Keep this smoke in both tileop_api and other/tileop_api; do not collapse it into the existing MatMul source, because the manifests must remain individually promotable. For TReshape, keep the bounded smoke shape aligned to the tile row-major byte contract, as in the current 4x8 -> 8x4 int64 case. For TTrans, keep the smoke square (4x4 int64) unless the test source starts using distinct input/output tile shape parameters. For TPad, keep the Linx include path free of host-only headers such as assert.h; use static shape checks plus a bounded scalar pad loop in the direct-boot smoke instead of runtime assert/libc calls. For TCI, keep the smoke 8x8 int32: unboxed row-major tiles require Cols * bits to be 32-byte aligned, and unboxed col-major tiles require Rows * bits to be 32-byte aligned. For TExpandScalar, keep the smoke 4x8 int64 so row-major Cols * bits and col-major Rows * bits both satisfy the same unboxed tile byte-alignment rule. For TExpandRow and TExpandCol, use the same 4x8 int64 smoke shape and cover both row-major and col-major expansion paths in the direct-boot branch. For TCvt, keep the direct smoke at 16x16 int64, fill tile storage directly instead of using TCOPYIN/TCOPYOUT on boxed tiles, and verify row-major, col-major, NZ, and ZN round-trips before returning success. For TRowSum and TRowMax, use a 4x8 int64 direct-boot branch, keep the output tile ValidCol == 1, and cover both row-major and col-major row reductions before promotion. For TRowSumExpand and TRowMaxExpand, use the same 4x8 int64 direct-boot branch, keep the full output tile shape, and fill every column in each row with that row's reduction value. If Clang lowers a direct-boot tile copy/zeroing operation to memcpy or memset, keep the helper source-local and freestanding under __linx; do not pull in host libc or relax the -nostdlib link. For TCmp, keep the direct smoke at 8x8 so row-major and col-major int32 output tiles both satisfy the unboxed 32-byte alignment rule; cover int64 row/col comparisons plus int32 EQ, and defer float/half direct-boot comparison until soft-float/runtime evidence exists. For TAdd_mask, use a 6x6 int64 global shape over a 4x4 tile to exercise the full tile plus trailing-row, trailing-column, and corner paths without violating the row-major unboxed 32-byte tile alignment rule. For TDiv, keep the direct smoke at 4x4 int64 and cover both row-major and col-major tiles with nonzero denominators; this proves scalar Linx div lowering through QEMU and gfsim without depending on soft-float or compiler-rt helpers. For TDivs, use the same 4x4 int64 row/col smoke with a nonzero scalar denominator so the case proves scalar-divisor lowering without vector-kernel scalar-register writes. For TRem, keep direct smoke at 8x8 int32 and cover both row-major and col-major tiles with nonzero denominators; this proves scalar Linx remw lowering through QEMU and gfsim without soft-float/compiler-rt dependencies. For TRecip, keep direct smoke at 4x4 int64, fill row-major and col-major tile storage directly, and verify reciprocal results before the finisher; model-only failures around the compiler's reciprocal lowering are commonly scalar csel/psel semantics. For TSqrt, keep direct smoke at 4x4 int64 perfect squares and use the bounded comparison-ladder helper in the Linx-only path; unbounded integer sqrt loops can expose current model loop/divergence limitations, and broader integer or floating-point sqrt belongs in a later model-backed promotion. For TExp, keep direct smoke at 4x4 int64 rounded-exp values and use a comparison-ladder helper in the Linx-only path; compiler-generated constant lookup tables for the same bounded values have QEMU-pass/model-timeout evidence, and float/half exponential belongs in a later model-backed promotion. Keep other/tileop_test and non-control kernel/* suites in Tier 2 until their larger shape/source contracts are individually promoted; keep kernel/fusion* rows in Tier 3 because they are model-oriented long-shape workloads.
• SuperNPUBench kernel/gemm/matmul MX cases TYPE=A16W4 and TYPE=HIF4_HIF4 currently pass source discovery/model-build smoke, then stop at compiler-contract with benchmark-owned evidence because their full MX path still depends on vector-only template_asm.h Tr constraints and blkv_get_* launch helpers. Do not classify these as compiler/QEMU/model bugs until the benchmark has a valid Linx direct-boot MX API contract.
• AVS Tier-0 parity smoke is avs-pto-parity-smoke; it passes -DPTO_PARITY_TLOAD_STORE_ONLY=1 through avs/qemu/run_tests.py --extra-cflag and runs only the PTO tload_store digest path. The full smoke-sized parity sequence is split by lane: avs-pto-parity is the Tier-1 QEMU parity maturity row and is intentionally not model-eligible in PR, while avs-pto-parity-full-model is the Tier-4 full-row LinxCoreModel closure target. Non-skipped model builds configure tools/LinxCoreModel/bin/gfsim with -DOPT_LEVEL=O3 -DDISABLE_DEBUG_SYMBOLS=ON so PR/nightly workload probes use the optimized bring-up binary. avs-pto-parity-prefix-gemm-performance is the fast Tier-1 model-green prefix boundary; it uses PTO_PARITY_FAST_F32_SEED=1, PTO_PARITY_FAST_FP16_SEED=1, and PTO_PARITY_STOP_AFTER_STAGE=PTO_PARITY_STAGE_GEMM_PERFORMANCE to stop after the GEMM prefix. avs-pto-parity-prefix-flash-attention is the deeper Tier-1 model-green prefix; it stops after PTO_PARITY_STAGE_FLASH_ATTENTION and proves source, compiler, QEMU, and gfsim through the flash_attention digest and pass finisher. avs-pto-parity-prefix-flash-attention-softmax is the current model-green softmax-prefix micro-profile; it stops after PTO_PARITY_STAGE_FLASH_ATTENTION_SOFTMAX and passes PTO_ATTENTION_SMOKE_SEQ=1, PTO_ATTENTION_LARGE_SMOKE_SEQ=1, PTO_ATTENTION_SMOKE_QD=1, PTO_ATTENTION_SMOKE_VD=1, PTO_ATTENTION_SMALL_SMOKE_QD=1, PTO_FLASH_TILE_M=1, and PTO_FLASH_TILE_K=1 through the AVS extra-cflag hook. Keep these as prefix proofs/probes, not substitutes for Tier-4 avs-pto-parity-full-model closure. avs-pto-parity-prefix-flash-attention-softmax-2x uses the same stop point with PTO_ATTENTION_* set to 2 and PTO_FLASH_TILE_* set to 1, proving a larger scalar soft-float softmax prefix through QEMU and plain gfsim -f <elf>. avs-pto-parity-prefix-flash-attention-masked is the next model-green micro-profile; it stops after PTO_PARITY_STAGE_FLASH_ATTENTION_MASKED and also passes PTO_ATTENTION_MASKED_SMOKE_SEQ=1, PTO_ATTENTION_MASKED_SMOKE_QD=1, and PTO_ATTENTION_MASKED_SMOKE_VD=1 through the AVS extra-cflag hook. avs-pto-parity-prefix-fa-performance reuses the same 1x attention micro-profile, stops after PTO_PARITY_STAGE_FA_PERFORMANCE, and proves the fa_performance digest under QEMU and gfsim. avs-pto-parity-prefix-mla-attention reuses that profile, stops after PTO_PARITY_STAGE_MLA_ATTENTION, and proves the mla_attention digest under QEMU and plain gfsim -f <elf>. avs-pto-parity-prefix-flash-attention-cube adds PTO_PARITY_FLASH_CUBE_SEQ=1, PTO_PARITY_FLASH_CUBE_MAX_SEQ=1, PTO_PARITY_FLASH_CUBE_DIM=1, and PTO_FLASH_CUBE_* 1x tiling flags, then proves the flash_attention_cube digest under QEMU and gfsim. avs-pto-parity-prefix-flash-attention-vec adds PTO_FLASH_VEC_* 1x tiling flags and proves the flash_attention_vec digest under QEMU and plain gfsim -f <elf>. avs-pto-parity-prefix-gqa adds PTO_PARITY_GQA_SEQ=1, PTO_PARITY_GQA_Q_HEADS=1, PTO_PARITY_GQA_KV_HEADS=1, PTO_PARITY_GQA_DIM=1, and matching PTO_GQA_SMOKE_* 1x source controls, then proves the gqa digest under QEMU and plain gfsim -f <elf>. avs-pto-parity-prefix-sparse-attention-local adds PTO_PARITY_SPARSE_SEQ=1, PTO_PARITY_SPARSE_HEADS=1, PTO_PARITY_SPARSE_DIM=1, PTO_PARITY_SPARSE_WINDOW=1, and matching PTO_SPARSE_LOCAL_SMOKE_* 1x source controls, then proves the sparse_attention_local digest under QEMU and plain gfsim -f <elf>. avs-pto-parity-prefix-rmsnorm adds PTO_PARITY_RMS_TOKENS=1, PTO_PARITY_RMS_CHANNELS=1, and matching PTO_RMSNORM_SMOKE_* 1x source controls, then stops after PTO_PARITY_STAGE_RMSNORM and proves the rmsnorm digest plus pass finisher under QEMU and plain gfsim -f <elf>. The promotion closes the prior UART handoff timeout at BROB BPC 0x11dfe; do not keep routing this 1x prefix as a model-owned timeout unless fresh evidence shows a new regression. Current full-row evidence passes QEMU, reaches flash_attention_softmax, then times out in flash_attention_demo_f32 at BROB BPC 0x18348; classify similar QEMU-passing Tier-4 avs-pto-parity-full-model timeouts as model-owned unless static legality evidence proves otherwise. Prior tanh/softmax BFU failures were model local-pipe lifetime and RAS speculative write-slot issues, not benchmark or compiler failures. AVS compiler-pass rows should preserve objdump disassembly, symbol, section, and relocation sidecars for linx-qemu-tests.elf; model timeout/crash rows should add uart_tail/uart_count breadcrumbs plus a last_brob_bpc_disasm window when the log exposes a latest BROB BPC. Use the UART marker to confirm source-stage progress and the BPC-to-objdump linkage before changing benchmark or compiler code for QEMU-passing AVS parity failures.
• PTO catalog smoke promotion currently covers pto-kernel-tload_store, pto-kernel-gemm, pto-kernel-gemm_basic, pto-kernel-gemm_demo, pto-kernel-gemm_performance, pto-kernel-mamulb, pto-kernel-tmatmul_acc, pto-kernel-relu_fp32, and pto-kernel-add_custom in Tier 1, plus Tier-2 layout cases pto-kernel-flatten_fp32, pto-kernel-reshape_fp32, pto-kernel-squeeze_fp32, pto-kernel-unsqueeze_fp32, pto-kernel-concat_fp32, pto-kernel-split_fp32, pto-kernel-stack_fp32, pto-kernel-permute_nhwc_nchw_fp32, and pto-kernel-transpose_large_fp32, and Tier-2 indexing cases pto-kernel-slice_fp32, pto-kernel-gather_fp32, pto-kernel-scatter_fp32, pto-kernel-where_fp32, pto-kernel-argmax_fp32, pto-kernel-unique_i32, pto-kernel-hash_table_insert_fp32, pto-kernel-hash_table_lookup_fp32, and pto-kernel-unsorted_segment_sum_fp32. Use --tier 2 with --profile pr when targeting the Tier-2 cases directly. The AI flow generates explicit per-case harnesses, compiles each matching source with -DPTO_QEMU_SMOKE=1, emits standalone Linx ELFs plus objdump/raw-bin artifacts, then runs each ELF in QEMU and only then gfsim -f <elf>. pto-kernel-add_custom is promoted with a harness-local freestanding __addsf3 helper scoped to the positive integer-valued smoke inputs seeded by the oracle. Its oracle-side f32_bits_from_u32 must keep the exact small-value table for the current smoke range; without that table, gfsim can time out in harness-only bit-scan conversion loops even though QEMU passes. Keep the table local to add_custom; do not move it into shared GEMM copy harnesses without rerunning pto-kernel-gemm_basic and pto-kernel-gemm_demo, because the generated .rodata access pattern is part of the model evidence. pto-kernel-unsorted_segment_sum_fp32 uses the same scoped helper for positive integer-valued smoke additions. Do not generalize either helper into a compiler-rt substitute. pto-kernel-gemm_basic, pto-kernel-gemm_demo, and pto-kernel-gemm_performance are promoted only through their PTO_QEMU_SMOKE float bit-pattern copy-oracle branches; gemm_performance keeps repeat_tiles=3 and verifies the final repeat through a precomputed expected-bit table, avoiding model-side oracle arithmetic as the success criterion. Do not count these as full float TMATMUL/TCVT/TMULS coverage. Keep every other non-promoted pto_kernel catalog entry source/compile/static until it has an ABI-specific harness, oracle, and QEMU-to-model evidence.
• pto-kernel-gemm_reuse_a_fp16, pto-kernel-gemm_reuse_b_fp16, and pto-kernel-gemm_reuse_ab_fp16 have direct-boot FP16 storage harnesses with harness-local positive-integer __mulsf3/__addsf3 shims. They are promoted at the default PTO_QEMU_SMOKE=1 16x16x16 shape and pass source, compiler, QEMU, and gfsim -f <elf> when the AI flow uses --model-timeout 600. Earlier model-fail packets around these cases were closed by the BlockISA store_si3 PR/PO decode fix plus LSU/local-link wakeup fixes; do not regress them by replacing the workload with a smaller shape. The PTO sources expose PTO_QEMU_SMOKE_DIM only as a controlled future probe hook.
• AVS Tier-0 tile smoke uses the compile-smoke source override during QEMU execution to prove the PTO/QEMU/model handoff before the full tile runtime source is green. Keep these case-level smokes separate from model-build smoke.
• Model-build smoke must use the generated tiny ELF under cases/_model/ unless --model-smoke-elf is explicitly provided; do not reuse an arbitrary QEMU-passing workload ELF as the global gfsim availability check.
• --model-build-timeout covers CMake configure/build only; --model-timeout covers gfsim -f <elf> smoke and workload execution.
• Use a targeted smoke selection such as --case avs-pto-parity-smoke --case avs-tile-smoke --case supernpu-tileop_api when you need a fast source-to-model green proof. Keep full-parity model work on the Tier-4 avs-pto-parity-full-model row; the Tier-1 avs-pto-parity row should remain a QEMU parity report row unless the runner policy is deliberately changed with matching docs and skills.
• First failing hard-break stage owns the fix lane: benchmark, compiler, emulator, model, or docs-skills.
• For model-lane scalar/vector select mismatches after QEMU pass, verify the csel/psel contract before changing benchmark or compiler code, and do not treat QEMU as model truth until the contract is reconciled. Current R137 Chisel evidence shows Sail and LinxCoreModel scalar CSEL select SrcL when SrcP != 0, while Linx QEMU selects SrcR.
• In SuperNPUBench compile logs, classify missing *_Impl tile API coverage, unsupported Linx tile runtime contracts (__vbuf__, blkv_get_*, Tr asm constraints, boxed layout static asserts, MATMUL unboxed/ACC static asserts), and host-libc/soft-float direct-boot dependencies as benchmark; reserve compiler for true LLVM/backend/MC/link legality bugs after the workload source contract is valid for Linx direct boot.
• If a SuperNPUBench make command exits successfully but the AI flow cannot find the expected ELF, inspect the compile log before assigning compiler ownership. Stale data-object assembly paths that still target linx64v5, or source manifests that still require missing benchmark-only headers such as benchmark.h, are benchmark/source-contract failures.
• For SuperNPUBench data-object cases, keep generated data/object packaging in the benchmark lane until it uses the current COMPILER_DIR with linx64-linx-none-elf, writes object artifacts under the run's OBJ_ROOT, links EXTRA_OBJ_FILES, and ignores regenerated .data/.bin inputs. Only after that packaging is valid should Tr/blkv_get_* errors be treated as the next unsupported Linx tile runtime contract.
• Failed cases emit bounded agent fix packets under workloads/generated/<run-id>/ai-bringup/fix-packets/.

Dual-lane governance

• Pin lane: superproject submodule SHAs.
• External lane: active external trees.
• For pin-lane bring-up, prefer in-repo toolchain binaries from compiler/llvm/build-linxisa-clang/bin.
• Run same gate matrix on both lanes and publish side-by-side outcomes.

Transcript lessons (2026-02-23)

• Treat ebreak as architectural breakpoint by default; semihost behavior must be explicit opt-in (LINX_SEMIHOST=1).
• Do not run avs/qemu suites in parallel against the same avs/qemu/out directory; shared build outputs can produce false undefined-symbol failures.
• Keep Linux timer diagnostics separate from parser failures: if ctx_tq fails with irq0_delta=0, capture /proc/interrupts and /proc/stat evidence before changing checklist status.
• In recovery-forward-port runs, treat compiler/assembler compatibility failures as module-domain first, and do not use stale Linux/QEMU artifacts as closure evidence before rebuilding them with the refreshed in-repo toolchain.
• Checklist status must be run-id backed, absolute-date stamped, and path-clean (no external tree evidence links).

Gate truth contract

Always record for each gate:

• command,
• lane,
• SHA manifest,
• timestamp,
• pass/fail,
• artifact links.

For promoted Linux runtime gates, the SHA manifest must also bind the SHA-256 of a verified vmlinux.provenance.json. That report must prove a clean, fresh build at the pinned Linux HEAD and bind the exact compiler, linker, host/build tools, config, helper, and vmlinux. A cleanup/deletion marker is not build provenance, and an unbound report cannot upgrade diagnostic runtime output to same-manifest closure.

Treat markdown status pages as generated views, not source-of-truth.

Repin workflow discipline

1. Land module change with module-owned gates green.
2. Update submodule SHA in superproject.
3. Re-run PR strict closure with extended cross gates.
4. Merge repin only with green required gates and complete evidence.
5. If the module PR merged by squash/rebase and rewrote the submodule SHA, follow immediately with a gitlink-only superproject repoint so main references the merged upstream SHA rather than the earlier topic-branch tip.

Included scope

This consolidated skill owns:

• AVS gate orchestration,
• submodule topology cleanup,
• workload matrix publishing (including TSVC).

References

• references/runbook.md
• ../linx-isa/references/v0.3_contracts_and_asm.md (archive-only historical baseline)
• ../linx-compiler/references/v0.3_codegen_and_asm_contracts.md (archive-only historical baseline)
• ../linx-qemu/references/runtime_gates.md (QEMU parity focus)