# Aep Human Alignment > Renders product-context.yaml into where we stand, what waits on a human, and what drifted. Use for pulse, status check, or a project brief; not planning. - Skill: `memorysaver/aep-human-alignment` (Agent Skill, multi-file: 25 files) - Install (CLI): `npx skillmds@latest add memorysaver/aep-human-alignment` - Raw SKILL.md: https://api.skillmd.com/api/skills/memorysaver/aep-human-alignment/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: memorysaver (https://skillmd.com/u/memorysaver) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/memorysaver/aep-human-alignment --- # Human Alignment Turn `product-context.yaml` into **one self-contained HTML page** that answers the three questions a returning human actually has: _where are we, what needs me, where did reality drift from intent?_ Numbers are derived by code. Prose is written by you. Both are labeled, and an independent audit refuses to ship a page that blurs the line. Rationale and the decisions behind every rule: [`docs/decisions/human-alignment.md`](https://github.com/memorysaver/agentic-engineering-patterns/blob/main/docs/decisions/human-alignment.md). ## The contract in one paragraph Every read is a **first read**. Each surfaced item is a plain-language sentence first — what happened, to what, why the reader cares — with the system identifier demoted to a small provenance anchor beneath it. Facts are unchipped; only non-facts carry a tense chip. **You never author a number.** ## Three emissions, three clocks The facts this surface rests on do not share a clock (decision doc D10). The attention set survives ~110 hours; story-status counts survive ~1. Fusing them into one artifact means re-authoring the slow prose at the fast plane's rate, and every re-authoring is a fresh chance to write something wrong. So there are three outputs, not one: | Emission | Clock | Form | | -------------------------------------------------- | ----------------------------- | ------------------------------------------------- | | **1 · the fact plane** (`derive.mjs` → facts JSON) | every plan-file commit | data, no prose | | **2 · the pulse** (`pulse.mjs`) | whenever you ask | events, computed at read time, never written down | | **3 · the orientation document** (the brief) | per layer, not per invocation | careful prose | Emission 2 is the one to reach for when the question is _what happened since I last looked_. It asserts nothing, so it cannot assert wrongly: ```bash node scripts/pulse.mjs --repo . [--since ] [--json] ``` It prints what you are owed and for how long, the transitions since your cursor, what needs you (dependency-ordered), and open work that has stopped moving. The cursor defaults to the last orientation document's commit. Emission 3 — the rest of this file — is worth its cost only at its own clock, not per invocation. ## Step 0 — choose the emission (do this first) **Default to the pulse.** It answers the question people actually arrive with, costs seconds, and cannot state anything wrongly: ```bash node scripts/pulse.mjs --repo . [--since ] ``` Stop there unless one of these is true: | Ask | Emission | | --------------------------------------------------------------------- | ---------------------------------------------------- | | "what changed / what needs me / where are we" | **2 · pulse** — stop after this | | a script or another skill needs the numbers | **1 · fact plane** — run Derive below, stop after it | | "produce a document someone can be onboarded from", stated explicitly | **3 · the brief** — read the warning first | **Before generating a brief, say this to the person and get a yes:** its prose failed two independent evaluations, the audit passing does not mean its claims are verified, and its output needs their review. A vague request is a pulse, not a brief. The phases below are **emission 3 only**. Emissions 1 and 2 are the two commands above. --- ## Emission 3 · the brief (unproven) Each phase ends in a checkable postcondition, and the next phase starts once the previous one's holds. ### 0 · Preflight `product-context.yaml` must exist (else stop and point to `/aep-envision`). Read `docs/human-alignment/manifest.json` for the delta baseline. → _baseline commit known, or first run declared._ ### 1 · Derive ```bash node scripts/census.mjs --context product-context.yaml # what am I blind to? node scripts/derive.mjs --context product-context.yaml --repo . \ --out docs/human-alignment/facts.json [--code-graph docs/human-alignment/code-graph.json] ``` The facts JSON is the **only legal source of numbers**. It validates against `scripts/facts.schema.json` — via the shared validator in `scripts/json-schema.mjs` — or the run stops. Story and gate states come from `references/aep-vocabulary.schema.json`, the corpus-wide vocabulary: a state this brief has no stage for stops the derive rather than rendering as stage 1. The census classifies every populated path in the plan file against `scripts/source-census.json` as `derived` / `ignored` (**with a reason**) / `unhandled`. An unhandled path is a field this brief cannot see, and an unseen field is where a content defect comes from. Add a rule before proceeding. → _census reports zero unhandled paths; facts JSON exists and validates._ ### 1.5 · Scan (architecture) ```bash node scripts/scan-workspace.mjs --repo . --out docs/human-alignment/code-graph.json node scripts/arch-rules.mjs --code-graph docs/human-alignment/code-graph.json \ --context product-context.yaml --out-dir for tier in overview packages declared; do node scripts/receipt-consumer.mjs --type architecture \ --in /architecture-$tier.architecture.json --out /architecture-$tier.html done node scripts/receipt-consumer.mjs --type workflow --in assets/aep-loop.workflow.json --out /aep-loop.html node scripts/receipt-consumer.mjs --type lifecycle --in assets/story-states.lifecycle.json --out /story-states.html ``` Re-run `derive.mjs` with `--code-graph` afterwards so the declared-vs-actual drift fact is included. No workspace manifest, or no archify CLI (exit 3)? The architecture view **degrades and says so on the page** — it never blocks. → _artifacts delivered `code-verified`, or the view is marked degraded._ ### 2 · Author Copy `assets/template.html` and fill its `{{SLOTS}}`. **Read the template's contract comment before writing a single section** — it is the only source of CSS class names and of the `data-fact` binding convention. The authoring rules are in [`references/guideline.md`](references/guideline.md). The five that fail an audit fastest: 1. **Answer first** — every section opens with one plain sentence that _is_ the section's conclusion. 2. **Translate** — re-author every story title and changelog entry as a consequence sentence bound to its id in the anchor. 3. **No naked numbers, in digits or in words.** Every number is `data-fact`. `five`, `eight`, `three quarters` are numbers too — a word spelling a count is still a claim about a count. 4. **Every assertive block cites what it rests on** — `data-claims=""`, or `data-authored` if it is narrative that can cite nothing. A claim the facts do not carry is not a sentence to write more carefully; it is a fact to derive first. 5. **Fold the queue** — backlog collapses to one sentence per layer, full list behind a disclosure. 6. **Never chip a fact** — an unchipped page is a page of facts; diluting that destroys the only trust gauge the reader has. → _every section rendered or stamped; no `{{SLOT}}` left._ ### 3 · Audit ```bash node scripts/audit.mjs --html --facts docs/human-alignment/facts.json \ --template assets/template.html ``` After Phase 4, audit the **delivered** file too — Phase 3 runs before assembly injects the diagrams, and nothing else re-checks afterwards: ```bash node scripts/audit.mjs --html --facts \ --template assets/template.html --delivered ``` `--delivered` excludes embedded artifact payloads from the claim rules (they are archify's prose, validated separately) while still checking that the diagrams and the facts describe the same commit. Failures are structured receipts (`code` · `subject` · `evidence` · `supportedFixes`). Apply a **listed** fix and re-run, at most **twice** — a receipt with no listed fix, and a third failure, are both reported rather than retried. Then walk the judgment checks in [`references/checklist.md`](references/checklist.md). → _audit passes; judgment checks walked._ ### 4 · Deliver ```bash node scripts/assemble.mjs --authored --facts docs/human-alignment/facts.json \ --artifacts --out-dir docs/human-alignment --keep 3 ``` Run it **in the output directory** — the script owns every move a brief makes. Removing one outside it discards the delta baseline, and the next run then reports itself as the first. `assemble.mjs` refuses to run when the ledger names a brief that is no longer present, and when the facts and the code graph disagree about which commit they describe. Writes `brief-T