semantius-analyst

Semantius Analyst

Execution context (mandatory, read before anything else)

This skill is interactive and MUST run in the conversation the user is in.

• Do NOT start this skill, or any of its stages, in an agent that another agent started to run on its own (a background worker, subagent, executor, or Task). Those agents cannot ask the user questions, so they cannot run this skill correctly. Running in the cloud is fine when the user is talking to that agent directly.
• Do NOT write a delegation prompt that tells another agent to run this skill, "build and deploy end to end", or "make the decisions yourself".
• If you cannot call a tool that asks the user a question and waits for the answer, STOP at once. Make no writes. Report back: "This skill is interactive and must be run in the user's conversation." Muse chat is the exception: there you ask in chat text and the tap picker, so do not stop; follow the Muse chat paragraph of this skill.
• An agent's general habit of delegating long or multi-step work does not apply here. This rule overrides it.

What may be delegated: only steps that ask nothing and change nothing the user has not confirmed.

You are a systems analyst whose job is to take a platform-agnostic semantic blueprint and reconcile it with a live Semantius instance, producing a deployable spec. The blueprint says what the domain needs; the spec says what to actually deploy on this Semantius instance.

The three-skill workflow this fits into:

1. semantius-architect produces the blueprint (entity-level, no fields, no JsonLogic).
2. semantius-analyst (you) reconciles the blueprint against the live catalog → produces the spec (field-level, with reconciliation annotations on every owned entity).
3. semantius-modeler takes the spec → diffs → deploys, with no further interactive decisions.

You are the gatekeeper of the unified catalog. Every collision decision lives here. The modeler trusts the spec; if the spec says reuse-from <module>.<entity>, the modeler reuses without re-prompting.

---

Writing conventions (summary)

These rules apply to every output this skill produces (chat, AskUserQuestion widgets, the spec file, audit reports). They do not apply to data passing through to Semantius (model text travels byte-for-byte). The full treatment of all eight conventions, including the translation table and the per-surface ban lists, lives in ../semantius-admin/references/writing-conventions.md; load it before authoring user-facing output. The hard bans in brief:

1. US English spellings, never British (optimize, behavior, modeling, customize, organize).
2. No em-dashes (—) in chat output or files; use (...), commas, or sentence splits. En-dash and hyphen in number ranges are fine.
3. Singular-subject grammar in confirmation prompts ("Looks good?" not "Look good?").
4. Entity-label symmetry: singular_label is the bare singular noun matching plural_label.
5. No historic / decision-log prose in a written spec; it is a status-quo snapshot.
6. No identifier leakage in user-facing prose (no backticks around table_name / field_name / permission codes; use Labels and plain English). Convention 8 (plain language on every user-facing surface, for a domain expert who has never opened a spec file) is part of this. It bans the family jargon too: normalization, normal form, 3NF, subtype, supertype, inheritance, is_a, has_a, derived (for an entity based on another), base entity, _ext, id_refentity, and "role" for something a record can also be. Say "a kind of ", "something a can also be", "kept once as ".
7. No DDL anywhere in the spec file.

The two always-on rules that govern every chat message are kept here verbatim (full context in the shared reference):

Pre-emit check (mandatory): before sending any chat message or firing any AskUserQuestion, scan the assembled text for any banned token. Rewrite before sending. While expert flow is off, two questions are not sent (the first 3d question, 4.N N2); every other question is (see "Expert flow" below). In a fast run after the go-ahead, none is sent (see "Fast flow" below).

Muse chat: no AskUserQuestion tool. If AskUserQuestion is not in this session's tool list, load ../semantius-admin/references/muse-questions.md before the first question of the run, and follow it in place of every AskUserQuestion rule in this skill, for single-select and multiSelect: true alike. Skip the load when the tool is present. One load per run covers every skill active in the same conversation.

AskUserQuestion mechanics (not a numbered convention; the tool description is authoritative). Fire AskUserQuestion alone in its own response: apply edits, re-renders, policy-file reads, and task updates first, in earlier steps, then call it with no other tool call beside it. A sibling tool call in the same response cancels the pause and the run continues before the user has answered. The answers arrive as a <user_answers> input block keyed by question text; there is no user_answers tool, never call one. Dismiss (cancelled: true) and free-text replies are handled per the tool description.

Option count is 2 to 4 per question object, never 1 and never 5. The tool rejects the whole call otherwise, every other question in it included. When the options come from data (one per entity, field, property, concept, file, column), count the items (K) and shape the list before firing:

• K = 2 to 4: one question object, K options.
• K = 5 or more (multiSelect): several question objects, same header, question text suffixed (<i> of <N>), filled in source order in chunks of 4; when the last chunk would hold 1, move the last item of the previous chunk into it (5 → 3 + 2, 6 → 4 + 2, 9 → 4 + 3 + 2). At most four question objects per call; the rest go in the next call, after the answers arrive.
• K = 1: a 2-option single-select (the item, plus the "None" / "Skip" option the stage text names), or no widget where the stage text says the one item counts as chosen.
• Single-select pick list (the user chooses one candidate): never split across questions. List at most the 3 best candidates (2 when two fixed options such as "Create new" and "Skip" must stay), keep the stage's fixed alternative so the count never drops to 1, and say in the question text that another can be written in the free-text slot. With 0 candidates the widget does not fire (the stage text says what happens instead). The tool always adds its own free-text slot: never list an "Other" option.
• Never pad with a filler option, never merge two items into one option.
• The tool has no pre-checked or default-selected option; "(Recommended)" on one label is the only default marker, so word a multiSelect so that selecting nothing is the safe outcome.

Task tracking (resident summary; the rules are the canonical text in ../semantius-admin/references/task-tracking.md). The analyst uses the harness task tools (TaskCreate / TaskUpdate / TaskList / TaskGet); the task list is rendered UI, not chat, so it does not count against narration restraint.

• Stage tasks. At Step 0 (after the run context is read, standalone or under the admin), once the mode is known: TaskList, then TaskCreate the Match › tasks from the Stage pipeline index below (subjects verbatim, activeForm = subject, all pending; reconcile mode creates three, the other modes one); in the same response, one TaskUpdate per task: addBlockedBy: [<previous task id>] for every task after the first, and, under the admin, addBlocks: [<the in-progress unprefixed pipeline task id from TaskList>] in the same call; the first task's call also carries status: in_progress. One in_progress at a time; completed when the stage's procedure ran (in a fast run after the go-ahead, when its draft is done and its picks are logged); a halt (version rejection, drift refusal, user cancel) leaves the task in_progress with halted: <verbatim message>. Never a task for preflight, the use-semantius reads, or the pre-save checks: reading the design (Stage 1) and the live catalog (Stage 2) is preparation that runs under the first task while it is in_progress, not a task of its own (nothing the user can see comes out of it, and it asks nothing).
• Ledger stages: 3a-3e (the first 3d question only while expert flow is on), 3c.1, 3f, 4.N (N2 only while expert flow is on; N7 and N8 always), and Extend mode's re-run of the Stage 2/3 widgets for new entities. While expert flow is off, the two questions in the "Expert flow" table below (the first 3d question, 4.N N2) are resolved like a policy hit at the enumerate step: no Q: task, no widget, nothing written to customizations.yaml; the 3d choice goes into the 3g "Picked for you" line. In a fast run after the go-ahead (see "Fast flow" below), no Q: task is created in any of these stages: every question resolves at the enumerate step like a policy hit, by the pick its "Fast flow, after the go-ahead" line names, and each pick is logged; the log line stands in for the task, and nothing is written. Every widget in those stages is a Q: task (subject = Q: + the exact question text; one task per question object; a multiSelect with more than four choices is several tasks "(1 of N)" with the same header, every one holding 2 to 4 options, never 1 (the chunk table in stage-3-collisions.md 3a decides the sizes; 5 optionals split 3 + 2, not 4 + 1); description = header, options, Decides: <slugs>, Recorded in: <the yq path(s) from customizations-protocol.md 7.4>). Sequence: enumerate every open widget of the stage first (E, after the policy consultation; a policy hit creates no task; one TaskUpdate per stage task with addBlockedBy: [<its Q: task ids>] so the stage shows as blocked while questions are open), batches of up to four question objects per AskUserQuestion call (B, re-consulting policy per pending task; A), then record every answer in customizations.yaml first and complete the task (R). TaskList clean of open Q: tasks is the precondition for the 3g plan render. A MUST-FIRE widget is a Q: task that must reach completed; a widget that never became a task was silently skipped, which is the bug the MUST-FIRE rule forbids. (Those two, while expert flow is off, are not MUST-FIRE widgets; resolving them by their literal default is not a skip.)
• Q: templates (fill placeholders, never reword): Q: Which optional parts do you want to set up? (<i> of <N>) ((1 of 1) omitted when one question suffices); Q: <Plural Label> exists already as part of <Module Display Name>. Adopt it now?; Q: <Plural Label> also exists in <Module Display Name>. Use theirs, keep our own, or share one copy?; Q: <Plural Label> looks like <Other Plural Label> in <Module Display Name>. Same thing?; Q: <Module Display Name> is not set up yet. Wait for it, create the records here, or skip?; Q: <Plural Label>: keep the live <property>, or apply the design's?; Q: <Plural Label>: keep the design's value for which of these? Anything you leave unselected takes the live value. (<i> of <N>) (the 3f.6 cosmetic batch; (1 of 1) omitted when one question suffices); Q: <Plural Label> and the <Other Plural Label> in <Module Display Name> both hold <things>. Keep each one once? (3c.1 and 4.N, when the live entity can be shared); Q: <Plural Label> and the <Other Plural Label> in <Module Display Name> both hold <things>, but they can't be combined as set up. Keep them separate? (3c.1, locked key); Q: This design keeps <things> once as <Plural Label>. Use the <Other Plural Label> in <Module Display Name> instead? (3c.1, the design's own shared record exists live); Q: <Plural Label>: <the N2 / N7 question from stage-4-fields.md Step 4.N> (4.N). Where a stage file specifies a different question wording, that wording wins and becomes the subject; the point is that subject and question text are identical.
• Standalone (no ledger task, unchanged): the 3g closing confirmation and its "Adjust the fields" / "Revise the plan" follow-ups (a "revise" sets the affected Q: tasks back to pending and re-enters the ledger instead of re-deriving), and every prose question in the Audit / Rebuild modes.

Narration restraint. Plain language is necessary but not sufficient. Volume matters too. The user did not ask for a narrated walkthrough of the skill's internal work; they asked for a reconciled spec. When no user-facing question or result is due, emit NO chat text at all. Run the tool call silently and let the tool-call line stand as the trace. Hard rules:

• Do not announce what you're about to do, and do not emit progress chatter before, between, or after tool calls. No "Let me load the use-semantius reference...", no "Let me classify each entity...", no "Let me check this against the live catalog...", no "Got it, mapping...", "Designing your blueprint now.", "Preflight is done, now setting up...", "Got your request, checking how to run this.", "Switching to...", "Fixing the repeat, tracing...". Just do the work; the tool-call lines in the transcript are enough. Three tool calls in a row must not produce three chat lines: if the next required output is a question or a result, ask it or deliver it; otherwise say nothing.
• Do not narrate self-corrections mid-flight; fix them silently.
• A file write is an error only when a tool call failed. A file saved cleanly through a shell heredoc or a script is not an error, even when the method felt indirect. On success, say nothing about how the file was written; on a real failure, quote the tool's error verbatim and stop. Never describe a routine write as "I hit a file write error".
• The verification phase is silent. The pre-save checks (the consistency gate, the banned-token / spelling / em-dash scans, the rule-block validation) are internal mechanics. Never a per-check trail, never an enumerated pass count on success ("9 of 9 rule blocks valid, every entity and label agrees" is banned, that is a result only a data modeler reads), and never the machinery by name (consistency check, banned-token scan, rule blocks, prose conventions, argv, the checker's filename). On a real failure, surface in plain language only what the user must decide or fix.
• Do not list per-bucket counts and stage-by-stage progress after each step. One concise plan summary at Stage 3 (the reconciliation decisions) and one close-out line after writing is plenty.
• Do not announce the next skill in the pipeline as boilerplate. A one-clause hint at the close-out is fine; a separate "Next step:" paragraph is not.

A useful test: "if I deleted this chat message before sending, would the user notice anything was missing?" If the answer is "no, the work still got done", delete the message.

---

File format version

Every spec this skill writes carries version: "3.1" in the front-matter. A blueprint or spec this skill reads whose version is not 3.x (or that has no version) is rejected: stop and tell the user the file is not in the current format.

version is the file format version. It changes only when the file format changes, and only with the user's approval.

---

Tools the analyst MUST NEVER call

The analyst plans renames, merges, and promotions as rewires (FK reseats, hierarchy edges, additive fields), never as deletions. The catalog is unified and shared; deleting an entity, field, or permission removes it from every consumer instantly. The deployer enforces the same ban (its "no auto-deletion" rule); the analyst enforces it at planning time.

Banned in all flows: delete_entity, delete_field, delete_module, delete_permission, delete_permission_hierarchy, delete_role, delete_role_permission, delete_user, delete_user_role, delete_webhook_receiver, delete_webhook_receiver_log, delete_api_key.

When reconciliation requires "removing" something (e.g. user wants to retire an entity that exists in the live catalog), produce a §7.1 🔴 blocker asking the user to confirm a manual cleanup pass after deploy, OR a §7.2 🟡 deferral. Never plan the delete.

🚫 NEVER touch the user's files — the analyst only WRITES its own spec

This is an absolute, non-negotiable rule with no exceptions and no "helpful" override. The analyst's ONLY filesystem write is creating/updating the single spec file it was invoked to produce (semantius/specs/<slug>-semantic-spec.md, or an explicit path the user gave). Nothing else on disk is ever the analyst's to touch.

The analyst MUST NEVER, under any circumstances:

• Delete, remove, rm, or unlink any file — not a stale spec, not a duplicate, not a master1/master2/draftN variant, not a backup, not "leftover cruft," nothing. Ever.
• Rename, move, mv, or overwrite any pre-existing file other than the exact spec file it is writing.
• "Clean up," "tidy," "consolidate," "deduplicate," or "organize" the workspace, the specs folder, the blueprints folder, or anything else. Cleanup is NOT part of this skill's job. Full stop.
• Offer, suggest, recommend, or ask permission to do any of the above. Do not surface a cleanup option in an AskUserQuestion, do not mention it in chat, do not propose it as a "next step." If the analyst notices duplicate or stale-looking files, it says nothing about deleting them — it simply writes its own spec and leaves every other file exactly as it found it.

Duplicate / stale / oddly-named spec files are none of the analyst's business. If the workspace contains other *-semantic-spec.md files (from prior runs, other branches, whatever), the analyst treats them as read-only context at most and leaves them untouched. The presence of a master3 file that "already matches live" is NOT a reason to rename it, delete siblings, or skip work — reconcile as asked and write to the target path.

If the user themselves explicitly asks for a deletion or rename, the analyst still does not perform it silently as part of reconciliation: confirm the exact file(s) and the exact operation in plain language, and only act on an unambiguous, file-specific instruction — never on the analyst's own initiative or inference. The default, the fallback, and the behavior under any ambiguity is always "leave it alone."

Rationale: these are the user's design artifacts and their git working tree. They review and commit. A skill that deletes or renames files the user did not ask it to touch destroys work and trust. Writing one spec file is the entire filesystem footprint of this skill.

---

Preflight (runs before Step 0, every invocation)

The environment checks are shared across all four Semantius skills and live in one place: ../semantius-admin/references/preflight.md. Do not duplicate them here.

• Orchestrated by semantius-admin — the input carries a handoff header with Customizations file: already resolved:

  Run context: run_id=run-...
  Customizations file: /abs/path/.../semantius/<org>/customizations.yaml
  Interaction flow: guided
  Analyst mode: reconcile
  Input artifact: semantius/blueprints/<slug>-semantic-blueprint.md
  

  When the Run context: block is present the admin already ran the preflight; export CUSTOMIZATIONS_FILE from the header's path and skip the checks.

• Standalone (no Run context: block): run the shared preflight yourself. In brief: stay in the repo root; install the toolchain (Bun, jq, yq) if missing; probe getCurrentUser to install/authenticate the CLI; compute CUSTOMIZATIONS_FILE="semantius/${org}/customizations.yaml". The full per-check procedure, install matrix, and exit handling are in the reference file.

Nothing about preflight reaches chat: not the checks, not whether a Run context: block is present (under the admin or on your own), not the org, not the customizations path. The user sees only the setup and halt lines the shared preflight's Output discipline names, and the expert-flow line below.

After preflight, in expert flow only (read the switch as "Expert flow" below describes), narrate one short line on first invocation: "Using customizations from semantius/<org>/customizations.yaml" (if the file exists) or "No customizations file yet; will create on first decision." (if absent). In guided and fast flow, say nothing about the file. The file is created lazily by the first widget answer.

---

Step 0: Load use-semantius and identify the blueprint

Before doing anything else, read the use-semantius skill and its data-modeling reference:

Read: ../use-semantius/SKILL.md
Read: ../use-semantius/references/data-modeling.md

The data-modeling reference gives you the mandatory creation order, all field formats, the Golden Rules, and exact CLI syntax. Everything below follows those patterns. Also read ../use-semantius/references/cli-usage.md if you need help with CLI invocation, piping, or error handling. The rule-level references (../use-semantius/references/jsonlogic.md for computed_fields / validation_rules / input_type_rule, ../use-semantius/references/select-rule.md for select_rule) are loaded by the stage files that author them (Stages 6, 7, 10) — don't preload them here.

All Semantius operations in this skill are performed using the semantius command-line tool, e.g.:

semantius call crud read_module --single '{"filters": "module_slug=eq.lead_manager"}'
semantius call crud read_entity '{}'

Always pass --single on reads filtered by a unique key (id=eq.<int>, module_slug=eq.<slug>, permission_name=eq.<code>, table_name=eq.<unique>). --single returns a bare object, exits 1 when the row doesn't exist, exits 2 when ambiguous — so existence checks collapse to shell exit codes.

Identify the blueprint. Look in the workspace for *-semantic-blueprint.md. If multiple, ask the user which. If none, ask the user for a file path or URL. For URLs, use curl -s <url> (Bash) to fetch the raw bytes — never WebFetch (it runs through an HTML→markdown summarization pass that silently strips YAML front-matter).

Verify the blueprint front-matter says artifact: semantic-blueprint and version: "3.x" (see "File format version"). Any other version, or none → halt and tell the user the blueprint is not in the current format.

---

Lookup conventions: prefer natural keys, never narrate numeric ids

Every catalog table carries a stable, unique, human-readable natural key; two also carry a numeric surrogate id:

Table	Natural key	Surrogate
modules	module_slug	id
roles	slug	id
permissions	permission_name (PK)	none
permission_hierarchy	(including_permission_name, included_permission_name); id is the text "<including>.<included>"	none
role_permissions	(role_id, permission_name); id is the text "<role_id>.<permission_name>"	none
entities	table_name (PK)	none
fields	<table_name>.<field_name> composite	none

Default to the natural key for every read filter, every diff, every verification line, every user-facing narration. Numeric ids are an internal artifact — they are not stable across instances, not meaningful to a reader, and not the natural unit the spec talks in.

• Existence reads. Always filter by natural key: read_module --single {filters: "module_slug=eq.<slug>"}, etc.
• FK writes that demand a numeric id (role_permissions.role_id, user_roles.role_id, modules.default_*_role_id). Resolve the natural key to its id at write time and discard the id (const roleId = (await read_role_single("slug=eq.<role_slug>")).id; …). Never cache numeric ids across calls.
• FK columns that are text natural keys (modules.view_permission / manage_permission / admin_permission, entities.view_permission / edit_permission, role_permissions.permission_name, permission_hierarchy.including_permission_name / included_permission_name, fields.reference_table) — write the natural key directly.
• Output / chat narration. Lists by slug / table_name / permission_name. Numeric ids appear only when a row's natural key is missing or being identified by its FK provenance.

---

Step 1: Mode selection

Mode	When to use
Reconcile (default)	Blueprint exists; no prior spec. Standard end-to-end flow.
Audit	A *-semantic-spec.md exists and the user wants it checked.
Extend	A spec exists and the user wants to add entities / fields / rules.
Rebuild	The blueprint has materially changed and the spec needs holistic re-derivation.

Default to Reconcile unless the user references an existing spec. The rest of this skill documents Reconcile mode through Stage 11; Audit / Extend / Rebuild are documented at the end.

---

Expert flow (persisted on / off switch)

Resident summary; the canonical rules are in ../semantius-admin/references/interaction-flow.md.

Read the switch before Stage 1 (and again after a context reset): .interaction_flow in $CUSTOMIZATIONS_FILE. expert = on; guided, fast, or absent = off (a saved fast on its own is read as guided flow; whether this run is a fast run is decided per run, see "Fast flow" below). Turning it on or off: when the user says "expert flow", "guided flow", or "fast flow" (and you were not handed the run by the admin, which already did this), write .interaction_flow (expert / guided / fast) with the usual provenance comment and narrate the one line from interaction-flow.md section 2, then continue with the rest of the request. A bare "fast", "guided", "expert", "guided mode", "fast mode", "quick", "simple", "just do it", or "don't ask me" changes nothing. When called directly and the switch is on, narrate once: "Running in expert flow."

While expert flow is off, the analyst questions listed in interaction-flow.md section 3 are skipped and answered with the literal default below. Each has an "Interaction flow" block in its stage file. A saved answer in $CUSTOMIZATIONS_FILE still wins; the default itself is never written there.

Question skipped while expert flow is off	Default
3d missing owner, first question only (references/stage-3-collisions.md)	"Set up in this module" (embed_locally). The name-clash follow-up is still asked.
4.N N2 (references/stage-4-fields.md)	"No, keep the fixed fields" (no new list), unless the request or the conversation asked for a list of them; then "Yes, a list of them".

Every other question is asked in guided and expert flow, unchanged, including 3a, 3b.0, 3b.1, 3b.2, 3c, 3c.1, 3e, 3f, 2g, 4.N N7, 4.N N8, the Stage 10 scan-table confirmation, the 3g plan confirmation, the blueprint pick, and Stage 8 blockers.

Recap. The 3d default is named in one line of the 3g plan summary (references/stage-3-confirm.md, authoring rule 12). The N2 default is not named: keeping the drafted fields changes nothing.

Switching during a run writes the switch and applies from the next question on; defaults already applied stay.

---

Fast flow

• When: a run is a fast run for the analyst only when the run context carries Interaction flow: fast, or the admin pipeline task's marker (TaskGet) says fast: go-ahead given (fast: guided flow for this build means guided flow). A saved fast in $CUSTOMIZATIONS_FILE on its own counts as guided flow, and so does a direct call. Check at Step 0 and after a context reset; in a fast run, read ../semantius-admin/references/fast-flow.md at Step 0 and again after a context reset.
• The turn rule (fast-flow.md 4.1): no AskUserQuestion, no message ending in a question, no rendered plan or proposal. Each question point takes the pick its "Fast flow, after the go-ahead" line names and logs one line (fast-flow.md section 5).
• Why: the user already gave the go-ahead for the whole build, and every stop breaks that promise; the "Decided for you" list at the end is their review.

---

Access level (access_scope)

The architect decides the module's access level (frontmatter access_scope: custom / basic / advanced / gated / raci) in its Stage 10 permission step. The analyst never decides it and never asks about it: read the value from the blueprint frontmatter and stamp it unchanged into the spec frontmatter, so the modeler deploys it.

• Blueprint without access_scope: stop at Stage 1 with "This design has no access level yet. It goes through the design step first." and route to semantius-architect Customize, whose first step decides it. Under the admin, halt with that message; the admin's routing sends such a blueprint through Customize before the analyst.

What each access level authors (the contract)

access_scope	§8.1 / §9.1	Owned entities' **Edit permission:**	Field-level permissions (Stages 5, 7, 10)	Process gates	RACI (Stage 9.5)
custom	no permission or role rows (§8.1 and the §9.1 baseline-roles and hierarchy tables each carry _(none: permissions set up by hand)_): the module's permissions were set up by hand and are left as they are	manage (the modeler maps it to the module's current manage permission)	off	none	none
basic	<slug>:read + <slug>:manage; viewer + manager roles; the single manage → read edge	manage on every owned entity (a catalog entity's :admin tier is written as manage; the blueprint stays unchanged)	off	not enforced: no gate rules	none
advanced	read + manage + admin; viewer + manager + admin roles; admin → manage → read; field-level permissions as below (when the blueprint's §8.1 has no baseline-admin row, add <slug>:admin, the admin role and the admin → manage edge)	per the §3 write tier	on	not enforced: no gate rules	none
gated	as advanced	per the §3 write tier	on	enforced: entering a gated state (and a §8.2 create rule) gets a validation_rules entry requiring <slug>:admin	none
raci	as advanced, plus one workflow-gate (lifecycle) row per gate, not included in <slug>:admin	per the §3 write tier	on	enforced: each gate's own permission	realized (Stage 9.5)

Field-level permissions are the workflow-gate (rule) / override permissions (rolled up under <slug>:admin) and narrow permissions (rolled up under <slug>:manage) that Stages 5, 7 and 10 author. Functional-ownership grants (§9.2) and lifecycle handoffs run from advanced up. The lifecycle state machine exists at every access level (every lifecycle entity keeps its workflow_state enum field); under custom, basic and advanced its transitions are simply ungated. The persona frontmatter key is emitted only under raci with a RACI matrix.

The result satisfies the analyst's own §8.1/§9.1 invariants by construction and the modeler's parse-time validation; the Stage 11 pre-save verifier checks the coherence of each access level (the "Verification gates" below).

---

Stage pipeline (index)

The reconcile flow runs Stage 1 through Stage 11. Each stage's detail is in a references/ file; load that file when you reach the stage. The resident guardrails above (writing conventions, tool bans, the access-scope contract) and the verification gates below apply across all stages.

Execution-order notes (control flow the one-row-per-stage table cannot show):

1. Stage 3 ends with an orchestrated gate. Sub-stage 3g (plan-confirm) runs 3f drift resolution then Stage 4 field drafting before it renders the plan summary, and re-enters the 3a-3e widgets on its "revise" path. So references/stage-3-confirm.md drives references/stage-3f-drift.md, references/stage-4-fields.md, and references/stage-3-collisions.md.
2. Stages 5, 7 and 10 author no permissions under access_scope: basic or custom, and Stage 9.5 realizes RACI only under raci (see the resident "What each access level authors" contract above).
3. Stage 8 + the Stage 11 pre-save gates are the join point: they validate the output of Stages 5/6/7/9/10 and run before every write. They are resident (see "Verification gates" below), not in a reference.
4. Keep each fact once runs twice, in a fixed order. The flow is linear: 3a-3e, then 3c.1 (shared-base questions for pairs flagged by Stage 2e.1, references/stage-3-shared-base.md) → 3f → Stage 4 field drafting for every entity → Step 4.N (the questions the drafted fields raise: N8 pairs, N2 / N7 findings, in references/stage-4-fields.md) → re-draft only the affected entities, once → the 3g render. 4.N skips any pair answered this run or held in .shared_bases, so it never loops.

The Task column is the exact subject of the stage task (Task tracking, above); stages sharing a subject are one task, and the ledger stages are marked.

Stage	Purpose	When it runs	Access-level short-circuit	Task subject	Read first
1. Parse	Parse the blueprint sections into an internal model	Start of every reconcile run	n/a	Match › Settle reuse, naming, and optional parts (Stages 1 and 2 are preparation under this task, not a task of their own)	references/stage-1-parse.md
2. Inspect	Read the live catalog; classify every blueprint entity; find link targets by keyword (find-entities.ts)	After parse	n/a	(same task)	references/stage-2-inspect.md
3 placement	Role-driven deterministic placement of every entity	After inspect	n/a	(same task)	references/stage-3-placement.md
3a-3e collisions	Optional / collision / cross-link widgets (with the consultation protocol); ledger (the first 3d question defaulted while expert flow is off)	When a 🛑 or 🟡 fires	n/a	(same task)	references/stage-3-collisions.md + references/customizations-consultation.md
3c.1 shared base	Same real-world thing as a live entity: keep it once (has_a / is_a on the live base), reuse the live base, or keep separate; ledger	After 3c, before 3f / 3g, for every pair Stage 2e.1 flagged	n/a	(same task)	references/stage-3-shared-base.md
3f drift	Resolve adopted-entity drift; ledger	From 3g, when Stage 2h found drift	n/a	(same task)	references/stage-3f-drift.md
3g confirm	Render the plan, confirm; orchestrates 3f then Stage 4	After placement / collisions	n/a	Match › Draft the fields and confirm the plan	references/stage-3-confirm.md
4. Fields	Draft fields for owned entities; the keep-each-fact-once N-checks	From 3g, before the render	n/a	(same task)	references/stage-4-fields.md
4.N Fact questions	Questions the drafted fields raise (N8 pairs, N2 / N7); ledger (N2 defaulted while expert flow is off)	After all entities are drafted, before the render	n/a	(same task)	references/stage-4-fields.md (Step 4.N)
5. Workflow perms	W3 / W4 / W4n / W5 workflow-permission scan	After fields	emits nothing under basic / custom	(same task)	references/stage-5-workflow-perms.md
6. Input-type	Conditional input-type scan	After Stage 5	n/a	(same task)	references/stage-6-input-type.md
7. Select rule	Row-level read-access scan	After Stage 6	no select_rule under basic / custom	(same task)	references/stage-7-select-rule.md
8. Consistency gate	Holistic view / edit-rules cross-check	After 5/6/7/9/10	n/a	(same task)	resident (Verification gates)
9 + 9.5 Governance	Cross-tier FK validation + RACI / persona reconciliation	After Stage 8 inputs	RACI only under raci; basic: viewer + manager only	(same task)	references/stage-9-governance.md
10. Rules	Computed fields + validation rules (families F1-F15)	After governance	drop permission-gated rules under basic / custom	(same task)	references/stage-10-rules.md
11. Write	Frontmatter, section deltas, write the spec, close-out	After all stages pass	n/a	Match › Write the file and double-check it	references/stage-11-write.md (pre-save gates resident)
Modes B/C/D	Audit / Extend / Rebuild	Non-reconcile invocations	n/a	Match › Review the file / Match › Extend the design (its Stage 2/3 re-run is a ledger stage) / Match › Rebuild the file	references/modes-audit-extend-rebuild.md

---

Stage 3: Drive reconciliation decisions

Before any field elicitation, surface every 🛑 ambiguity and every 🟡 optional to the user via AskUserQuestion (except the questions the MUST-FIRE table below defaults while expert flow is off, and every question after the go-ahead of a fast run), through the question ledger (Task tracking, above): every widget is enumerated as a Q: task first, asked in batches of up to four per call, and completed only after its answer is written to customizations.yaml. No field work happens until every decision is recorded, which is checkable: TaskList shows no Q: task pending or in progress.

Reminder: every AskUserQuestion in this stage must follow Writing Convention 8 (plain language). Use Singular/Plural Labels, never raw table_name. Use module display names when known, never internal annotation values. Map the user's choice to an internal annotation after they pick.

🛑 MUST-FIRE rule for Stage 3 widgets (no silent auto-resolution allowed).

Which widgets it covers depends on the expert flow switch (and, in a fast run, on the go-ahead), and nothing else does:

Expert flow	MUST-FIRE widgets	Resolved by their literal default instead (no widget, no Q: task)
Off	3a, 3b.0, 3b.1, 3b.2, 3c, 3c.1, the 3d name-clash follow-up, 3e, 3f, 4.N N7, 4.N N8	the first 3d question, 4.N N2 (the table under "Expert flow" above names each default)
On	3a, 3b.0, 3b.1, 3b.2, 3c, 3c.1, 3d, 3e, 3f, and all of 4.N	none
Fast run, after the go-ahead	none: the widget does not fire	every widget, by the pick its gate's "Fast flow, after the go-ahead" line names; the logged line satisfies the check that every must-fire question was resolved

Every widget in the MUST-FIRE column for the run's flow is a mandatory user gate, not an optional prompt. The Convention 8 narration-restraint culture does NOT override them — that culture is about not narrating implementation work in chat ("Let me load the file...", "Let me classify each entity..."). It is NOT about skipping decision widgets just because a "safe default is obvious." When this stage detects a condition that calls for a widget, the widget fires. Always, in guided and expert flow. No exceptions for "the answer is obvious," "the user will pick option 1 anyway," or "I can save the user a click." The user is the decision-maker; the analyst proposes, the user confirms.

In particular:

• 3c.1 / 4.N (keep each fact once): always ask, in guided and expert flow, unless .shared_bases already holds the pair. Keeping a company twice or once is the user's call, even when one answer is obvious. (The one exception: 4.N N2 while expert flow is off, per the table above.)
• 3b.0 (catalog-owner adoption): even though option 1 is the only sensible outcome, the widget MUST fire (in guided and expert flow) so the user explicitly consents to the ownership transfer. Adoption changes the catalog state in a way the user should knowingly approve.
• 3f.1 / 3f.2 / 3f.3 / 3f.4 (drift widgets): even when option 1 ("keep live state, align spec to it") is the safe and obvious default, the widget MUST fire (in guided and expert flow) so the user knows drift was detected. (The one drift case with no widget is 3f.4's cross-primitive format change: nothing can be chosen there, so it becomes a blocker in the file and a line in the plan summary instead; the user still sees it.) Silently rewriting the spec to align to live state is a Convention 8 violation — the spec is the user's design, and changing field names / enum values / permission tiers behind their back is exactly the kind of "silent self-correction" Convention 8 forbids in its Narration restraint section ("Do not narrate self-corrections mid-flight; fix them silently" applies to implementation corrections, not spec content corrections).
• Put the recommended option first, mark its label "(Recommended)", then fire the widget — that's the correct pattern. (The tool has no pre-selected or pre-checked option; the label marker is the only way to point at the default.) The user picks it with one click per widget; they did not lose conversation context; they have explicit awareness of every adjustment to their design.

If you find yourself reasoning "the user is going to pick option 1, so I'll just do it and move on," about a widget in the MUST-FIRE column for this run's flow, that's the bug. Fire the widget anyway, in guided and expert flow. The mechanical form of this rule: every MUST-FIRE widget is a Q: task, and the stage does not end while any Q: task is pending or in progress; a decision that never became a task was skipped (in a fast run after the go-ahead, the logged pick stands in for the task).

---

Verification gates (resident: run before every write)

Stage 8 and the Stage 11 pre-save verification are kept resident because they are the correctness backbone and must never load late: every Reconcile / Extend / Rebuild write passes through them. They validate the output of Stages 5 / 6 / 7 / 9 / 10, whose authoring detail lives in the references named in the stage index above.

Stage 8: View & edit rules consistency gate

After Stages 5/6/7/9/10, run a holistic consistency pass over every owned entity:

For each entity, cross-check:

• view_permission (always <slug>:read on the entity record).
• edit_permission (<slug>:manage default, <slug>:admin for admin-tier, <slug>:<narrow> for narrow).
• select_rule (the JsonLogic from Stage 7).
• input_type_rule entries (per-field from Stage 6).
• validation_rules entries (per-entity).
• §8.1 Permissions catalog (the permission catalog).

Failure modes (all 🔴 blockers, halt save):

• A require_permission argument references a permission code not in §8.1.
• A select_rule references a column that isn't on this entity.
• A select_rule JsonLogic body contains a throwing operator (require_permission or throw_error). A select_rule compiles to a per-row FOR SELECT policy evaluated on every read; a throw aborts the entire read instead of hiding the row. Permission checks inside a select_rule must use the non-throwing has_permission (it returns false rather than throwing). See use-semantius jsonlogic.md, which calls require_permission "Wrong shape for select_rule". This is the check whose absence let require_permission ship inside a read rule.
• An entity's **Edit permission:** admin annotation but the baseline-admin row (<slug>:admin) isn't declared in §8.1.
• An override-tier view_all_<plural> / manage_all_<plural> row in §8.1 with no select_rule on the matching entity (the row-scope playbook's owner + oversight shape mints both together), or vice versa.
• A <slug>:<workflow> permission declared in §8.1 but never invoked by any require_permission rule.
• A <slug>:<workflow> permission invoked by a rule but missing from §8.1.
• A validation_rules rule references {"var": "$old.x"} where x isn't on this entity.
• Bypass-prose in a select_rule description that doesn't reconcile with the JsonLogic body.

Surface every blocker with the entity and rule name; ask the user to revise.

Stage 11 write: pre-save gates (resident)

Pre-save verification (mandatory, non-silent)

Before writing the file, run these checks. ANY failure halts save and prints a structured report:

Check	Failure surfaces as
version is "3.1"	wrong version
Every blueprint §3 entity has a Reconciliation decision	missing decisions list
No reuse-from entity carries a Fields block	over-spec list
No create-new / rename-incoming-from / promote-to-master entity is missing a Fields block	under-spec list
Every require_permission argument is in §8.1 Permissions catalog	unbound permissions list
Frontmatter carries tagline and icon_name (required, carried verbatim from the blueprint); module_kind carried verbatim when the blueprint has it, otherwise the key is omitted (never null); description / license carried when the blueprint has them (absence is not a finding); persona is REQUIRED under access_scope: raci when §9 carries a RACI matrix and MUST BE ABSENT under every other access level (see the coherence rows below)	missing / forbidden frontmatter keys
§9 governance section is present; §9.1 is populated unless access_scope: custom; §9.2 carries the blueprint's functional ownership from advanced up (a _(none: …)_ placeholder when the blueprint has none, and under basic and custom)	missing or empty §9
Frontmatter access_scope is present and equals the blueprint's value (one of custom / basic / advanced / gated / raci)	missing or changed access level
When access_scope: custom: §8.1 and §9.1 carry no permission or role rows; every owned entity has **Edit permission:** manage; no field-level permission rows and no rule gating on a permission; no RACI realization / Processes / §9.2 ownership rows; no persona frontmatter	access_scope incoherence list
When access_scope: basic: §8.1 carries exactly <slug>:read + <slug>:manage (no baseline-admin / workflow-gate / override / narrow); no §3 entity has **Edit permission:** admin or a narrow tier; §9.1 carries only viewer + manager + the single manage → read row (plus, when a based entity's base lives in another module, the cross-module family edit grant: <slug>:manage including the base's edit permission; see stage-3-shared-base.md); no RACI realization / Processes / §9.2 ownership rows; no persona frontmatter	access_scope incoherence list
When access_scope: advanced or gated: §8.1 carries <slug>:read + <slug>:manage + <slug>:admin and no workflow-gate (lifecycle) row; no RACI realization / Processes rows; no persona frontmatter. advanced: no rule gates a lifecycle transition. gated: every gated §7 state and every §8.2 create rule has a validation_rules entry requiring <slug>:admin	access_scope incoherence list
When access_scope: raci: §8.1 carries one workflow-gate (lifecycle) row per gated §7 state and per §8.2 create rule, none included in <slug>:admin (no admin → <gate> row in §9.1); the RACI realization, Processes and §9.2 ownership rows are present; every process has exactly one accountable row, and every gate is in the grant gates [...] list of exactly one accountable row (the RACI rule); persona frontmatter is present	access_scope incoherence list
RACI provenance — mechanically enforced by consistency-check.ts. When the spec carries a RACI matrix, frontmatter MUST carry raci_mode (living/documentation) AND raci_mode_source (computed-default/non-interactive; raci_mode is auto-derived from instance state, so this gate never produces user-answer), and the §9 **RACI mode:** line must match raci_mode. The checker fails the save on any missing / invalid / mismatched value.	RACI provenance missing / inconsistent
Every re-prefixed-from annotation in §8.1 names a catalog module and a verb; the verb appears on the relevant entity in §3	malformed re-prefix list
§4 rows carry fk_format and the delete behavior consumed verbatim from the blueprint's §5.1 / §5.2 / §5.3a, not re-derived. Exception: a row whose From is an is_a entity is never cascade (use restrict / clear; enforced by consistency-check.ts)	column-missing list
§6 Outbound handoffs / Inbound handoffs rows carry the transition column; for an Outbound lifecycle row (or an Inbound row whose payload is a declared §3 entity), to_state is one of that entity's workflow_state enum values	mismatched-state list
Every select_rule column references a real field on the entity	dangling columns list
No throwing operator inside any select_rule (require_permission / throw_error abort the per-row read; permission checks must use the non-throwing has_permission)	throwing-select_rule list
DDL token scan (CREATE TABLE, CREATE INDEX, ALTER TABLE, DROP, REFERENCES, ON DELETE CASCADE as SQL clause)	DDL tokens found list
Identifier-leakage scan (backticks around tokens, table_name/field_name in user-facing prose surfaces)	leakage list
Em-dash scan (—)	em-dash list
US-spelling scan (-ise / -our / -ised tokens)	British-spelling list
§2 Mermaid completeness AND correctness (every §3 entity is a node; every §4 row is an edge; every edge's direction and verb are mechanically derived from §3 relationship_label + §4 Cardinality/Kind, not hand-authored — see Stage 11 "Generate §2, never hand-author it")	diagram drift
§7.1 🔴 blockers count	block count; halt save if > 0
Adopted-entity drift resolution complete — every drift surfaced by Stage 2h has either a Stage 3f decision applied OR a §7.1 🔴 blocker documenting why it's deferred	unresolved drift list (entity, drift kind, expected resolution)
JsonLogic field references resolve — every {"var": "<token>"} in every computed_fields, validation_rules, input_type_rules, and select_rule references a field that exists on the relevant entity (either declared in the spec's Fields block, or carried from live state via Stage 2h for adopted/reused entities, or known to be a Semantius built-in column like id, created_at)	dangling JsonLogic var list (entity, rule name, unresolved token)
JsonLogic permission references resolve — every require_permission(<code>) and every has_permission(<code>) argument in JsonLogic resolves to a permission row in §8.1 OR a known platform-level permission	unbound permission code list
JsonLogic enum-value references resolve — every literal value compared against an enum-typed field in JsonLogic exists in that field's enum_values as a value, never a label (after any Stage 3f.2 merge)	unknown enum literals list
Enum entries well-formed — every §5 bullet and hint sub-bullet follows the §5 grammar in semantic-spec-template.md; every entry carries a label and a color, and labels and hints follow stage-4-fields.md ("Enum values, labels and hints"); each Notes enum_values: set equals its §5 values; every default: is a value, never a label (enforced by consistency-check.ts)	enum list (entity, field, issue)
Every enum entry's icon checked — every §5 entry carries either - icon: `<name>` or - icon: none <!-- finder: <query>, …: no fit --> naming the finder queries tried (stage-4-fields.md rule 3); an entry with no icon line is unchecked and blocks the save, it never means that no icon fits (enforced by consistency-check.ts --require-icons)	unchecked entry list (entity, field, value)
Icons exist — every §5 icon and the frontmatter icon_name pass bun "<skill-folder>/../use-semantius/references/lucide-icon-checker.ts" <name…> (a URL always passes)	unknown icon list
Label column is text — the §3 row named by **Label column:** (and marked `label_column`) has Format string, never enum, multiline, a FK or any other format: the platform creates it as text and locks its format (90219) (enforced by consistency-check.ts)	label list (entity, field, format)
JsonLogic rename cascade complete — for every rename recorded in Stage 3f.1 / 3f.3, grep the assembled spec text for the old token; the count must be zero	partial rename list (token, line numbers where stale references remain)
No enum value would orphan live records — for every adopted entity, no value (compared by value; a label change orphans nothing) in live_distinct_enum_values_in_use is missing from the spec's final enum_values for that field UNLESS a §7.1 🔴 blocker documents the required pre-deploy data migration	enum drop list (entity, field, dropped value, live record count)
No cross-primitive format change without §7.1 🔴 blocker	format-change list (entity, field, live format, spec format)
Permission tier downgrade has user consent (Stage 3f.3 option 2 explicitly picked)	unconfirmed downgrade list (entity, live tier, spec tier)
Validation-rule identity: every validation_rules entry carries a name (snake_case, unique within the entity) and a code matching ^99[0-9]{3}$ (class-99 SQLSTATE; the platform rejects any other shape with 90905), assigned sequentially from 99001 in §3 entity order then array order	rule-identity list (entity, rule name, issue)
Key types valid and not changed on a live entity (Stage 9 rule 5): every **Key type:** is bigint / text / uuid / typeid / is_a / has_a; typeid and is_a have a well-formed **Key prefix:** unique in the spec and the live catalog, any other type has none; no entity that exists live carries a key type (or **Based on:**) different from its live one unless a §7.1 🔴 rebuild blocker documents it	key-type list (entity, issue)
Families valid (Stage 9 rule 5): every is_a / has_a entity has a **Based on:** naming a declared entity whose key type fits (live-checked when reused); no **Label column:** / **Label parent:** / **Order column:** on a based entity; its Fields list only its own fields; no _process_gates_ row names it; no table_name ends in _ext and <table_name>_ext is free live; roles that write it also write its base (a cross-module edit grant when the base lives elsewhere). The file-level part is enforced by consistency-check.ts	family list (entity, issue)

Mechanical consistency gate (mandatory — run it, do not eyeball it). The §2 Mermaid-completeness row above and the entity-set / label / reference reconciliation are enforced by the same deterministic checker the architect ships (it handles both blueprints and specs). After writing the candidate spec, run it and require a clean exit:

# <skill-folder> = the directory this skill's SKILL.md was read from (absolute path; works for plugin and workspace installs alike)
bun "<skill-folder>/../semantius-architect/references/consistency-check.ts" --require-icons "semantius/specs/<slug>-semantic-spec.md"

For a spec it byte-compares: the frontmatter entities: list ⟺ §2 Table name ⟺ §3 sub-section headings (the entity set, strict 1:1); §2 Singular label ⟺ the §3 heading singular label (per entity); that every §4 / §5 / §8.2 / mermaid reference resolves to a declared entity; and that every §2 mermaid edge's direction + verb agrees with what §3 relationship_label + §4 Cardinality/Kind derive (a parent-kind row is always drawn as a bare arrow with no verb, per the junction convention; every other row's verb comes from §3, never invented at diagram time). It is content-agnostic on prose — it never judges language or casing, only that every occurrence of a name (and now every diagram edge) agrees with its source. A non-zero exit prints the exact entity and the disagreeing locations; fix every reported line and re-run until exit 0 before narrating the close-out. Do not substitute reading for running it.

The drift / JsonLogic block of checks is the analyst's safety net against modeler-time halts. Any failure means the spec would be rejected by the modeler at deploy time anyway, so failing now (in the analyst, where the user has full context) is strictly better than failing later (in the modeler, where the user has lost the conversational thread). Every check above corresponds to a modeler refusal condition documented in ../semantius-modeler/SKILL.md and ../../docs/architecture.md §6 failure modes.

Narrating this phase (silent on success). Everything above, the checks table, the mechanical consistency gate, the scans, the rule-block / JsonLogic validation, is internal QA. Per Narration restraint, the user sees no chat text for the phase, never the checker / scans / rule blocks by name, never an enumerated pass count on success, and never a narrated re-run when a check has to be re-invoked (a tooling hiccup like swallowed output is fixed silently, not reported). Surface output only when a check fails, and then name, in plain language, what the user must decide or fix.

---

Closing message

After a successful spec write in Reconcile or Extend mode, narrate the close-out (this section is the canonical rule; stage-11-write.md defers here). The shape depends on invocation mode:

Admin-orchestrated (handoff header has Run context:):

Wrote semantius/specs/<slug>-semantic-spec.md. Summary: new, adopted from , skipped, reusing platform built-ins.

One line; no "next step" hint in admin-orchestrated mode (the admin narrates whether to run the modeler or stop, per the run's deploy flag, and uses this summary to compose its final report). In guided and expert flow this line is always sent: the file name is the user's record of what was produced, and it is the analyst's own result line, not admin hand-off narration. In a fast run there is no close-out line: complete the task and let the admin move on.

Stand-alone (no handoff header):

Done. Wrote the design to semantius/specs/<slug>-semantic-spec.md (). When you're ready, ask me to deploy it.

Never emit raw reconciliation_summary: {...} curly-brace data, "Tell the admin to invoke the modeler," or any skill-name references. Use the plain-English translation table from §3g (create-new → "new", promote-to-master → "adopted from ", reuse-from → "reusing existing from ", dropped → "skipped", reuse-from semantius_builtin.* → "reusing platform built-in").

After Audit mode: print the structured report; no file write; suggest Extend or manual fix.

After Rebuild mode: same shape as Reconcile but with a diff-summary preamble.

---

Scope boundaries

The spec deliberately excludes UI layouts, API endpoint design, analytics / dashboards, workflows beyond lifecycle states and permissions, integration plumbing (auth flows, queue topology, retry policy), and anything platform-specific outside Semantius primitives. These belong in other skills downstream.

---

Tone and collaboration style

Lead with the structured output (tables, JSON, plans). Prose between sections stays brief — orient the user, ask one question at a time, confirm before moving on. Match the user's vocabulary; if they say "client" call it clients, not customers. Don't argue minor stylistic choices; reserve pushback for genuine correctness issues. When unsure, ask one specific question rather than guess (in a fast run after the go-ahead, take the most conservative assumption and log it instead; ../semantius-admin/references/fast-flow.md, section 4.3).

Reference material

• ../semantius-architect/references/semantic-blueprint-template.md: the blueprint format, this skill's input. Read it at Stage 1 when a blueprint section's structure or grammar is in doubt.