diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md index d46a1f1..fd1368c 100644 --- a/.specify/templates/tasks-template.md +++ b/.specify/templates/tasks-template.md @@ -152,6 +152,7 @@ Examples of foundational tasks (adjust based on your project): **Purpose**: Improvements that affect multiple user stories - [ ] TXXX [P] Documentation updates in docs/ +- [ ] TXXX Home-page currency (plans → achievements): if this spec moves a thesis or stage from planned to demonstrated, update `docs/assay-home.html` so the plan reads as an achievement (objectives/theses state + progress tracker), under banded honesty — nothing shown as done the repository does not contain. See comms plan §9 and the flagged candidate concept §6.12. Skip only if the spec demonstrates no new user-visible capability. - [ ] TXXX Code cleanup and refactoring - [ ] TXXX Performance optimization across all stories - [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/ diff --git a/docs/assay-comms-plan.md b/docs/assay-comms-plan.md index 7af95fc..241b6a0 100644 --- a/docs/assay-comms-plan.md +++ b/docs/assay-comms-plan.md @@ -1,6 +1,6 @@ # ASSAY — Communications Plan -Status: draft for review · v0.3 · 2026-07-11 (v0.2 adds §6: blog articles with working interactive embeds; v0.3 adds §12: the SME listening loop, and the schema namespace on the Documents page) +Status: draft for review · v0.4 · 2026-07-12 (v0.2 adds §6: blog articles with working interactive embeds; v0.3 adds §12: the SME listening loop, and the schema namespace on the Documents page; v0.4 wires the per-spec home-page-currency step into §9 — flagged candidate, concept §6.12, pending ratification — and the `docs/assay-home.html` Home page it maintains) Authority: ASSAY-DEC-9 (banded honesty — re-derived here as *communications* honesty), ASSAY-DEC-2 (register discipline; the site surfaces the register, never replaces it), ASSAY-DEC-7 (theses as explorations; the site reports thesis *state*, not thesis *products* claimed as shipped). The vehicle is a **public GitHub Pages site** whose single job is to communicate ASSAY's goals and demonstrate its progress — honestly, always-current, and doctrinally literate — to the audiences who will judge it. The site is not a product page; it is the demonstrator's accountable public face, and it inherits ASSAY's signature discipline: **nothing is shown as done that is not, and nothing assessed is shown as fact.** @@ -156,6 +156,7 @@ Illustrative, not binding — the embed is chosen per article by whoever closes ## 9. Cadence & ownership - **On every stage gate** (exit criteria met in the build plan): update `status.yml`, publish the stage's research note to the Roadmap index, add an updates-feed entry. Where the stage introduced a new component or a graphically-expressible algorithm, that entry is a full blog article carrying its working embed (§6) — choosing and shipping the embed is part of authoring the article, not a separate task. This ties site currency to the build's own gates — no separate reporting ritual. +- **On every spec that demonstrates new capability** — the home-page-currency step: a single SPEC can turn a planned capability into a demonstrated one *within* a stage. When it does, revising the public Home page (`docs/assay-home.html`) so the plan reads as an achievement — the objectives/theses state and the progress tracker reflecting what the repository now contains — is part of that spec's definition of "done," under the same banded-honesty guardrail (nothing shown as done the repository does not contain). This extends the stage-gate cadence above to *spec* granularity so the site never lags the build by a whole stage. *(Flagged candidate, concept §6.12 — pending register ratification; wired here provisionally under the same delegated-authority pattern as the DEC-16 floor.)* - **On each research note written:** flip `research_published: true`; the note appears in the index. - **At the spine-complete gate:** swap the Demo page from wireframes to the live demonstrator; add a milestone entry. - **Milestones** continue to fire to `ntfy.sh/iancc2025` (concept §5); the updates feed is the durable written record of the same events. diff --git a/docs/assay-concept.md b/docs/assay-concept.md index bf71779..4a88da8 100644 --- a/docs/assay-concept.md +++ b/docs/assay-concept.md @@ -103,6 +103,7 @@ Target set (peers, batch-propagated): 9. ~~**G6 — propagation honesty**…~~ — **ratified as ASSAY-DEC-25**: G6 is a standing seam invariant alongside G1–G5; oracle cases in vignette §9. 10. ~~Whether `assay-findings.md` joins the canonical set…~~ — **ratified as ASSAY-DEC-26**: it joins the canonical set as the sole home of findings; a finding may be cited for what an exploration concluded, never as the origin of a decision. 11. ~~SME evaluation checkpoints as standing gates…~~ — **ratified as ASSAY-DEC-27**: no thesis concludes without at least one checkpoint having seen it; reactions land in the findings ledger within a day. +12. **Home-page currency (plans → achievements).** The comms plan ties public-site progress to *stage gates* (§9). But a single SPEC can turn a planned capability into a demonstrated one *within* a stage, and the public home page (`docs/assay-home.html`) should re-render that plan as an achievement when it does — not wait for the whole stage to close. **Candidate:** each build specification carries, as part of its definition of "done," a **home-page-currency step** — assess whether the slice moves a thesis or stage from planned to demonstrated and, if so, update the home page's objectives/progress accordingly, under the same banded-honesty guardrail the site already inherits (nothing shown as done that the repository does not contain; a stage cannot show "building" before its research note is published). This makes progress reporting part of building at *spec* granularity, mirroring the ownership rule the comms plan already states at stage granularity (§9). Wired provisionally into the spec-kit tasks template and comms plan §9 pending this batch's ratification — the same "build against the flagged candidate under delegated authority" pattern by which the DEC-16 confidence→band-width floor and the sparse-channel schema entered on landing. On ratification, batch-propagates to the delivery plan §1 ("How we deliver") and the build/comms cadence. *Flagged candidate — not yet ratified.* ## 7. Research starting points (ASSAY-DEC-11) diff --git a/docs/assay-home.html b/docs/assay-home.html new file mode 100644 index 0000000..d56a3ff --- /dev/null +++ b/docs/assay-home.html @@ -0,0 +1,516 @@ + + + + + + +ASSAY — Assessment Semantics & Scenario Analysis + + + + + +
+
+
+ Stage 1 built · Stage 2 in progress + Demonstrator, not a product + Meridian Archipelago — engineered fiction +
+

ASSAY.

+

Assessment Semantics & Scenario Analysis

+

+ Intelligence preparation produces a mass of judged questions and answers. ASSAY's premise: + those answers can become objective, quantifiable, typed objects — and be exploited by + planning machinery honestly, without laundering judgement into false precision. +

+ +
+
+ + +
+
+

What ASSAY is

+

A shared spine, honest by construction

+

+ ASSAY explores optimisation techniques for command-and-control planning, anchored in the + JIPOE/IPOE doctrine family (JP 2-01.3, ATP 2-01.3, AIntP-17). It is a deliberate + re-derivation of a sibling project's principles against a new problem domain: intelligence-fed + course-of-action analysis. Where a principle survives, it is validated as general; where it + does not, that is a finding. +

+ +
+ + + + + + + + + + + + + + + + + + Knowledge + typed · banded + + + + + Compile + stamped world + + + + + Score + banded verdicts + + + + + Analyse + sensitivity · staleness + + + + + Surfaces + four role views + + + every value traces backward to named knowledge, with a named owner + + + +
+
+ demonstrated + in progress + planned +
+
+
+ + +
+
+

See it now

+

The published demonstrator

+

+ ASSAY has no compiled app — its shippable surfaces are static HTML rendered over real + Meridian fixtures. These are live, running on the same code the build uses. +

+ +

+ Fiction, deliberately. Every surface renders the Meridian Archipelago — an + engineered scenario (ASSAY-DEC-8). No service, no plan, and no real operational picture sits + behind these surfaces. +

+
+
+ + +
+
+

The objectives

+

Eight theses over one environment

+

+ ASSAY builds one spine and one small set of role surfaces, then explores a catalogue + of theses across them rather than building each separately. A thesis is only ever + explored — never claimed proven. +

+
+
APipelineJIPOE knowledge can flow into an optimiser honestly — typed encoding + compile path.explored
+
BLeast-worstWhen commitments conflict, minimal relaxation yields a defensible plan-as-argument.planned
+
CRobustnessScoring plans across the adversary COA set beats optimising against most-likely.planned
+
DCollectionOptimisation can tell you where to look — COA-hypothesis discrimination.planned
+
ESensitivity / deceptionThe system can identify which beliefs the decision is leaning on.planned
+
FStalenessA changed answer identifies exactly what it invalidates.planned
+
GInterdependencySystems-perspective (PMESII) knowledge made computable — highest false-precision risk.horizon
+
HReactive redA responding adversary changes which plans survive.horizon
+
+
+
+ + +
+
+

Where it is · plans becoming achievements

+

Progress the repository can back

+

+ The build runs in seven stages — lap first, depth after — behind a spine-complete gate. + This tracker records only what the repository actually contains; a stage cannot show + "building" before its research note is published. +

+
+
+ Stage 0 + Foundations — store, trace graph, type-gen, fixtures + done +
+
+ Stage 1 + Knowledge & discipline — band pill, provenance chip, encoding firewall + done +
+
+ Stage 2 + Compile — knowledge → stamped world channels + in progress +
+
+ ·Stage 3 + Score, then plan — banded verdicts, oracle cases + planned +
+
+ ·Stage 4 + Least-worst — relaxation (thesis B) + planned +
+
+ ·Stage 5 + Scenario robustness — (thesis C) + planned +
+
+ ·Stage 6 + Analysis loops — sensitivity, discrimination, staleness (D, E, F) + planned +
+
+
🚩  Spine-complete gate — not yet reached. Passing it swaps the Demo from wireframes to the live in-browser demonstrator, and opens Stage 7 (surfaces & narratives).
+
+
+ + +
+
+

Reading

+

How the work is explained

+

+ Each stage gate publishes a research note and a dated update; where a milestone warrants it, + that update grows into an article that walks through what the slice actually does — with a + working embed of the new component or algorithm, never a screenshot (comms plan §6). +

+
+ +
Published now
+

Research notes

+

The research-first record: each build stage opens with a bounded research note citing + primary doctrine, ending in "what we will do differently." Note 00 (foundations) and + note 01 (knowledge) are published.

+
+
+
Articles — forthcoming
+

Blog & embeds

+

The dated updates feed and its milestone articles — each carrying a live, playable embed + of the slice it reports — publish as the stage gates land. Linked here the moment the + first article ships; nothing is promised as written before it is.

+
+
+
+
+ + +
+
+

The stance

+

Nothing shown as done that isn't

+

+ ASSAY's discipline is visible in its interface and in this page. The same rule governs both: + no assessed quantity is rendered as fact, and no planned capability is rendered as shipped. +

+
+
+ 2–5 days · low +
Banded honesty

No scalar from an assessed source ever reaches a surface unbanded. Bands are pure closed intervals — no stored midpoint, no distributional claim. Only directly-observed values and commander's thresholds may be scalar.

+
+
+ ASSAY-DEC-n +
Register-first

Every decision is recorded in the register before it is cited anywhere else. Peer documents — and this page — are projections of it, kept current by batch propagation, never rival sources of truth.

+
+
+ why? → +
Every number can be traced

Any verdict, score, or ranking opens a backward walk that terminates in named knowledge objects with named owners. A chain that dead-ends is a bug surfaced, not hidden.

+
+
+
+
+ + +
+
+

Go deeper

+

The canonical set

+

+ ASSAY is docs-first: the reasoning is the asset. Start with the vignette and the walkthrough; + the register holds every decision. +

+ +
+
+ + + + + diff --git a/scripts/build-site.ts b/scripts/build-site.ts index 627ad67..71936c2 100644 --- a/scripts/build-site.ts +++ b/scripts/build-site.ts @@ -4,17 +4,20 @@ * ASSAY has no compiled SPA — the demonstrator's shippable surfaces are static * HTML: the fixture-backed component gallery (SPEC-14, `npm run gallery`) and * the role-surface wireframes (a peer of the canonical set). This script - * gathers those into one directory with a small landing page, so the whole - * thing can be served from a single Pages root (or a per-PR preview subtree). + * gathers those into one directory under the hand-authored Home page + * (`docs/assay-home.html`, comms plan §4 page 1), so the whole thing can be + * served from a single Pages root (or a per-PR preview subtree). * * Run via `npm run build:site` (which regenerates the gallery first). Output is * generated and git-ignored; the CI workflows publish it, nothing is committed. * - * Build metadata (commit, ref, PR number) is read from the environment when - * present so the landing page can label a preview honestly — no value is - * invented when a variable is absent. + * The Home page is the source of truth for the landing content and is copied + * verbatim, save for one substitution: a `` placeholder is + * replaced with a honest preview label when — and only when — the build is a + * PR preview (`PR_NUMBER` present). A production (main) or local build carries + * no badge: a preview must announce itself; the real site needs no label. */ -import { copyFileSync, mkdirSync, writeFileSync } from 'node:fs'; +import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; import { fileURLToPath } from 'node:url'; const root = new URL('../', import.meta.url); @@ -38,52 +41,25 @@ const esc = (s: string): string => // Honest build labelling: only render what the environment actually gives us. const sha = process.env.GITHUB_SHA?.slice(0, 7); -const ref = process.env.GITHUB_REF_NAME; const pr = process.env.PR_NUMBER; const server = process.env.GITHUB_SERVER_URL ?? 'https://github.com'; const repo = process.env.GITHUB_REPOSITORY ?? 'DeepBlueCLtd/assay'; -const badge = pr - ? `preview of PR #${esc(pr)}` - : ref - ? `${esc(ref)}` - : 'local build'; +// A preview badge is injected only for PR-preview builds; the production Home +// page ships badge-free. The commit link is added only if a SHA is available. const commitLink = sha ? ` · ${esc(sha)}` : ''; +const badge = pr + ? `
preview of PR #${esc(pr)}${commitLink}
` + : ''; -const card = ( - href: string, - title: string, - body: string, - tag: string, -): string => - ` -
${tag}
-
${title} →
-
${body}
-
`; - -const html = ` - - - - - -ASSAY — demonstrator preview - - -
-
${badge}${commitLink}
-

ASSAY

-

Assessment Semantics & Scenario Analysis — a docs-first demonstrator. These are the demonstrator's live static surfaces, rendered over the Meridian Archipelago vignette (engineered fiction, ASSAY-DEC-8). No service, no plan, and no real operational picture sits behind them.

-${card('gallery/', 'Component gallery', "The demonstrator's actual components — band pills, provenance chips, the minimal S1 knowledge table and its four discipline moments — rendered over the real fixtures (SPEC-05/SPEC-14).", 'live components')} -${card('wireframes.html', 'UI wireframes', 'The four role surfaces on Meridian data, at the D+2 tableau moment (K9 supersedes K5; K12 contested). Frozen vignette identifiers only.', 'role surfaces')} -

Banded honesty holds throughout: no scalar from an assessed source appears unbanded (constitution II). Identifiers are frozen per assay-vignette.md §8.

-
- - -`; +// The Home page is the source of truth; inject the badge at its placeholder. +const home = readFileSync( + fileURLToPath(new URL('docs/assay-home.html', root)), + 'utf8', +); +const index = home.replace('', badge); -writeFileSync(fileURLToPath(new URL('index.html', site)), html); -console.log(`wrote site/ (${badge})`); +writeFileSync(fileURLToPath(new URL('index.html', site)), index); +console.log(`wrote site/ (${pr ? `preview of PR #${pr}` : 'production home'})`);